Doc Tools ​

本插件集成了markdownlint、链接失效等多种常见文档问题的自动化检测修复功能，同时提供文档预览等功能，旨在提升文档开发体验。

安装 ​

在 Visual Studio Code 中搜索插件并安装：

功能总览 ​

全局配置说明 ​

插件支持以下配置项（可在 VSCode 设置中搜索 docTools.scope 或通过 settings.json 进行配置）：

• docTools.scope
  • 类型：boolean
  • 说明：是否检查范围仅限于 docs/zh 和 docs/en 目录
  • 默认：false

全局配置示例 ​

{
  "docTools.scope": false // 启用检查范围仅限于 docs/zh 和 docs/en 目录，默认检查项目全局文档
}

Markdown Lint ​

基于 markdownlint v0.12.0 版本实现，帮助用户规范 Markdown 文档格式。

功能介绍 ​

• 自动检测 Markdown 文件中的格式问题，如标题格式、列表缩进、空行等；
• 可通过配置项灵活启用或禁用 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 配置对象。若未设置，则使用插件内置的默认规则

配置示例 ​

{
  "docTools.markdownlint": true, // 是否开启功能
  "docTools.markdownlint.config": {
    "MD013": false, // 禁用行长度限制
    "MD041": true // 启用标题必须为一级标题
  }
}

Tag Closed Check ​

检查 Markdown 文件中的 HTML 标签是否正确闭合，帮助用户避免因标签未闭合导致的渲染或语法错误。

功能介绍 ​

• 自动检测 Markdown 文件中的 HTML 标签闭合问题；
• 支持快速修复功能，帮助用户一键修正标签闭合和转义问题；
• 支持通过配置项灵活启用或禁用该功能。

使用方法 ​

1. 安装并启用本插件，打开 Markdown 文件（.md），自动检查文件内容有效性；
2. 检查结果会以错误（Error）的形式在编辑器中高亮显示，可在“问题”面板，或将光标悬停在错误标记处，查看错误详情；
3. 可通过 VSCode 提供的 Quick Fix（快速修复）功能，点击灯泡图标或按下快捷键（通常为 Cmd+. 或 Ctrl+.），一键修复标签问题。

快速修复说明 ​

• “转义字符替换”：自动将错误的转义标签替换为正确的 HTML 实体或标签；
• “闭合标签”：自动为未闭合的标签补全闭合部分。

配置说明 ​

插件支持以下配置项（可在 VSCode 设置中搜索docTools.check.tagClosed或通过settings.json进行配置）：

• docTools.check.tagClosed
  • 类型：boolean
  • 说明：是否启用 HTML 标签闭合检查

配置示例 ​

{
  "docTools.check.tagClosed": true
}

Link Validity Check ​

检查 Markdown 文档中的链接有效性，帮助用户及时发现失效或错误的链接，提升文档质量。

功能介绍 ​

• 自动扫描 Markdown 文档中的所有链接，包括以下三种格式：
  • [文本](链接) 形式的标准 Markdown 链接
  • <http://example.com> 形式的裸链接
  • <a href="链接"> 形式的 HTML 链接
• 支持跳过锚点链接（如 #section），并自动忽略链接中的锚点部分，仅校验主链接地址；
• 支持通过配置项灵活启用或禁用该功能。

使用方法 ​

1. 安装并启用插件后，打开任意 Markdown 文件（.md），自动检测所有链接的有效性；
2. 无效链接会以警告（Warning）的形式在编辑器中高亮显示，可在“问题”面板中，或将光标悬停在警告标记处，查看错误详情。

注意事项 ​

• 插件仅检测链接的格式和可达性，不保证目标内容的正确性；
• 某些私有或受限网络下的链接，可能因网络原因被误判为无效；
• 对于本地文件链接，需确保路径正确且文件存在。

Resource Existence Check ​

检查 Markdown 文件中的资源链接（如图片、视频等）是否存在，帮助用户及时发现无效或丢失的资源引用。

功能介绍 ​

• 自动检测 Markdown 文件中的图片、视频等资源链接是否有效，包括 Markdown 语法和 HTML 标签（如 <img>、<image>、<video>）中的资源路径；
• 支持多种资源引用方式，全面覆盖常见的资源链接格式；
• 支持通过配置项灵活启用或禁用该功能。

使用方法 ​

