# vscode-doc-tools
**Repository Path**: gzbang/vscode-doc-tools
## Basic Information
- **Project Name**: vscode-doc-tools
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-11-26
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Doc Tools
本插件提供文档[静态检查](#静态检查)、[预览、目录生成等工具](#其它工具)，希望能提高文档贡献过程中开发体验。
[开发指南](./README_develop.md)
[CHANGELOG](./CHANGELOG.md)
## 静态检查
| 名称 | 功能 |
| ----------------------------------------------------- | ------------------------------------------------------------------------------ |
| [Markdown Lint](#markdown-lint) | Markdown 语法检查 |
| [Tag Closed Check](#tag-closed-check) | Html 标签闭合检查 |
| [Link Validity Check](#link-validity-check) | 链接有效性检查（包含：1. 内链；2. 外链） |
| [Resource Existence Check](#resource-existence-check) | 资源是否存在检查（包含：1. 内链；2. 外链） |
| [Toc Check](#toc-check) | 目录文件检查（1. 目录中引用的文件需要存在；2. 每一篇 md 文档都需要在目录中进行维护） |
| [CodeSpell Check](#codespell-check) | 单词拼写检查 |
| [Filename Check](#filename-check) | Markdown 文件名称检查（包含：1. 文件名称是否命名规范，2. 中英文文档名称是否一致） |
| [Punctuation Check](#punctuation-check) | 标点符号检查 |
### 全局配置说明
插件支持以下配置项（可在 VSCode 设置中搜索 `docTools.scope` 或通过 `settings.json` 进行配置）：
- `docTools.scope`
- 类型：`boolean`
- 说明：是否检查范围仅限于 `docs/zh` 和 `docs/en` 目录
- 默认：`false`
#### 全局配置示例
```json
{
"docTools.scope": false // 启用检查范围仅限于 docs/zh 和 docs/en 目录，默认检查项目全局文档
}
```
### Markdown Lint
基于 `Markdownlint` 实现，帮助用户规范 Markdown 文档格式。
#### 功能介绍
- 自动检测 Markdown 文件中的格式问题，如标题格式、列表缩进、空行等；
- 检查结果以警告（Warning）的形式在编辑器中高亮显示，并可在“问题”面板中查看详细信息；
- 可通过配置项灵活启用或禁用 lint 功能，并支持自定义 lint 规则，满足不同团队或个人的文档规范需求；
- 支持一键修复功能，帮助用户一键修复所有 Markdownlint 问题。
#### 使用方法
1. 安装并启用本插件，打开 Markdown 文件（`.md`），插件会自动对文件内容进行 lint 检查；
2. 检查结果会以警告（Warning）的形式显示在编辑器左侧和底部问题面板；
3. 将光标悬停在警告标记上可查看详细的规则说明和建议；
4. 可通过 VSCode 提供的 Quick Fix（快速修复）功能，点击灯泡图标或按下快捷键（通常为 `Cmd+.` 或 `Ctrl+.`），一键修复所有 Markdownlint 问题。
#### 配置说明
插件支持以下配置项（可在 VSCode 设置中搜索 `docTools.markdownlint`或通过`settings.json`进行配置）：
- `docTools.markdownlint.enable`
- 类型：`boolean`
- 说明：是否启用 Markdown lint 功能
- 默认：`true`
- `docTools.markdownlint.config`
- 类型：`object`
- 说明：自定义 markdownlint 配置对象。若未设置，则使用插件内置的默认规则
##### 配置示例
```json
{
"docTools.markdownlint.enable": true, // 是否开启功能
"docTools.markdownlint.config": {
"MD013": false, // 禁用行长度限制
"MD041": true // 启用标题必须为一级标题
}
}
```
#### 默认规则
插件内置一套 Markdownlint 默认规则（见 `config/markdownlint`），可根据实际需求通过配置覆盖。
### Tag Closed Check
检查 Markdown 文件中的 Html 标签是否正确闭合，帮助用户避免因标签未闭合导致的渲染或语法错误。
#### 功能介绍
- 自动检测 Markdown 文件中的 Html 标签是否正确闭合，包括未闭合、嵌套错误等问题；
- 支持快速修复功能，帮助用户一键修正标签闭合和转义问题；
- 支持通过配置项灵活启用或禁用该功能。
#### 使用方法
1. 安装并启用本插件，打开 Markdown 文件（`.md`），插件会自动对文件内容进行 Html 标签闭合检查；
2. 检查结果会以错误（Error）的形式在编辑器中高亮显示，并可在“问题”面板中查看详细信息；
3. 将光标悬停在错误标记处，可查看错误详情；
4. 可通过 VSCode 提供的 Quick Fix（快速修复）功能，点击灯泡图标或按下快捷键（通常为 `Cmd+.` 或 `Ctrl+.`），一键修复标签问题。
PS：在嵌套的 Html 标签（如 \ 这种情况）里引发提示，请使用`<和>字符替换 (适用于 Html 标签嵌套的情况)`进行修复，其它情况请使用`\字符替换 (适用于非 Html 标签嵌套的情况)`进行修复。
#### 配置说明
插件支持以下配置项（可在 VSCode 设置中搜索 `docTools.check.tagClosed`或通过`settings.json`进行配置）：
- `docTools.check.tagClosed.enable`
- 类型：`boolean`
- 说明：是否启用 Html 标签闭合检查
##### 配置示例
```json
{
"docTools.check.tagClosed.enable": true
}
```
#### 快速修复说明
- \字符替换：适用于非 Html 标签嵌套的情况，会在对应的 Html 标签前加上 `\` 转义字符；
- \<和\>字符替换：适用于 Html 标签嵌套的情况，会将 `<` 和 `>` 替换为 `<` 和 `>`；
- 闭合标签：自动为未闭合的标签补全闭合部分。
### Link Validity Check
该插件用于在 VSCode 中检查 Markdown 文档中的链接有效性，帮助用户及时发现失效或错误的链接，提升文档质量。
#### 功能介绍
- 自动扫描 Markdown 文档中的所有链接，包括以下三种格式：
- `[文本](链接)` 形式的标准 Markdown 链接
- `` 形式的裸链接
- `` 形式的 Html 链接
- 链接为 http 链接，支持跳过锚点链接（如 `#section`），并自动忽略链接中的锚点部分，仅校验主链接地址；
- 链接为相对路径的 `.md` 链接时，支持检测本地的 `.md` 文件是否存在，并且能够检查锚点是否有效；
- 对于无效链接，会在编辑器中以错误（Error）的形式在编辑器中高亮显示，并在问题面板中给出详细提示；
- 对于访问超时的链接，会在编辑器中以警告（Warning）的形式在编辑器中高亮显示，并在问题面板中给出详细提示；
- 支持通过配置项灵活启用或禁用该功能；
- 支持添加链接检查白名单（仅在链接为 http 链接会出现此修复功能）。
#### 使用方法
1. 安装并启用插件后，打开任意 Markdown 文件（`.md`），插件会自动检测所有链接的有效性；
2. 检查结果会以错误（Error）或警告（Warning）的形式显示在编辑器左侧和底部问题面板；
3. 将光标悬停在错误或警告标记处，可查看错误详情；
4. 若 http 链接确认可访问存在误报的情况，可通过 Quick Fix（快速修复）功能，将链接加入检查白名单。
#### 配置说明
插件支持以下配置项（可在 VSCode 设置中搜索 `docTools.check.linkValidity`或通过`settings.json`进行配置）：
- `docTools.check.linkValidity.enable`
- 类型：`boolean`
- 说明：是否启用链接有效性检查
- 默认：`true`
- `docTools.check.linkValidity.only404.enable`
- 类型：`boolean`
- 说明：启用链接有效性检查只在链接无法访问时提示（可减少一些误报）
- 默认：`true`
- `docTools.check.url.whiteList`
- 类型：`array`
- 说明：检测链接白名单（添加后忽略对该链接的检查）
- 默认：`[]`
##### 配置示例
```json
{
"docTools.check.linkValidity.enable": true,
"docTools.check.linkValidity.only404.enable": true,
"docTools.check.url.whiteList": []
}
```
#### 注意事项
- 默认开启`链接有效性检查只在链接无法访问时提示`配置，可自由关闭此配置；
- 插件仅检测链接的格式和可达性，不保证目标内容的正确性；
- 某些私有或受限网络下的链接可能因网络原因被误判为无效；
- 对于本地文件链接，需确保路径正确且文件存在。
### Resource Existence Check
检查 Markdown 文件中的资源链接（如图片、视频等）是否存在，帮助用户及时发现无效或丢失的资源引用。
#### 功能介绍
- 自动检测 Markdown 文件中的图片、视频等资源链接是否有效，包括 Markdown 语法和 Html 标签（如 `![]()
`、``、`