Markdown 格式规范为什么这么重要?
Markdown 的优势在于用纯文本表达结构,但这也带来一个隐患:不同工具对"格式容忍度"差异极大。GitHub 会把 ##标题(# 号后无空格)渲染成普通段落;markdownlint、Vale、CI 流水线会把行尾空格当成 lint 错误;pandoc 导出 PDF 时,标题前缺少空行会导致层级坍塌。
这些问题在源头不起眼,但在团队协作、版本控制、多平台发布中会形成连锁反应:PR 里出现大量无意义的空格 diff、CI 格式检查失败让发布卡住、同一份 .md 在不同渲染器里呈现不一致……提前把格式修干净,既是对自己稿件的负责,也是对下游工具链的尊重。
MeTool 的 Markdown 格式校验与自动修复工具,基于业界最广泛使用的 markdownlint 规则集,在浏览器本地运行 — 内容不离开设备,适合处理内部草稿和未公开内容。
自动修复能处理的 7 类常见格式问题
① 标题 # 号后缺少空格(MD018 / MD019)
很多人习惯打 ##标题,在浏览器预览里看起来没问题,但严格的渲染器会把它当成普通文本。自动修复会在 # 号后插入规范的空格:## 标题。
② 标题前后缺少空行(MD022)
标题紧跟在正文后面不换行,在一些渲染器和导出工具里会导致标题与上文"粘"在一起,层级错乱。自动修复会在标题前后各插入一个空行。
③ 行尾多余空格(MD009)
行尾空格在 Markdown 里有特殊含义(两个空格 = 强制换行),但无意的尾随空格会造成 Git diff 噪音、CI lint 失败。自动修复会清除无意义的尾随空格。
④ 有序列表序号格式不一致(MD029)
有些编辑器或复制粘贴场景会让有序列表全写成 1. 1. 1.,GitHub 能渲染,但 Word / PDF 导出工具可能会混乱。自动修复会让序号变成 1. 2. 3. 标准递增。
⑤ 列表标记后空格不对(MD030)
规范要求 - 后跟一个空格,有些工具会产生两个或零个空格。自动修复统一为单空格。
⑥ 文件末尾缺少换行(MD047)
POSIX 标准要求文本文件末尾有换行符。缺少换行会导致 Git 提示 "No newline at end of file",多人协作时容易产生不必要的 diff。
⑦ 硬 Tab 缩进(MD010)
代码块外的 Tab 字符在不同渲染器里宽度不一致。自动修复将 Tab 替换为 4 个空格(Markdown 缩进标准)。
什么时候用格式修复,什么时候用 Prettier?
两个工具定位不同:
- 本工具(markdownlint 修复):只修复明确的格式违规,不重写内容。适合"帮我把这份别人发来的 .md 修干净"场景,改动最小,不会意外折行或改变排版意图。
- Prettier:风格统一工具,会对整个文档做再排版 — 折行宽度(默认 80 字符)、标点前后空格、列表缩进全部重新整理。适合团队 CI 中强制统一风格,但改动较大,不适合"只想修几个 lint 错误"。
建议工作流:先用本工具修复格式错误 → 再用 Markdown 编辑器做内容润色 → 最后发布到 公众号 / PDF。
在 CI / Pre-commit Hook 里做格式检查
本工具专为"随时修一篇 .md"的手动场景设计。如果你管理的是一个 Markdown 文档库或文档站点,建议配合以下方案做自动化保障:
- markdownlint-cli2:在本地或 CI 里运行
markdownlint-cli2 "**/*.md",--fix 参数自动修复可修复项,退出码非 0 时让 CI 失败。 - pre-commit hook:配合 husky + lint-staged,提交前自动对 changed .md 文件运行 markdownlint --fix,只拦截有问题的提交。
- GitHub Actions:在 PR 里添加 markdownlint-cli2 step,让格式检查成为合并门控的一部分。
上述方案都基于与本工具相同的规则集,浏览器端的修复结果和 CI 端完全一致。
