markdownlint

Markdownlint

验证 Markdown 文件是否符合格式规范，确保文档风格一致、差异易读，并符合 POSIX 标准。

此技能的功能

1. 检查是否已安装 markdownlint-cli；如果未安装，则进行安装。
2. 检测项目专属的 markdownlint 配置；如果没有，则使用最精简的默认配置。
3. 验证 Markdown 文件的格式、结构和风格。
4. 可使用 --fix 标志自动修正常见问题；报告错误及对应规则和修复方法。

安装检查

# Check if markdownlint is available
markdownlint --version 2>/dev/null

如果尚未安装，则全局安装：

npm install -g markdownlint-cli

如果安装失败（权限问题、未安装 npm），请停止验证并报告问题，同时提供解决步骤：

• 使用 sudo npm install -g ...，或修复 npm 权限
• 使用 Node 版本管理器（nvm、volta、fnm）
• 如果尚未安装 Node.js，请先安装

不要悄悄跳过验证。

配置检测优先级

1. 项目根目录中的 .markdownlint.json
2. 项目根目录中的 .markdownlint.yaml
3. 项目根目录中的 .markdownlintrc
4. package.json 中的 markdownlint 字段
5. 默认配置（参见 references/markdownlint-config.json）

如果项目中不存在配置，请使用参考文件中的默认配置创建临时 .markdownlint.json，然后再运行验证。

验证工作流

1. Check markdownlint installation
   ├─ Installed → continue
   └─ Missing → install, then continue (fail if install fails)

2. Detect project config
   ├─ Found → use it
   └─ Not found → use default config from references/

3. Run validation
   ├─ Check only:
   │    markdownlint <files-or-directories>
   └─ Auto-fix:
        markdownlint --fix <files-or-directories>

4. Report results
   ├─ Valid → confirm and proceed
   └─ Invalid → show errors, suggest fixes, re-validate after correction

验证方法

检查文件（默认）

markdownlint README.md CHANGELOG.md docs/

自动修正常见问题

markdownlint --fix README.md CHANGELOG.md docs/

注意：有些问题（例如 MD001 标题级别递增）无法自动修复，需要手动更正。修复后，请在不使用 --fix 的情况下重新运行，以确认所有问题均已解决。

错误处理

安装失败

如果无法安装 markdownlint，请报告错误并提供解决步骤。不要继续验证。

验证失败

验证失败时，请报告每个错误，并说明：

• 违反的规则（例如，MD022/blanks-around-headings）
• 具体问题（例如，标题周围没有空行）
• 明确的修复方法

示例：

Validation failed:

1. MD022/blanks-around-headings: heading not surrounded by blank lines
   File: README.md:15
   Fix: add blank lines before and after the heading

2. MD047/single-trailing-newline: file does not end with newline
   File: CHANGELOG.md:89
   Fix: add a single newline at end of file

报告错误后，建议运行 markdownlint --fix 修复可自动修复的问题，并为其余问题提供手动修复方法。更正后重新验证。

格式参考

完整规则参考、常见修复方法和可自动修复的规则，请参见 references/markdownlint-rules.md。