文档流水线是什么
文档流水线（Docs CI）把代码评审的那套门禁搬到文档仓库：每次提交自动跑格式检查、链接检查、术语校验、示例代码语法检查与预览构建，错误级问题直接阻塞合并。它替代的是人工逐页翻看这类低价值劳动，让评审者把注意力放在内容是否准确、结构是否合理上。前提是文档以纯文本（Markdown/AsciiDoc）形式存入 Git 仓库。
基本信息
| 适用平台 | GitHub Actions、GitLab CI、Jenkins 等，配合 Markdown 仓库与静态站点生成器 |
|---|---|
| 检查项 | 格式 lint、内部与外部链接、拼写与术语、示例代码语法、目录与文件命名 |
| 常见工具 | markdownlint、Vale（术语与写作规则）、Lychee 或 linkchecker（链接）、依语言选用的语法检查 |
| 门禁策略 | 错误级阻塞合并，警告级只提示不阻塞 |
| 运行成本 | 外部链接检查耗时最长，通常限频或放在定时任务里 |
典型使用场景
- 文档仓库提交即校验：作者在合并前就看到问题，不必等评审人指出
- API 文档与代码同仓库时，校验示例请求是否还能跑通
- 站点改版或批量替换路径后，全量扫一遍失效的内外链
- 统一术语与写作风格：把规范写成规则文件，而不是靠人记
- 多语言文档：校验翻译文件与源文件的结构是否一一对应
流水线阶段示例
流水线阶段示例
1. lint # markdownlint 检查标题层级、列表缩进、行尾空格
2. vale # 术语与写作规则，按严重级别输出
3. linkcheck # 内部链接先查，外部链接单独 stage 并允许失败重试
4. syntax # 抽取代码块按语言做语法或编译校验
5. preview # 构建站点预览，产出预览链接贴到合并请求检查项与策略
| 检查项 | 常见误报 | 建议策略 |
|---|---|---|
| 外部链接 | 对方站点的反爬与 403、临时超时 | 设置重试与超时，允许白名单，不对单次失败直接判死 |
| 拼写检查 | 大量专有名词被标错 | 维护术语词典，把产品名与命令加入白名单 |
| 格式 lint | 历史存量文件规则冲突 | 先对新文件生效，存量分批评改 |
| 示例代码语法 | 代码块是片段而非完整程序 | 只对标注了可校验的代码块执行 |
门禁要分清错误与警告两级：把警告也设成阻塞，会逼团队用忽略标记绕过检查，最后整条流水线形同虚设。新引入规则时先以警告观察一到两周，确认误报率可接受再升级为错误。
流水线本身也要可维护：规则配置文件放在仓库内随文档一起评审，检查失败的日志要能直接定位到文件与行号，否则作者不看日志、直接找人问，自动化就白做了。