diff --git a/docs/zh/contribute/_toc.yaml b/docs/zh/contribute/_toc.yaml index 4a6a8fdaabeb385daa28af14c46b845d846a1158..36349a7c4fc41ff1818ab11ba4c8d838295fcc20 100644 --- a/docs/zh/contribute/_toc.yaml +++ b/docs/zh/contribute/_toc.yaml @@ -11,3 +11,5 @@ sections: href: ./documentation_writing_specifications.md - label: 文档发布流水线门禁 href: ./ci_rules.md + - label: 文档开发工具 + href: ./doc_tools.md diff --git a/docs/zh/contribute/doc_tools.md b/docs/zh/contribute/doc_tools.md new file mode 100644 index 0000000000000000000000000000000000000000..69798f7fc8869de3b769c7b754da7f9e12e20d52 --- /dev/null +++ b/docs/zh/contribute/doc_tools.md @@ -0,0 +1,251 @@ +# Doc Tools + +本插件集成了markdownlint、链接失效等多种常见文档问题的自动化检测修复功能，同时提供文档预览等功能，旨在提升文档开发体验。 + +## 安装 + +在 Visual Studio Code 中搜索插件并安装： + +![Doc Tools Installation](figures/install_doctools.png) + +## 功能总览 + +| 名称 | 功能 | 执行时机 | 提示级别 | 提示语 | +| -----| ----| ----------| -------- | -------| +| [Markdown Lint](#markdown-lint) | Markdown 语法检查 | md 文件打开、保存、停止修改 1s 后 | warning | 具体的 markdownlint 规则 | +| [Tag Closed Check](#tag-closed-check) | Html 标签闭合检查 | md 文件打开、保存、停止修改 1s 后 | error | Unclosed html tag: ${tag} | +| [Link Validity Check](#link-validity-check) | 链接有效性检查（包含：1. 内链；2. 外链） | md 文件打开、 保存、停止修改 1s 后 | warning | Invalid link: ${link} | +| [Resource Existence Check](#resource-existence-check) | 资源是否存在检查（包含：1. 内链；2. 外链） | md 文件打开、保 存、停止修改 1s 后 | warning | Non-existent resource: ${resource} | +| [Toc Check](#toc-check) | 目录文件检查（1. 目录中引用的文件需要存在；2. 每一篇 md 文档都需要在目录中进行维护） | \_toc.yaml 打开、保 存、停止修改 1s 后，md 文件打开后会检测是否加入 \_toc.yaml | error | Non-existent doc in toc: ${doc} | +| CodeSpell Check | 单词拼写检查 | md 文件打开、保存、停止修改 1s 后 | info | CodeSpell warning: ${code} | +| [目录生成](#目录生成) | 自动生成`_toc.yaml` | 点击**生成目录**按钮 | 不涉及 | 不涉及 | +| [文档预览](#文档预览) | 文档实时预览 | 点击**预览功能**按钮 | 不涉及 | 不涉及 | + +### 全局配置说明 + +插件支持以下配置项（可在 VSCode 设置中搜索 `docTools.scope` 或通过 `settings.json` 进行配置）： + +- `docTools.scope` + - 类型：`boolean` + - 说明：是否检查范围仅限于 `docs/zh` 和 `docs/en` 目录 + - 默认：`false` + +#### 全局配置示例 + +```json +{ + "docTools.scope": false // 启用检查范围仅限于 docs/zh 和 docs/en 目录，默认检查项目全局文档 +} +``` + +## Markdown Lint + +基于 `markdownlint v0.12.0` 版本实现，帮助用户规范 Markdown 文档格式。 + +![Markdown Lint](public_sys_resources/lint-markdown.gif) + +### 功能介绍 + +- 自动检测 Markdown 文件中的[格式问题](./markdownlint_rules.md)，如标题格式、列表缩进、空行等； +- 可通过配置项灵活启用或禁用 lint 功能，并支持自定义 lint 规则，满足不同团队或个人的文档规范需求。 + +### 使用方法 + +1. 安装并启用本插件，打开 Markdown 文件（`.md`），插件会自动对文件内容进行 lint 检查； +2. 检查结果会以警告（Warning）的形式在编辑器中高亮显示，可在“问题”面板，或将光标悬停在警告标记上，查看详细的规则说明和建议； + +#### 默认规则 + +插件内置一套 markdownlint 默认规则（见 `config/markdownlint`），可根据实际需求通过配置覆盖。 + +### 配置说明 + +插件支持以下配置项（可在 VSCode 设置中搜索 `docTools.markdownlint`或通过`settings.json`进行配置）： + +- `docTools.markdownlint` + + - 类型：`boolean` + - 说明：是否启用 Markdown lint 功能 + - 默认：`true` + +- `docTools.markdownlint.config` + - 类型：`object` + - 说明：自定义 markdownlint 配置对象。若未设置，则使用插件内置的默认规则 + +#### 配置示例 + +```json +{ + "docTools.markdownlint": true, // 是否开启功能 + "docTools.markdownlint.config": { + "MD013": false, // 禁用行长度限制 + "MD041": true // 启用标题必须为一级标题 + } +} +``` + +## Tag Closed Check + +检查 Markdown 文件中的 HTML 标签是否正确闭合，帮助用户避免因标签未闭合导致的渲染或语法错误。 + +![tag closed check](public_sys_resources/check-tag-closed.gif) + +### 功能介绍 + +- 自动检测 Markdown 文件中的 [HTML 标签闭合问题](./ci_rules.md#tag-closed-check)； +- 支持快速修复功能，帮助用户一键修正标签闭合和转义问题； +- 支持通过配置项灵活启用或禁用该功能。 + +### 使用方法 + +1. 安装并启用本插件，打开 Markdown 文件（`.md`），自动检查文件内容有效性； +2. 检查结果会以错误（Error）的形式在编辑器中高亮显示，可在“问题”面板，或将光标悬停在错误标记处，查看错误详情； +3. 可通过 VSCode 提供的 Quick Fix（快速修复）功能，点击灯泡图标或按下快捷键（通常为 `Cmd+.` 或 `Ctrl+.`），一键修复标签问题。 + +### 快速修复说明 + +- “转义字符替换”：自动将错误的转义标签替换为正确的 HTML 实体或标签； +- “闭合标签”：自动为未闭合的标签补全闭合部分。 + +### 配置说明 + +插件支持以下配置项（可在 VSCode 设置中搜索`docTools.check.tagClosed`或通过`settings.json`进行配置）： + +- `docTools.check.tagClosed` + - 类型：`boolean` + - 说明：是否启用 HTML 标签闭合检查 + +#### 配置示例 + +```json +{ + "docTools.check.tagClosed": true +} +``` + +## Link Validity Check + +检查 Markdown 文档中的链接有效性，帮助用户及时发现失效或错误的链接，提升文档质量。 + +![Link Validity Check](public_sys_resources/check-link-validity.gif) + +### 功能介绍 + +- 自动扫描 [Markdown 文档中的所有链接](./ci_rules.md#link-validity-check)，包括以下三种格式： + - `[文本](链接)` 形式的标准 Markdown 链接 + - `` 形式的裸链接 + - `` 形式的 HTML 链接 +- 支持跳过锚点链接（如 `#section`），并自动忽略链接中的锚点部分，仅校验主链接地址； +- 支持通过配置项灵活启用或禁用该功能。 + +### 使用方法 + +1. 安装并启用插件后，打开任意 Markdown 文件（`.md`），自动检测所有链接的有效性； +2. 无效链接会以警告（Warning）的形式在编辑器中高亮显示，可在“问题”面板中，或将光标悬停在警告标记处，查看错误详情。 + +### 注意事项 + +- 插件仅检测链接的格式和可达性，不保证目标内容的正确性； +- 某些私有或受限网络下的链接，可能因网络原因被误判为无效； +- 对于本地文件链接，需确保路径正确且文件存在。 + +## Resource Existence Check + +检查 Markdown 文件中的资源链接（如图片、视频等）是否存在，帮助用户及时发现无效或丢失的资源引用。 + +![Resource Existence Check](public_sys_resources/resource_check.gif) + +### 功能介绍 + +- 自动检测 Markdown 文件中的图片、视频等[资源链接是否有效](./ci_rules.md#resource-existence-check)，包括 Markdown 语法和 HTML 标签（如 ``、``、`