Markdownlint 使用指南

本项目使用 markdownlint 来保证 Markdown 文档的格式一致性和质量标准。本指南详细介绍如何安装、配置、使用 markdownlint，以及项目采用的检查规则。

📋 概述

Markdownlint 是一个用于检查 Markdown 文档格式和语法的工具，帮助团队维护一致的文档风格。项目配置支持 VitePress 语法，适配中文文档特点。

🚀 安装和使用

全局安装

# 使用 npm 全局安装
npm install -g markdownlint-cli

# 使用 yarn 全局安装
yarn global add markdownlint-cli

# 验证安装
markdownlint --version

项目中使用

# 检查所有 Markdown 文档
markdownlint docs/**/*.md

# 检查特定文件
markdownlint docs/development/markdownlint-guide.md

# 自动修复可修复的问题
markdownlint --fix docs/**/*.md

# 使用 npx（无需全局安装）
npx markdownlint-cli docs/**/*.md

IDE 集成

VS Code

安装 markdownlint 扩展：

{
  "recommendations": [
    "DavidAnson.vscode-markdownlint"
  ]
}

功能特性：

• 实时语法检查和错误高亮
• 自动修复建议
• 保存时自动格式化

JetBrains 系列

安装 Markdown 插件并启用 markdownlint 支持：

1. Settings → Plugins → 安装 Markdown
2. Settings → Languages & Frameworks → Markdown → 启用 Use markdownlint

⚙️ 配置文件

项目根目录的 .markdownlint.yaml 文件包含完整的检查规则配置：

核心配置理念

# 启用所有规则作为基础
default: true

# 针对项目特点进行定制
MD013: false  # 禁用行长度限制（中文文档特点）
MD033: false  # 允许内联 HTML（VitePress 组件支持）
MD040: false  # 允许无语言标识的代码块

VitePress 兼容性

# 支持 VitePress 特殊语法
MD001: false  # 允许标题跳级
MD026: false  # 允许标题末尾标点
MD028: false  # 支持特殊块语法（::: tip, ::: warning）

中文文档优化

# 中文文档友好配置
MD051: false  # 禁用中文标题锚点检查（避免误报）
MD036: false  # 允许粗体文本强调
MD024: false  # 允许重复标题（不同章节）

📖 检查规则详解

标题相关规则

规则	名称	说明	项目配置
MD001	标题层级递增	标题应按 H1→H2→H3 顺序	❌ 禁用
MD003	标题风格	统一使用 ATX 风格（#）	✅ 启用
MD018	标题空格	# 后必须有空格	✅ 启用
MD019	标题末尾空格	# 前不能有多余空格	✅ 启用
MD020	标题内部空格	标题内部空格规范	✅ 启用
MD021	标题缩进	标题不应缩进	✅ 启用
MD022	标题前后空行	标题前后必须有空行	✅ 启用
MD023	标题缩进	标题开始必须在行首	✅ 启用
MD024	重复标题	不允许重复标题	❌ 禁用
MD025	单个 H1 标题	文档只能有一个 H1	❌ 禁用
MD026	标题末尾标点	标题末尾不应有标点	❌ 禁用

列表相关规则

规则	名称	说明	项目配置
MD004	列表标记风格	统一使用短横线（-）	✅ 启用
MD005	列表缩进一致	同级列表项缩进一致	✅ 启用
MD006	列表开始位置	列表从行首开始	✅ 启用
MD007	列表缩进	使用 2 个空格缩进	✅ 启用
MD029	有序列表序号	有序列表序号格式	❌ 禁用
MD030	列表标记后空格	列表标记后空格数量	✅ 启用
MD032	列表前后空行	列表前后必须有空行	✅ 启用

代码相关规则

规则	名称	说明	项目配置
MD031	代码块前后空行	代码块前后必须有空行	✅ 启用
MD040	代码块语言标识	代码块应指定语言	❌ 禁用
MD046	代码块风格	优先使用围栏式代码块	✅ 启用
MD048	代码块风格一致	代码块风格保持一致	✅ 启用

链接和图片规则

规则	名称	说明	项目配置
MD034	裸露 URL	避免使用裸露的 URL	✅ 启用
MD039	链接空格	链接文本不应有空格	✅ 启用
MD042	空链接	避免空的链接引用	✅ 启用
MD045	图片替代文本	图片应有替代文本	✅ 启用
MD051	链接片段验证	验证内部链接有效性	❌ 禁用

格式和样式规则

