diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 1fec684..97b6389 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -2,7 +2,7 @@ import { defineConfig } from 'vitepress'
// https://vitepress.dev/reference/site-config
export default defineConfig({
- base: "/PSCompletions",
+ base: "/PSCompletions/",
title: "PSCompletions(psc)",
locales: {
"en-US": {
@@ -19,6 +19,36 @@ export default defineConfig({
themeConfig: {
socialLinks: [
{ icon: 'github', link: 'https://github.com/abgox/PSCompletions' }
- ]
- }
+ ],
+ search: {
+ provider: 'local',
+ options: {
+ locales: {
+ "zh-CN": {
+ translations: {
+ button: {
+ buttonText: '搜索文档',
+ buttonAriaLabel: '搜索文档'
+ },
+ modal: {
+ displayDetails: "显示详细列表",
+ noResultsText: '无法找到相关结果',
+ resetButtonTitle: '清除查询条件',
+ footer: {
+ selectText: '选择',
+ navigateText: '切换',
+ closeText: "关闭"
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ outline: "deep",
+ footer: {
+ message: 'Released under the MIT License.',
+ copyright: 'Copyright © 2023-present abgox'
+ }
+ },
})
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index 5fee056..9a86e5a 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -13,7 +13,11 @@ export default {
},
enhanceApp() {
try {
+ let langs = ['en-US', 'zh-CN']
let lang = navigator.language
+ if (!langs.includes(lang)) {
+ lang = langs[0]
+ }
if (/\/PSCompletions\/?$/.test(location.pathname)) {
location.href += lang
}
diff --git a/docs/en-US/command/index.md b/docs/en-US/command/index.md
new file mode 100644
index 0000000..7799f17
--- /dev/null
+++ b/docs/en-US/command/index.md
@@ -0,0 +1,11 @@
+---
+title: About PSCompletions(psc) command
+next:
+ text: About PR (Pull Request)
+ link: '../contribute/index.md'
+---
+
+- Waiting...
+ - You can trigger completion by running `psc`, then learn about them by completion tip.
+ - View the README file of PSCompletions.
+ - Enter 'psc' and press 'Enter' to print some module information
diff --git a/docs/en-US/completion/index.md b/docs/en-US/completion/index.md
new file mode 100644
index 0000000..1864e0d
--- /dev/null
+++ b/docs/en-US/completion/index.md
@@ -0,0 +1,155 @@
+---
+title: About the structure of json file
+next:
+ text: About PR (Pull Request)
+ link: '../contribute/index.md'
+---
+
+# About the structure of json file
+
+```json
+{
+ "root": [],
+ "options": [],
+ "common_options": [],
+ "info": {},
+ "config": []
+}
+```
+
+- The json file uses a schema structure to ensure that the json content is correct and complete.
+ - You can learn about these properties by hovering over the prompts
+- In fact, it is very simple, you can refer to the existing json file.
+
+## Properties
+
+### 1. `root`
+
+- The type of value: array
+- The most core attribute (usually)
+
+ - Each item in the array is an object
+ - Object available attribute: `name`(required)、`alias`、`symbol`、`next`、`options`、`tip`
+ - In vscode, with schema, it's easy to understand.
+ - The values of `next` and `options` are also arrays, almost identical to `root`.
+ - Difference: The `options` attribute is not allowed in `options`.
+ - In most cases, you don't need to think about defining `symbol` because `symbol` will automatically add some value to the symbols depending on context
+ - When the completion item has `next`, `SpaceTab` is automatically added.
+ - The `symbol` attribute in `options` automatically adds the `OptionTab`.
+ - Some Cases where `Symbol` needs to be added manually.
+
+ - When several preset values are needed in `options`
+
+ - ```json
+ {
+ "name": "reset",
+ "options": [
+ {
+ "name": "--soft",
+ "symbol": ["WriteSpaceTab", "SpaceTab"]
+ }
+ ]
+ }
+ ```
+
+ - When completion uses `hooks` to add some dynamic completion items.
+ - ```json
+ {
+ "name": "rm",
+ "symbol": "SpaceTab"
+ }
+ ```
+
+### 2. `options`
+
+- The type of value: array
+- Same as the `options` for each item in `root`.
+- ```json
+ {
+ "options": [
+ {
+ "name": "--version",
+ "alias": ["-v"],
+ "tip": "Show current version"
+ }
+ ]
+ }
+ ```
+
+### 3. `common_options`
+
+- The type of value: array
+- All options are displayed at all times.
+- ```json
+ {
+ "options": [
+ {
+ "name": "--help",
+ "alias": ["-h"],
+ "tip": "Show help."
+ }
+ ]
+ }
+ ```
+
+### 4. `info`
+
+- The type of value: object
+- All values defined can be obtained elsewhere with the following syntax.
+- ```json
+ // {{ $info.xxx }}
+ // {{ $json.xxx }} $json is the object of the entire json file.
+ {
+ "root": [
+ {
+ "name": "test",
+ "tip": "{{ $info.test_tip }}"
+ },
+ {
+ "name": "abc",
+ "tip": "{{ $json.info.abc_tip }}"
+ }
+ ],
+ "info": {
+ "test_tip": "this is test content.",
+ "abc_tip": "abcdefg"
+ }
+ }
+ ```
+
+### 5. `config`
+
+- The type of value: array
+- Define some special configurations for completion.(e.g. `git`)
+- ```json
+ "config": [
+ {
+ "name": "disable_hooks",
+ "value": 0,
+ "values": [
+ 1,
+ 0
+ ],
+ "tip": [
+ "Set whether to disable hooks. Default to 0.\n",
+ "Hooks in git are mainly used to parse commit information, branch information, etc., and then dynamically add them to some completions (such as reset,checkout,branch, etc.)\n",
+ "For example, enter <@Magenta>git reset<@Blue>, press <@Magenta>Space<@Blue> and <@Magenta>Tab<@Blue>, and you can get the resolved commit completions.\n",
+ "If you don't need it, you can disable it, which will improve the loading speed of the completion.\n",
+ "If you disable it, the <@Magenta>max_commit<@Blue> configuration will also be invalid."
+ ]
+ },
+ {
+ "name": "max_commit",
+ "value": 20,
+ "values": [
+ -1,
+ 20
+ ],
+ "tip": [
+ "The maximum number that can be parsed for a project commit.\n",
+ "If it is <@Magenta>-1<@Blue>, all commits will be parsed.\n",
+ "If there are a large number of project commits, setting <@Magenta>-1<@Blue> will affect the loading speed of the completion."
+ ]
+ }
+ ]
+ ```
diff --git a/docs/en-US/contribute/index.md b/docs/en-US/contribute/index.md
new file mode 100644
index 0000000..9232fb1
--- /dev/null
+++ b/docs/en-US/contribute/index.md
@@ -0,0 +1,32 @@
+---
+title: About PR (Pull Request)
+prev:
+ text: About the structure of json file
+ link: '../completion/index.md'
+---
+
+# About PR (Pull Request)
+
+1. Prerequisite: You should read [About the structure of completion json file](../completion/index.md) first.
+2. You should fork [PSCompletions](https://github.com/abgox/PSCompletions), and clone to your machine.
+3. After Changing, you should commit and create the `PR`.
+
+## 1. Update the content of completion json file
+
+- Patch some tips of the completion.(`tip` attributes)
+- Add some missing commands for the completion.
+
+## 2. Add language
+
+1. In the `completions` directory, select the language you want to add.
+2. Add the language identifier to the language in the `config.json` file.
+3. Add a json file with the same name as the language identifier in the `language` directory.
+ - You can copy the original json file and rename it.
+4. Translate the contents of the `tip` attribute.
+
+## 3. Add a new completion
+
+1. Run it in the project root directory. `.\script\create.ps1`
+2. Follow the prompts.
+3. Modify the new completion.
+4. Add this completion to the value of the `list` property in `completions.json` in the project root directory.
diff --git a/docs/en-US/index.md b/docs/en-US/index.md
index cecfe49..281ed43 100644
--- a/docs/en-US/index.md
+++ b/docs/en-US/index.md
@@ -1,5 +1,25 @@
---
layout: home
+hero:
+ name: PSCompletions
+ tagline: A completion manager for better and simpler use completions in PowerShell.
+ actions:
+ - theme: brand
+ text: About module command
+ link: en-US/command
+ - theme: alt
+ text: About the structure of json file
+ link: en-US/completion
+ - theme: alt
+ text: About PR (Pull Request)
+ link: en-US/contribute
+features:
+ - title: Multi-language
+ details: Switch between languages(zh-CN,en-US...) freely.
+ - title: Sort dynamically
+ details: Sort completion tab dynamically by frequency of use.
+ - title: New Completions menu
+ details: The module provides a more useful completion menu
+ - title: Base-in-json
+ details: Define completion data from json files.
---
-
-waiting...
diff --git a/docs/zh-CN/command/index.md b/docs/zh-CN/command/index.md
new file mode 100644
index 0000000..1471890
--- /dev/null
+++ b/docs/zh-CN/command/index.md
@@ -0,0 +1,11 @@
+---
+title: 模块命令
+next:
+ text: 关于贡献
+ link: '../contribute/index.md'
+---
+
+- 等待补充...
+ - 可以使用 `psc` 触发补全，通过补全提示信息了解模块命令
+ - 通过项目的 README 了解
+ - 输入 `psc` 后 按下 `enter`，将会打印一些模块信息
diff --git a/docs/zh-CN/completion/index.md b/docs/zh-CN/completion/index.md
new file mode 100644
index 0000000..3073f13
--- /dev/null
+++ b/docs/zh-CN/completion/index.md
@@ -0,0 +1,156 @@
+---
+title: 关于补全的 json 文件结构
+next:
+ text: 关于贡献
+ link: '../contribute/index.md'
+---
+
+# 关于补全的 json 文件结构
+
+```json
+{
+ "root": [],
+ "options": [],
+ "common_options": [],
+ "info": {},
+ "config": []
+}
+```
+
+- 以上是 json 文件的总体结构
+- json 文件使用了 schema 架构来保证 json 内容的正确和完整
+ - 你可以通过悬浮提示了解属性
+- 其实很简单，多看几个已有的 json 文件，就能看懂了
+
+## 属性详解
+
+### 1. `root`
+
+- 值类型: 数组
+- 最核心的一个属性(通常情况下)
+
+ - 数组中的每一项是一个对象
+ - 对象可用属性: `name`(必需)、`alias`、`symbol`、`next`、`options`、`tip`
+ - 不多解释，在 vscode 中，配合 schema，很容易理解
+ - 其中，`next` 和 `options` 的值也是一个数组，几乎和 `root` 相同
+ - 不同点: `options` 中不允许添加 `options` 属性(就是不能在选项中嵌套选项)
+ - 在大多数情况，你不需要考虑定义 `symbol`，因为 `symbol` 会根据上下文，自动添加一些值，用于显示符号
+ - 当补全项有 `next` 时，会自动添加 `SpaceTab`
+ - 在 `options`中的 `symbol` 属性会自动添加 `OptionTab`
+ - 需要手动添加 `Symbol` 的情况
+
+ - 当 `options` 中的选项类补全需要有几个预设值时
+
+ - ```json
+ {
+ "name": "reset",
+ "options": [
+ {
+ "name": "--soft",
+ "symbol": ["WriteSpaceTab", "SpaceTab"]
+ }
+ ]
+ }
+ ```
+
+ - 当补全使用到了 `hooks` 添加了动态补全项时
+ - ```json
+ {
+ "name": "rm",
+ "symbol": "SpaceTab"
+ }
+ ```
+
+### 2. `options`
+
+- 值类型: 数组
+- 和 `root` 中的每一项的 `options` 相同
+- ```json
+ {
+ "options": [
+ {
+ "name": "--version",
+ "alias": ["-v"],
+ "tip": "显示当前版本"
+ }
+ ]
+ }
+ ```
+
+### 3. `common_options`
+
+- 值类型: 数组
+- 这里面的所有选项在任何时候都会显示
+- ```json
+ {
+ "options": [
+ {
+ "name": "--help",
+ "alias": ["-h"],
+ "tip": "显示帮助信息"
+ }
+ ]
+ }
+ ```
+
+### 4. `info`
+
+- 值类型: 对象
+- 定义的所有值，可以在其他地方通过以下语法获取
+- ```json
+ // {{ $info.xxx }}
+ // {{ $json.xxx }} $json 是整个json文件形成的对象
+ {
+ "root": [
+ {
+ "name": "test",
+ "tip": "{{ $info.test_tip }}"
+ },
+ {
+ "name": "abc",
+ "tip": "{{ $json.info.abc_tip }}"
+ }
+ ],
+ "info": {
+ "test_tip": "这是一个测试内容",
+ "abc_tip": "abcdefg"
+ }
+ }
+ ```
+
+### 5. `config`
+
+- 值类型: 数组
+- 定义补全的特殊配置(以 `git` 的特殊配置为例)
+- ```json
+ "config": [
+ {
+ "name": "disable_hooks",
+ "value": 0,
+ "values": [
+ 1,
+ 0
+ ],
+ "tip": [
+ "设置是否禁用 hooks，默认为 0 表示不禁用\n",
+ "git 中的 hooks 主要用于解析 commit 信息、分支信息等, 然后动态添加到一些补全中(如 reset,checkout,branch 等)\n",
+ "如: git reset 后可以获取到解析出来的 commit，快速补全\n",
+ "如果你不需要它，你可以禁用它，这样可以提高补全的加载速度\n",
+ "如果禁用它，那么 <@Magenta>max_commit<@Blue> 配置也将无效"
+ ]
+ },
+ {
+ "name": "max_commit",
+ "value": 20,
+ "values": [
+ -1,
+ 20
+ ],
+ "tip": [
+ "可以为当前项目解析的 commit 的最大数量\n",
+ "如果设置为 <@Magenta>-1<@Blue>, 会解析所有的 commit\n",
+ "如果项目 commit 数量较多，设置为 <@Magenta>-1<@Blue> 对补全加载的速度会有不小的影响"
+ ]
+ }
+ ]
+ ```
diff --git a/docs/zh-CN/contribute/index.md b/docs/zh-CN/contribute/index.md
new file mode 100644
index 0000000..1930c94
--- /dev/null
+++ b/docs/zh-CN/contribute/index.md
@@ -0,0 +1,35 @@
+---
+title: 关于 PR (Pull Request)
+prev:
+ text: 关于补全的 json 文件结构
+ link: '../completion/index.md'
+---
+
+# 关于 PR (Pull Request)
+
+1. 前提: 你应该先阅读 [关于补全的 json 文件结构](../completion/index.md)
+2. 你应该 fork [PSCompletions 仓库](https://github.com/abgox/PSCompletions)，克隆到本地进行修改
+3. 只要到补全文件进行了修改，都需要更新其目录下的 `guid.txt` 文件
+ - 你可以手动运行 `New-Guid` 生成，将值填入此文件中
+ - 也可以直接运行 `.\script\updateGuid.ps1`，在弹出的 PowerShell 列表框中，选择此补全，并应用修改即可
+4. 修改完成后，提交并创建 `PR`
+
+## 1. 更新 json 文件内容
+
+- 完善补全的一些提示信息(`tip` 属性)
+- 添加补全的一些缺失的命令
+
+## 2. 添加语言
+
+1. 在项目的 `completions` 目录中找到你想要添加语言的补全
+2. 在其目录下的 `config.json` 文件中的 `language` 属性里添加像 `zh-CN` 这样的语言标识符
+3. 在 `language` 目录下添加与语言标识符同名的 json 文件
+ - 你可以将原有的一个 json 文件直接复制，改名即可
+4. 翻译其中的 `tip` 属性的内容即可
+
+## 3. 添加一个全新的命令补全
+
+1. 在项目根目录下运行 `.\script\create.ps1`
+2. 根据提示进行操作
+3. 修改新创建的补全
+4. 最后还需要在项目根目录的 `completions.json` 中的 `list` 属性值中添加此补全
diff --git a/docs/zh-CN/index.md b/docs/zh-CN/index.md
index 05b8aa8..c94e0f2 100644
--- a/docs/zh-CN/index.md
+++ b/docs/zh-CN/index.md
@@ -1,5 +1,25 @@
---
layout: home
+hero:
+ name: PSCompletions
+ tagline: 一个补全管理模块，它能让你在 PowerShell 中更简单、更方便地使用命令补全。
+ actions:
+ - theme: brand
+ text: 关于模块的命令
+ link: zh-CN/command
+ - theme: alt
+ text: 关于补全的 json 文件结构
+ link: zh-CN/completion
+ - theme: alt
+ text: 关于 PR (Pull Request)
+ link: zh-CN/contribute
+features:
+ - title: 多语言
+ details: 支持多种语言，你可以随意在这些语言中切换
+ - title: 动态排序
+ details: 补全会根据命令输入的历史纪录动态排序，让你能够更快、更舒适的获取命令补全
+ - title: 灵活的补全菜单
+ details: 模块提供了一个补全菜单，它比 PowerShell 自带的补全菜单更方便、更好用
+ - title: 补全基于 json
+ details: 模块通过 json 文件去定义补全的数据
---
-
-待完善...