使用 markdownlint-cli2 实现 Markdown 批量格式修复：一次完整的实战记录

在整理一个包含大量 Markdown 文档的项目时，编辑器（VS Code）中出现了大量 MD032/blanks-around-lists 的提示，意思是“列表前后应有空行”。由于涉及文档数量众多，手动修复非常耗时，因此我们尝试寻找一键修复的方法，以下是完整的排查与解决过程记录。

初步调查：确认提示信息

在 VS Code 中安装了官方推荐的 Markdown 插件（David Anson 的 Markdownlint）后，文档中出现了大量如下提示：

1

MD032/blanks-around-lists: Lists should be surrounded by blank lines

这属于 markdownlint 的一条格式规则，主要目的是增强可读性和统一性。

查找自动修复工具

我们首先了解到了 markdownlint-cli2 工具，它是一个命令行工具，支持 lint 多个文件，也支持批量修复。

安装 markdownlint-cli2

可使用如下命令全局安装（或使用 npx 临时运行）：

1

npm install -g markdownlint-cli2

执行修复命令

最关键的是使用 --fix 参数：

1

markdownlint-cli2 "**/*.md" "#node_modules" --fix

其中：

• "**/*.md" 表示匹配当前目录及子目录下所有 .md 文件
• "#node_modules" 表示排除 node_modules 文件夹
• --fix 表示自动修复支持的规则

执行后终端输出显示：

1

Summary: 25 error(s)

可以看到诸如 MD032 的错误已被成功修复。

处理未修复的规则

自动修复后，还剩下一些不能自动修复的错误，包括：

可选配置：禁用部分规则

在 .markdownlint.json 中可禁用不希望使用的规则：

1
2
3
4
5

{
  "MD013": false,
  "MD036": true,
  "MD040": true
}

补充说明：关于误传的 markdownlint-cli2-fix

在过程中我们曾尝试安装名为 markdownlint-cli2-fix 的包：

1

npm install -g markdownlint-cli2-fix

但发现该包并不存在，最终确认：markdownlint-cli2 本身已内置 --fix 功能，不需要安装额外的工具。

总结

通过 markdownlint-cli2 --fix，我们顺利解决了 Markdown 项目中的批量格式问题，尤其是大量 MD032 报错，极大提升了文档质量和维护效率。结合配置文件与简单的脚本处理，其它无法自动修复的错误也可以高效清理。

对于文档量大或协作性强的项目，建议将 lint 步骤加入 CI/CD 流程，确保格式统一、阅读体验良好。