1. 安装并启用本插件，打开 Markdown 文件（.md），自动检查文档中的资源链接有效性；
2. 检查结果会以警告（Warning）的形式在编辑器中高亮显示，可在“问题”面板，或将光标悬停在警告标记处，查看无效资源的具体路径和提示信息。

配置说明 ​

插件支持以下配置项（可在 VSCode 设置中搜索 docTools.check.resourceExistence 或通过 settings.json 进行配置）：

• docTools.check.resourceExistence
  • 类型：boolean
  • 说明：是否启用资源存在性检查
  • 默认：true

配置示例 ​

{
  "docTools.check.resourceExistence": true
}

Toc Check ​

检查目录文件_toc.yaml中链接的有效性，同时检查目录下未被_toc.yaml引用的文档，帮助用户快速定位目录结构问题。

功能介绍 ​

• toc.yaml链接有效性：自动解析_toc.yaml，递归检查所有链接（如 href/upstream）对应的文档是否存在；
• 目录覆盖完整性：自动检测当前打开的 Markdown 文档是否已被加入到项目的_toc.yaml目录结构中。

使用方法 ​

1. 安装并启用本插件，打开任意目录文件toc.yaml，自动检查文件内容有效性，并检查文件是否被当前/上级目录的_toc.yaml引用；
2. toc.yaml链接有效性检查结果会以错误（Error）的形式在编辑器中高亮显示，可在“问题”面板，或将光标悬停在错误标记处，查看错误详情。
3. 若文档未加入目录文件，编辑器右下角会弹出提示信息，提醒用户将该文件加入_toc.yaml；

配置说明 ​

插件支持以下配置项（可在 VSCode 设置中搜索 docTools.check.toc 或通过 settings.json 进行配置）：

• docTools.check.toc
  • 类型：boolean
  • 说明：是否启用 TOC 校验功能
  • 默认：true

配置示例 ​

{
  "docTools.check.toc": true
}

中英文标点混用检查 ​

功能介绍 ​

• 自动检测 Markdown 中英文混用标点的情况（例如：中文内使用英文标点，或英文内使用中文标点）；
• 如需屏蔽此检测，可在该标点前后加空格（若后方紧跟其他标点符号，则无需额外空格）。
  • 例句1：添加 .png 后缀
  • 例句2：添加到 _toc.yaml。
  • 例句3：1. 这是一个有序列表
• 支持通过配置项灵活启用或禁用该功能。

使用方法 ​

1. 安装并启用本插件，打开 Markdown 文件（.md），自动检查文档中的中英文标点混用情况；
2. 检查结果会以警告（Warning）的形式在编辑器中高亮显示，可在“问题”面板，或将光标悬停在警告标记处，查看错误详情。

中文标点冗余空格检查 ​

功能介绍 ​

• 自动检测 Markdown 文件中的中文标点符号前后存在空格的错误；
• 支持通过配置项灵活启用或禁用该功能。

使用方法 ​

1. 安装并启用本插件，打开 Markdown 文件（.md），自动检查文档中的中文标点符号前后存在空格；
2. 检查结果会以警告（Warning）的形式在编辑器中高亮显示，可在“问题”面板，或将光标悬停在警告标记处，查看错误详情；
3. 可通过 VSCode 提供的 Quick Fix（快速修复）功能，点击灯泡图标或按下快捷键（通常为 Cmd+. 或 Ctrl+.），一键修复冗余空格问题。

目录生成 ​

功能介绍 ​

• 自动生成目录：根据实际存在的 Markdown 文件，自动生成_toc.yaml，避免手动维护目录结构；
• 同步标题：自动读取每个 Markdown 文件的一级标题（# ），作为目录项的 label；
• 去除无效项：如果_toc.yaml中的某些 href 指向的文件不存在，会自动移除这些无效项。

使用方法 ​

1. 安装并启用本插件；
2. 右键点击对应目录：选择“生成目录”命令，自动生成或更新此目录下的_toc.yaml；
3. 按需调整 label 值和章节顺序。

注意事项 ​

• 只有带有一级标题（# 标题）的 Markdown 文件才会被收录。

文档预览 ​

功能介绍 ​

• 支持文档实时预览功能，可完整呈现单本手册内容，可将 Markdown 语法渲染为格式化文本，同时能够解析_toc.yaml文件，生成目录导航。

使用方法 ​

1. 安装并启用本插件，打开 Markdown 文件（.md）；
2. 点击编辑器右上角的Doc Tools 预览功能按钮，即可查看当前 Markdown 文件所属的完整手册内容。