规则	名称	说明	项目配置
MD009	行尾空格	删除行尾多余空格	❌ 禁用
MD010	硬制表符	使用空格替代制表符	❌ 禁用
MD011	反向链接语法	修复错误的链接语法	✅ 启用
MD012	多个连续空行	最多 2 个连续空行	✅ 启用
MD013	行长度限制	限制行长度	❌ 禁用
MD027	引用块缩进	引用块后空格数量	✅ 启用
MD028	空行包围引用	引用块前后空行	❌ 禁用
MD033	内联 HTML	允许/禁止内联 HTML	❌ 禁用
MD036	强调文本作标题	避免用粗体代替标题	❌ 禁用
MD047	文件末尾换行	文件以单个换行符结尾	✅ 启用

表格相关规则

规则	名称	说明	项目配置
MD055	表格管道符对齐	表格管道符应对齐	✅ 启用
MD056	表格列对齐	表格列内容对齐	✅ 启用
MD058	表格前后空行	表格前后必须有空行	✅ 启用

🔧 常见问题和修复

自动修复命令

# 修复所有可自动修复的问题
markdownlint --fix docs/**/*.md

# 修复特定类型问题
markdownlint --fix --config .markdownlint.yaml docs/**/*.md

手动修复指南

1. 标题前后空行 (MD022)

问题：

段落文本
## 标题
下面内容

修复：

段落文本

## 标题

下面内容

2. 列表前后空行 (MD032)

问题：

段落文本
- 列表项
下个段落

修复：

段落文本

- 列表项

下个段落

3. 代码块前后空行 (MD031)

问题：

段落文本
```bash
命令

下个段落

**修复**：
```markdown
段落文本

```bash
命令

下个段落

#### 4. 表格前后空行 (MD058)

**问题**：
```markdown
段落文本
| 列1 | 列2 |
|-----|-----|
| 值1 | 值2 |
下个段落

修复：

段落文本

| 列1 | 列2 |
|-----|-----|
| 值1 | 值2 |

下个段落

🎯 最佳实践

1. 集成到开发流程

预提交检查

# .git/hooks/pre-commit
#!/bin/sh
markdownlint docs/**/*.md
if [ $? -ne 0 ]; then
    echo "❌ Markdown 格式检查失败，请修复后再提交"
    exit 1
fi

CI/CD 集成

# .github/workflows/docs.yml
- name: Markdown Lint
  run: |
    npm install -g markdownlint-cli
    markdownlint docs/**/*.md

2. 团队协作规范

编辑器配置

推荐团队成员统一使用支持 markdownlint 的编辑器：

• VS Code: 安装官方扩展
• JetBrains: 启用 Markdown 插件
• Vim/Neovim: 使用 ALE 或 COC 插件

文档审查清单

提交 PR 时检查：

• [ ] 运行 markdownlint docs/**/*.md 无错误
• [ ] 标题层级合理，前后有空行
• [ ] 列表格式统一，前后有空行
• [ ] 代码块有语言标识（推荐但非强制）
• [ ] 表格格式整齐，前后有空行
• [ ] 无多余的行尾空格和连续空行

3. 性能优化

批量处理

# 并行检查多个文件
find docs -name "*.md" | xargs -P 4 markdownlint

# 只检查修改过的文件
git diff --name-only --diff-filter=AM | grep '\.md$' | xargs markdownlint

忽略特定文件

创建 .markdownlintignore 文件：

# 忽略自动生成的文档
docs/api/generated/
*.tmp.md

# 忽略第三方文档
docs/vendor/

🔍 故障排除

常见错误及解决方案

1. 配置文件不生效

症状：修改 .markdownlint.yaml 后规则未更新

解决方案：

# 检查配置文件语法
yamllint .markdownlint.yaml

# 验证配置是否生效
markdownlint --config .markdownlint.yaml docs/test.md

2. 中文标题链接错误

症状：MD051 错误，中文标题锚点检查失败

解决方案：

# 在 .markdownlint.yaml 中禁用
MD051: false

3. VitePress 语法冲突

症状：VitePress 特殊语法被标记为错误

解决方案：

# 禁用相关检查
MD033: false  # 允许 HTML
MD001: false  # 允许标题跳级
MD028: false  # 允许特殊块

4. 性能问题

症状：大型项目检查速度慢

解决方案：

# 只检查修改的文件
git diff --name-only | grep '\.md$' | xargs markdownlint

# 使用 .markdownlintignore 排除不需要检查的文件
echo "docs/generated/" >> .markdownlintignore

📚 参考资料

官方文档

• markdownlint GitHub
• markdownlint-cli GitHub
• 规则详细说明

相关工具

• Prettier Markdown 插件
• remark-lint
• Vale 文档校对工具

扩展阅读

• CommonMark 规范
• GitHub Flavored Markdown
• VitePress Markdown 扩展

---

💡 提示：本指南与项目的 .markdownlint.yaml 配置保持同步，定期更新以反映最新的规则调整和最佳实践。