Markdown 文档语法检查器

被文档风格漂移拖慢的评审

代码评审里,Markdown 文件往往是最后被检查、也最容易被放过的部分。一个仓库里 README、文档站点源码、变更日志混在一起,不同贡献者写出来的标题层级、列表符号、链接格式各有一套习惯。轮到人工 review 时,审阅者要在「内容对不对」之外,再分心去盯「空行有没有漏」「列表缩进对不对」,评审时间被格式琐事吃掉。

用规则而不是审美来收口

这个技能把 markdownlint-cli2 的能力包装成可复用的动作:对仓库或文档目录执行规则检查,输出定位到具体文件和行号的违规清单,每条意见都有规则编号可追溯。核心流程很直接:先按仓库根目录或文档路径收集待检查的 Markdown 文件,再套用内置或自定义的 .markdownlint-cli2 配置,得到结构化报告;不合规项要么在本地提交前修掉,要么挂在 CI 里挡住合并。

关键能力包括:

• 规则化输出:每条提示对应明确规则,修哪一行、改成什么都有据可依。
• 配置可组合:仓库级默认配置与目录级覆盖并存,前端文档和内部 wiki 可以用不同宽松度。
• 双环境运行:宿主机 CLI 与 Docker 容器两种方式都支持,保证 CI 与本地跑出的结果一致。
• 增量友好:可只扫描变更涉及的文件,适合接入 PR 检查。

适用边界

它只管格式一致性,不判断内容是否准确,也不会改写文案。规则冲突或刻意偏离标准时,需要自己写例外配置,而不是指望工具猜意图。另外上游对不同运行方式的支持范围并不完全对等,选定一种工作流后要保持统一,免得本地干净、CI 报错。