markdownlint 是什么
markdownlint 检查 Markdown 的结构与风格：标题层级是否跳级、行宽是否超限、代码块是否标注语言、文件末尾是否只有一个换行。规则用 MD 编号标识，Node 生态里常用 markdownlint-cli2 作为命令行包装。它适合文档仓库批量执行，在 CI 里守住文档的一致性，让目录生成、锚点跳转这类依赖结构的事情不出错。
基本信息
| 典型规则 | MD013 行宽 / MD041 首行一级标题 / MD047 文件末尾换行 |
|---|---|
| 工具 | markdownlint（库）、markdownlint-cli2（命令行包装） |
| 配置 | .markdownlint.json 或 .markdownlint-cli2.jsonc |
| 修复 | 支持 --fix 自动修复部分规则 |
| 适用 | 文档仓库、README、团队规范文档 |
常被触发的规则
- MD013：行宽超限，中文文档与表格最容易命中
- MD041：文件首行必须是顶级标题，否则文档目录里显示异常
- MD040：代码围栏未标注语言，语法高亮与工具解析都失效
- MD009 / MD012：行尾多余空格、连续多个空行
- MD024：同一文档内出现重复标题，锚点链接会指向第一个
- MD033：内联 HTML，多数文档站的渲染策略下不生效
用法与配置
用法与配置
npx markdownlint-cli2 "docs/**/*.md" # 批量检查
npx markdownlint-cli2 --fix "docs/**/*.md" # 自动修复可修项
markdownlint docs/ # 旧版 CLI 用法
# .markdownlint.json 片段
# {
# "default": true,
# "MD013": { "line_length": 120, "tables": false },
# "MD033": false
# }常用规则速查
| 规则 | 检查内容 | 常见处理 |
|---|---|---|
| MD013 | 行宽（默认 80） | 放宽阈值，表格单独豁免 |
| MD041 | 首行一级标题 | 补一行 H1 |
| MD040 | 围栏代码块语言 | 补 bash / json 等 |
| MD047 | 文件末尾换行 | 交给 --fix 自动补 |
| MD024 | 重复标题 | 允许不同层级重复或改写标题 |
| MD033 | 内联 HTML | 按文档站策略决定是否关闭 |
中文文档的常见做法是把 MD013 的 line_length 放宽并关闭对表格的检查，而不是整条关掉：一旦整条禁用，超长段落会重新出现且无人提醒，评审时才慢慢发现。
让编辑器插件与 CI 共享同一份配置能减少摩擦：本地保存即提示，CI 只做兜底。两份规则不一致时，作者会在提交后才发现问题，返工成本明显上升。