Markdown Lint 完整指南：检查标题层级、列表、链接、行长规则与自动化质量门禁

把 Markdown lint 作为可重复的质量检查

Lint 并不等同于渲染、拼写检查、链接爬取或内容审校。文件即使通过全部样式规则，仍可能包含错误事实、不可访问图示或失效外链。可靠流程应把 lint 结果与渲染预览、链接验证和人工语义检查结合起来。

理解 Markdown lint 能检查什么、不能检查什么

搜索 Markdown validator 的用户通常面临三类问题：语法无法渲染、样式违反项目规范，或内容在 CommonMark 与 GitHub Flavored Markdown 中表现不同。修改规则前，应先确定真正的失败类型。

优先处理真正预防缺陷的 Markdownlint 规则

维护中的 markdownlint 规则说明记录了规则别名、参数、触发示例和修复方式。应阅读项目实际使用的实现，不要假设不同软件包对同一规则编号的处理完全一致。

在不破坏内容的前提下修复 Markdown lint 问题

1. 1复现问题。记录命令、软件包版本、配置路径、文件、规则和行号。
2. 2读取本地规范。使用通用默认值前，先检查仓库配置和贡献说明。
3. 3判断影响。先修复大纲、破损语法和解析歧义，再处理空白或个人风格。
4. 4进行最小且语义安全的修改。保留含义、代码行为、链接目标、表格数据和生成标记。
5. 5重新运行 lint 并渲染。只有报告变干净还不够，还要确认文档预览仍然正确。
6. 6审阅差异。确认修改没有重排无关段落，也没有掩盖合理警告。

建立团队能够解释的 Markdownlint 配置

良好配置应表达经过讨论的项目决策。尽量从默认规则开始，只对有明确理由的规则做修改，并把例外范围限制到最小。配置应存入仓库，让本地编辑器和 CI 使用同一规范。

{
  "default": true,
  "MD013": {
    "line_length": 100,
    "code_blocks": false,
    "tables": false
  },
  "MD033": {
    "allowed_elements": ["details", "summary"]
  }
}

该示例只说明配置思路，并非通用推荐。表格行无法安全换行时，可让 MD013 忽略表格以减少噪声。文档平台明确支持某些 HTML 元素时可以允许它们，但不应因此开放任意嵌入标记。

markdownlint 项目文档说明了配置对象和行内控制方式。应优先使用仓库级配置，而不是散落的禁用注释。如果确实需要行内抑制，应明确规则并解释例外为何安全。

在命令行和 CI 中运行 Markdown lint

对于 JavaScript 项目，markdownlint-cli2 在 markdownlint 库之上提供 glob 匹配和配置发现。应安装仓库批准的版本，在锁文件中固定，并通过脚本排除生成目录和依赖目录。

npm install --save-dev markdownlint-cli2
npx markdownlint-cli2 "**/*.md" "#node_modules" "#dist"

markdownlint-cli2 文档说明了配置格式、glob、输出格式化和 CI 用法。本地与 CI 应运行同一个项目脚本；两套独立命令很容易演变为两套规范。

# Example CI step
- name: Lint Markdown
  run: npm run lint:markdown

拉取请求可检查变更文档，大型仓库则可定期运行全量扫描。基线能够帮助渐进引入 lint，但应记录已知债务，而不是永久静默排除整棵文档目录。

让编辑器反馈与仓库检查保持一致

编辑器集成能够缩短反馈周期，但前提是它发现的配置和工具行为与 CI 相同。应把仓库根目录作为工作区打开，确认当前配置路径，并用一个已知违规做测试。如果编辑器与 CI 报告不同，就比较软件包版本、工作目录、忽略模式和配置优先级。

不要让写作者养成压制所有警告的习惯。应提供简短政策，区分必须修复的结构问题、项目特定样式、合理例外，以及需要其他工具完成的检查。这样 lint 输出才能成为共同审阅语言，而不是障碍。

排查常见 Markdown lint 失败

使用这份 Markdown lint 完成清单

1. 记录主要 Markdown 方言、linter 软件包、版本、命令和配置路径。
2. 确认配置已纳入版本控制，并由本地和 CI 共同使用。
3. 先修复结构和语法问题，再处理外观一致性问题。
4. 检查每个抑制和排除模式，确保理由明确且范围有限。
5. 重新运行项目命令，并保留干净输出作为构建证据。
6. 在目标发布平台中渲染所有修改文件。
7. 通过适当检查验证重要链接、图片替代文字和事实声明。
8. 审阅最终差异，检查无关重排、锚点变化或示例损坏。

CommonMark 规范是核心解析行为的权威参考。平台扩展仍需查阅各自文档并进行测试。

Markdown lint 常见问题

关于本指南

快速答案补充：用基线、差异审查和退出条件逐步引入 Markdown lint

不要在遗留仓库中一次开启全部规则并机械修复所有文件。先固定 linter、运行时和依赖版本，保存当前命令与配置路径，再对完整仓库运行只读扫描。把结果按结构缺陷、解析风险、可维护性、纯格式和生成文件分类；标题跳级、未闭合围栏、列表解析歧义等可能改变输出的项目优先处理，而行长或项目符号风格应结合团队审阅方式决定。

每次修改规则都应像修改代码一样审查。记录发起原因、受影响文件、预期减少的缺陷、可能产生的误报、是否允许自动修复，以及撤销条件。选择一个包含表格、代码、HTML、链接引用和多级列表的代表性样例，在变更前后运行 lint，并在目标平台渲染。只有当违规变化符合预期、语义没有改变、锚点仍有效、示例仍可复制时，规则调整才算通过。

用可复核示例判断 Markdown lint 警告是否应该修复

以下是教学示例，不代表真实客户结果。假设 CI 报告 MD013 行长问题，目标行是一张包含长网址的表格。直接换行可能破坏表格，关闭整个仓库的 MD013 又会掩盖普通正文的可读性问题。维护者应先确认当前 markdownlint 实现和参数，再用最小范围配置排除表格，同时保留正文限制，并把理由写入配置评审记录。

Lint 通过只证明文件满足已配置规则，不能证明事实准确、链接可访问、图片替代文字合适或内容满足用户意图。发布门禁还应包含目标渲染、外链状态、图片检查和人工内容审阅。任何自动化指标都应保留边界说明，避免把“零警告”误写成“零缺陷”。

Markdown lint 的官方来源与参考资料

规则编号、参数和抑制语法应以当前项目实际安装的实现为准。请查阅 markdownlint 规则说明确认每条规则的触发条件，使用 markdownlint 项目文档核对配置与行内控制，并参考 markdownlint-cli2 文档验证命令行、glob 和 CI 行为。底层 Markdown 解析边界可对照 CommonMark 规范；平台扩展仍需在实际发布环境中测试。

为 Markdown lint 规则变更保留回滚与复核记录

规则升级或配置调整后，应保存变更前后的违规汇总、代表性渲染截图、锁定的软件包版本、批准人和回滚触发条件。如果新规则导致大量无关差异、破坏生成内容、改变锚点，或让本地与 CI 无法一致复现，应先恢复最后一个已验证配置，再隔离问题规则。不要通过删除锁文件、扩大忽略目录或全局禁用来制造“通过”结果；这些做法会隐藏真实质量债务。关闭变更前，再让未参与配置修改的人复跑仓库脚本并检查一份代表性文档，确认报告、退出码和目标渲染都与记录一致。