Markdown 规范与 Lint

让 Agent 在撰写或批量修复文档时遵循统一 Markdown 风格，并与 markdownlint、Prettier 或项目 .markdownlint.json 对齐。

本页为 Agent 提供 Markdown 质量管理的完整参考：.markdownlint.json 配置文件、markdown-link-check 死链检测与 CI 集成、代码块规范（fenced + 语言标注）、文档风格指南关键规则，以及 SKILL 片段。

在 SKILL 中写明标题层级（单一 H1、逻辑递进 H2/H3）、列表前后空行、围栏代码块必须带语言标签、链接用相对路径；区分「必须修复（阻断 CI）」与「建议项（warning）」，避免 Agent 随意改风格。

markdownlint 完整配置文件

项目根目录 .markdownlint.json 配置，覆盖最常见规则；根据项目需要调整 false（关闭）或具体参数：

// .markdownlint.json
{
  "default": true,
  "MD001": true,          // 标题层级递增（H1→H2→H3，不跳级）
  "MD003": { "style": "atx" },  // 统一用 # ## ### 风格
  "MD004": { "style": "dash" }, // 无序列表统一用 -
  "MD007": { "indent": 2 },     // 列表缩进 2 空格
  "MD010": { "code_blocks": false }, // 禁止 Tab（代码块除外）
  "MD013": false,         // 关闭行宽限制（由 Prettier 接管）
  "MD022": true,          // 标题上下各空一行
  "MD024": { "siblings_only": true }, // 同级兄弟标题不重名
  "MD025": true,          // 全文唯一 H1
  "MD031": true,          // 围栏代码块前后空行
  "MD032": true,          // 列表前后空行
  "MD033": false,         // 允许 HTML（如 <details><summary>）
  "MD040": true,          // 围栏代码块必须有语言标签
  "MD041": true,          // 首行为 H1（部分模板可设为 false）
  "MD051": true,          // 锚点链接片段必须存在
  "MD055": { "style": "consistent" } // 表格分隔线风格一致
}

死链检查：markdown-link-check 配置：

// .mlc-config.json（markdown-link-check 配置）
{
  "ignorePatterns": [
    { "pattern": "^https://localhost" },
    { "pattern": "^https://internal\\.example\\.com" }
  ],
  "replacementPatterns": [
    { "pattern": "^/", "replacement": "{{BASEURL}}/" }
  ],
  "httpHeaders": [
    { "urls": ["https://github.com"], "headers": { "Accept-Encoding": "zstd,br,gzip,deflate" } }
  ],
  "timeout": "20s",
  "retryOn429": true,
  "retryCount": 3,
  "aliveStatusCodes": [200, 206]
}

// package.json scripts
// "check:links": "find docs -name '*.md' | xargs markdown-link-check --config .mlc-config.json"

CI 集成（GitHub Actions）：

# .github/workflows/docs-lint.yml
name: Docs Lint
on:
  pull_request:
    paths: ['**/*.md', 'docs/**']

jobs:
  markdownlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx markdownlint-cli2 "**/*.md" "#node_modules"

  link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm i -g markdown-link-check
      - run: find docs -name '*.md' | xargs markdown-link-check -c .mlc-config.json

与仓库配置对齐：优先读取 .markdownlint.json，不在 SKILL 里重复矛盾规则。
与 Prettier 并用时：prose wrap、list 样式由谁负责写清楚，避免两工具打架。

规则与 SKILL 映射

下表为常见 markdownlint 规则与 SKILL 中应写清的约定对应关系；具体启用与否以仓库配置为准。

规则	含义摘要	SKILL 应交代
`MD001`	标题层级逐级递增，避免跳级。	是否允许从 H2 直接到 H4；文档模板若固定 H1 由站点生成则注明。
`MD003 / MD004`	标题风格、无序列表符号一致。	统一 `-` 或 `*`，与 Prettier 配置一致。
`MD013`	行宽上限（若启用）。	最大列数或声明由 Prettier prose wrap 接管。
`MD022 / MD031 / MD032`	标题与列表周围空行。	要求「标题上下空行」「列表前后空行」，减少渲染抖动。
`MD040`	围栏代码块须带语言标签。	默认语言（如 `text`）是否可接受。
`MD041`	首行应为一级标题。	若 README 由模板拼 H1，在 SKILL 写豁免策略。
`MD051`	链接片段存在性（部分配置）。	锚点命名规范、是否校验站内链接。

CI 集成

将 markdownlint 放进与 TypeScript/ESLint 同级的 PR 检查，Agent 才能在「绿 CI」约束下改文档。

markdownlint-cli2：在 package.json 脚本中跑 markdownlint-cli2 "**/*.md"，配置指向 .markdownlint-cli2.jsonc；适合与 npm 生态一体。
GitHub Actions：单独 job 或在 lint job 中串行执行；缓存 node_modules 以缩短时间。
pre-commit：本地钩子跑同一命令，减少 push 后才发现的失败。
与 Prettier：CI 中顺序建议先 Prettier（若格式化 md）再 markdownlint，或在文档中约定「只由一方改空格/换行」。

SKILL 提示：写明「修复后必须在本地或 CI 跑通与 main 相同的 lint 命令」，并引用仓库内确切脚本名，避免 Agent 臆造不存在的任务。

Agent 修复流程

将「读配置 → 摘要 → 分批修复 → 校验」写进 SKILL，便于模型按顺序执行。

  [ 读取 .markdownlint* / Prettier / CI 脚本名 ]
                    │
                    ▼
            [ 扫描：违规摘要 + 按文件分组 ]
                    │
           ┌────────┴────────┐
           ▼                 ▼
    [ 自动可修项 batch ]   [ 需人审项单独列出 ]
           │                 │
           └────────┬──────────┘
                    ▼
            [ 应用补丁 / 小步 commit ]
                    │
                    ▼
         [ 本地或 CI：markdownlint + 约定命令 ]
                    │
           ┌────────┴────────┐
           ▼                 ▼
        [ 通过 ]         [ 失败则回滚该批 ]
                              │
                              ▼
                    [ 对照规则 ID 再改一版 ]

标题层级检查（围栏内忽略）

粘贴草稿 Markdown：统计行数、检测 ATX 标题（# … ######）在层级上是否跳级（类似 MD001 的直观版）；``` 围栏内的 # 不计入。

Markdown 草稿

行数 0 检出标题 0

SKILL 片段

可直接复制为技能正文骨架，再替换为仓库真实路径与脚本。

---
name: markdown-lint
description: 按项目规则规范化 Markdown 并对接 markdownlint
---
# 规则
- 标题：唯一 H1，H2/H3 不跳级（MD001/MD025）
- 列表：统一用 - 符号，前后空行（MD004/MD032）
- 代码块：全部用围栏（```lang），禁止无语言标注的围栏（MD040）
- 链接：内部链接用相对路径；锚点 ID 用小写连字符
- 行宽：由 Prettier 接管，关闭 MD013
- 表格：列分隔线对齐，每行列数一致

# 步骤
1. 读取 .markdownlint.json / .markdownlint-cli2.jsonc（优先项目配置）
2. 运行扫描：npx markdownlint-cli2 "**/*.md" "#node_modules"
3. 输出违规摘要，按文件分组（规则 ID + 行号 + 描述）
4. 自动修复：markdownlint-cli2 --fix（仅安全可修复项）
5. 人工审查：跳级标题、缺语言标注的代码块、破损链接
6. 死链检查：find docs -name '*.md' | xargs markdown-link-check -c .mlc-config.json
7. 小步 commit，每批修复独立 commit 便于 revert

返回技能库更多技能入口