5.7.4 让机器提醒你更新文档——自动化检查

一句话破题

用 CI 自动检查文档，让机器代替人工提醒你更新文档。

自动化检查的价值

没有自动化：
  提交代码 → 忘了更新文档 → 合并 → 发现文档过时 → 再补

有自动化：
  提交代码 → CI 检查文档 → 提醒缺失 → 补上文档 → 合并

可以自动检查什么

检查项	工具	说明
Markdown 格式	markdownlint	格式规范
链接有效性	markdown-link-check	死链检查
拼写检查	cspell	单词拼写
文档覆盖率	自定义脚本	API 文档完整性

基础 CI 配置

GitHub Actions 示例：

# .github/workflows/docs.yml
name: Docs Check

on:
  push:
    paths:
      - 'docs/**'
      - '*.md'
  pull_request:
    paths:
      - 'docs/**'
      - '*.md'

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Lint Markdown
        uses: DavidAnson/markdownlint-cli2-action@v14
        with:
          globs: '**/*.md'

Markdown 格式检查

创建配置文件 .markdownlint.json：

{
  "default": true,
  "MD013": false,
  "MD033": false,
  "MD041": false
}

常见规则：

• MD013：行长度限制（通常禁用）
• MD033：禁止 HTML（通常禁用）
• MD041：首行必须是标题

链接检查

检查文档中的链接是否有效：

- name: Check Links
  uses: gaurav-nelson/github-action-markdown-link-check@v1
  with:
    use-quiet-mode: 'yes'
    config-file: '.markdown-link-check.json'

配置文件 .markdown-link-check.json：

{
  "ignorePatterns": [
    { "pattern": "^https://localhost" }
  ],
  "timeout": "10s",
  "retryOn429": true
}

文档覆盖率检查

自定义脚本检查 API 文档完整性：

// scripts/check-docs.js
const fs = require('fs')
const path = require('path')

// 获取所有 API 路由
const apiDir = 'src/app/api'
const routes = fs.readdirSync(apiDir, { recursive: true })
  .filter(f => f.endsWith('route.ts'))
  .map(f => path.dirname(f))

// 检查文档是否存在
const docsDir = 'docs/api'
const missing = routes.filter(route => {
  const docPath = path.join(docsDir, `${route}.md`)
  return !fs.existsSync(docPath)
})

if (missing.length > 0) {
  console.error('Missing docs for:', missing)
  process.exit(1)
}

console.log('All APIs have docs!')

PR 模板提醒

创建 PR 模板 .github/pull_request_template.md：

## 变更说明

### 代码变更
-

### 文档更新
- [ ] 不需要更新文档
- [ ] 已更新 API 文档
- [ ] 已更新 README
- [ ] 已更新部署文档

### 测试
- [ ] 本地测试通过

简化版自动化

对于个人项目，可以用最简单的方式：

# .github/workflows/docs.yml
name: Docs

on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Check Markdown
        run: npx markdownlint-cli2 "**/*.md"

本地预检查

在提交前本地检查：

// package.json
{
  "scripts": {
    "docs:lint": "markdownlint-cli2 '**/*.md'",
    "docs:links": "markdown-link-check docs/**/*.md"
  }
}

使用 husky 添加 pre-commit hook：

# 安装
pnpm add -D husky
npx husky install

# 添加 hook
npx husky add .husky/pre-commit "pnpm docs:lint"

实用建议

1. 从简单开始：先做格式检查，再逐步添加
2. 不要过度：检查太严格会让人厌烦
3. 快速反馈：CI 检查要快，几分钟内完成
4. 提供修复建议：告诉开发者如何修复问题