From f66f9653baf9b47b1ed347315f51bd13c8647ff5 Mon Sep 17 00:00:00 2001
From: abgox <abgohxf@outlook.com>
Date: Wed, 22 May 2024 18:29:55 +0800
Subject: [PATCH] update

---
 docs/.vitepress/config.mts     |  36 +++++++-
 docs/.vitepress/theme/index.ts |   4 +
 docs/en-US/command/index.md    |  11 +++
 docs/en-US/completion/index.md | 155 ++++++++++++++++++++++++++++++++
 docs/en-US/contribute/index.md |  32 +++++++
 docs/en-US/index.md            |  24 ++++-
 docs/zh-CN/command/index.md    |  11 +++
 docs/zh-CN/completion/index.md | 156 +++++++++++++++++++++++++++++++++
 docs/zh-CN/contribute/index.md |  35 ++++++++
 docs/zh-CN/index.md            |  24 ++++-
 10 files changed, 481 insertions(+), 7 deletions(-)
 create mode 100644 docs/en-US/command/index.md
 create mode 100644 docs/en-US/completion/index.md
 create mode 100644 docs/en-US/contribute/index.md
 create mode 100644 docs/zh-CN/command/index.md
 create mode 100644 docs/zh-CN/completion/index.md
 create mode 100644 docs/zh-CN/contribute/index.md

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 <a href="https://github.com/abgox/PSCompletions/blob/main/LICENSE">MIT License</a>.',
+      copyright: 'Copyright © 2023-present <a href="https://github.com/abgox">abgox</a>'
+    }
+  },
 })
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 文件去定义补全的数据
 ---
-
-待完善...