【11-12】技术团队 Markdown 文档工程化实践：规范、校验与自动化发布

为什么文档需要工程化

技术团队的知识沉淀大多以 Markdown 形式存在，但长期存在三类问题：格式不统一、链接失效没人管、更新不及时。我们的解法是把文档当代码管理。

三步走

1. 统一规范

引入 markdownlint，在仓库根目录放置 .markdownlint.json，约定标题层级、列表缩进、行尾空格等规则。编辑器装上插件后可以实时提示。

2. CI 自动校验

在流水线中加入文档检查任务：

• 全量扫描 Markdown 文件执行 lint；

• • 解析所有站内链接，发起 HEAD 请求校验可达性；

  • • 检查图片引用的文件是否存在。

    • 任何一项失败都会阻断合并，保证进入主干分支的文档是合格的。

  • 3. 自动发布

• 文档合并到主干后，流水线自动把 Markdown 渲染为静态站点并发布。团队成员看到的永远是最新版本，不再需要来回传文件。

效果

落地三个月后，文档链接失效率从每周十余处降到基本为零，新人上手成本明显降低。文档工程化投入不大，收益却是长期的。