VS Code Markdown 插件实战：MarkdownLint 与 All in One 的黄金组合

写作工具这东西最怕的就是装了一堆插件结果不知道该用哪个、也不知道哪个功能解决什么问题。今天我把 VS Code 生态里两个出场率最高的 Markdown 辅助工具放在一起讲MarkdownLint 和 Markdown All in One。这两个插件一个管“规范检查”一个管“编辑效率”配合好之后写文档的体验会从“能用”变成“真香”。这篇教程我会把安装配置、核心功能、常用规则、坑点排查全部过一遍保证你照着操作就能直接上手。先说明一下我自己的使用场景日常工作要写技术方案、维护开源项目 README、整理团队知识库Markdown 几乎是每天都要碰的东西。过去写文档全凭自觉后来有一次因为目录不更新、格式混乱被读者吐槽才认真研究这两个插件。现在我的 VS Code 里Markdown All in One 负责让内容更好写MarkdownLint 负责让内容更规范两者配合一年能省下不少改格式的时间。1. 两个工具到底解决什么问题1.1 Markdown All in One把重复劳动交给编辑器先说 Markdown All in One。它的定位很纯粹辅助编辑提升手写 Markdown 的效率。你在文稿里插入图片、调整标题层级、维护列表序号、生成目录这些看起来很小但频率极高的操作它都能接管。我最早被它圈粉是因为“自动维护有序列表序号”这个功能。写过有序列表的人都知道在中间插入一条内容之后后面每一行的序号都要手动改一遍。装了插件以后你只需要把光标放在任意一个有序列表行按下回车后面的序号会自动重排不需要自己操心。类似的还有任务列表的钩子切换、标题加粗倾斜等快捷键都是平常用得上的。还有一个经常被忽略但非常实用的功能格式化。Markdown All in One 在编辑器里执行“格式化文档”操作时会统一表格对齐方式、修正标题前后的空行、清理多余空格。花几分钟写完的文档按一次格式化版面会干净很多。这个动作非常符合“机器干的活交给机器”的原则。1.2 MarkdownLint给 Markdown 装上代码检查MarkdownLint 的定位跟 Markdown All in One 完全不同它更像一个“裁判”。它不帮你补全内容也不帮你格式化它只负责告诉你当前这次 Markdown 写得不规范哪里有问题应该怎么改。很多新手一开始不理解为什么要检查 Markdown。纯文本格式写出来能预览不就行了吗但当你开始维护一套文档规范或者多人协作写同一个仓库的时候没有统一规则就会出现各种问题有人用四个空格缩进有人用 Tab有人标题跳级从 H2 直接跳到 H4有人代码块不标语言类型导致高亮失效还有人写图片链接时漏掉 alt 文本影响无障碍访问。这些都不是语法错误但是在大型文档体系里它们会变成真实存在的维护成本。MarkdownLint 做的事就是把这些“看起来没毛病但实际不统一”的问题用规则的形式一条条列出。它默认带了 40 多条规则覆盖了标题、列表、代码块、行长度、HTML 嵌套、图片 alt 等几乎所有 Markdown 书写维度。启动方式也灵活既能在 VS Code 里实时提示也能在命令行里跑批量检查还能接进 CI 流程让提交代码的时候自动验证。1.3 这两种工具适合什么人用我接触过几类经常用 Markdown 的用户他们对这两个工具的接受度差别很大写技术博客的程序员这类人基本离不开 VS Code装上 Markdown All in One 能明显加快写作节奏MarkdownLint 能让文章格式规范投稿到社区时减少排版问题。维护开源项目的开发者README、CONTRIBUTING、CHANGELOG 这些文档都是很多人一起维护的MarkdownLint 的规则约束能起到统一风格的作用。写内部知识库和团队文档的产品、运营同学比起 Word 的强排版Markdown 本身已经很轻了再加上工具辅助几乎不用花心思在格式上。纯 Markdown 初学者其实更建议先装 Markdown All in One边写边感受快捷键和自动补全等文档量变多了再引入 MarkdownLint 管规范。如果你只是偶尔写条笔记装不装都无所谓但如果 Markdown 是你的生产力工具这两个插件基本属于“必装清单”里的。2. 安装与初始配置2.1 基于 VS Code 的扩展安装两个插件都直接基于 VS Code 扩展机制运行在扩展面板里分别搜索“Markdown All in One”和“markdownlint”就能找到。前者由 Yiyi Wang 开发后者由 David Anson 维护两个扩展的下载量都是百万级别的认准名字和作者不要装错同名仿品。安装方式不复杂但有一个细节值得提markdownlint 在 VS Code 里有两个相近的版本一个是主包 markdownlint一个是预览版 markdownlint-preview功能差异不大追求稳定就装主包。Markdown All in One 要注意安装后可能需要重载窗口特别是老版本 VS Code如果不重载快捷键可能不会立即生效。如果你有团队环境更推荐用ext install命令直接指定扩展 IDcode --install-extension yzhang.markdown-all-in-one code --install-extension davidanson.vscode-markdownlint这样可以在批量初始化一台新电脑的时候把所有开发配置一键装好。我自己的开发环境初始化脚本里就会带上这两行省去手动点击的流程。2.2 Markdown All in One 的关键设置项安装完成之后Markdown All in One 不会在界面上惊动你但只要打开一个 Markdown 文件编辑器里就会出现它的痕迹。比如你保存带表格的文档它会自动把表格对齐输入带编号的列表按下回车它会自动补全序号。先看设置。在 VS Code 设置面板里搜索markdown.extension会看到所有 Markdown All in One 的配置项。有几个我建议动手调整一下markdown.extension.toc.updateOnSave我一般是直接打开这样每次保存文档时目录都会自动刷新不用手动执行命令。markdown.extension.toc.levels默认生成 1 到 3 级目录如果你文档标题层级多可以扩展范围比如1..6。markdown.extension.orderedList.marker默认有序列表使用1.还是1)的样式团队规范里如果统一要求就在这改。markdown.extension.italic.indicator斜体标记是*还是_默认用星号这个也建议跟团队达成一致。第一次配置不需要记住所有选项核心就是目录、列表、格式化这三块。后面我会在第 3 部分详细拆解每个功能对应的设置。2.3 markdownlint 配置文件初始化markdownlint 安装后默认就启用全部推荐规则。它支持通过项目根目录里的.markdownlint.json、.markdownlint.yaml或.markdownlint.cjs文件覆盖默认规则。它自己的查找顺序是项目根目录、用户目录如果都没有就使用内置默认规则。我的习惯是在第一次准备做团队文档规范时就顺手建好配置文件避免默认规则里某些条款影响写作。初始化比如这样{ MD013: false, MD033: false, MD041: false }false的意思是完全关闭这条规则。MD013默认限制每行最大长度 80 字符对于中文文档特别不友好MD033禁止行内 HTML但某些场景下你需要用 HTML 控制细节排版MD041要求文档首行为一级标题如果你有 front matter 之类的额外结构它就会误报。关于规则编号和含义后面会有专门的小节来讲。配置文件建好之后VS Code 的实时提示会立刻识别它你可以在当前文档里触发一下检查看文本注解和诊断信息是否正常显示。如果之前界面上一片空白说明配置生效。3. Markdown All in One 核心功能逐个拆解3.1 目录自动生成关键是真的能自动更新Markdown All in One 最出名的功能就是自动生成目录。在文档开头的位置按CtrlShiftP输入Create Table of Contents插件会根据当前文档的标题层级自动生成 TOC。默认生成的目录是用无序列表嵌套的并且每一项都带锚点链接点击即可跳转到对应标题非常实用。它还有一个隐藏能力目录自动更新。当你在文档里增删标题、调整标题顺序之后目录可能已经过时。如果你开启了markdown.extension.toc.updateOnSave保存文件的时候目录区块会自动重写标题变了、顺序变了都跟着变完全不用手动维护。不过目录功能也有它的脾气。它把生成的目录区域放在两个标记之间!-- TOC -- - [目录说明](#目录说明) !-- /TOC --如果手动把这两个注释删了或者把插件生成的标题行手动改掉了下次自动更新可能失效。所以千万不要手动去改它生成区域里的内容要用命令重新生成或者在插件设置里调整含标题层级和锚点前缀等参数。还有一个锚点链接的细节中文标题生成的锚点格式是依赖于 markdown 解析器的。GitHub 上面对中文标题生成的锚点就是标题原文去掉标点后加前缀VS Code 预览的锚点可能跟 GitHub 的不完全一致。如果目录是给 GitHub 仓库用的最好在发布之前点一遍最上层的几个链接看看跳转是否正常。3.2 列表序号自动维护与缩进细节有序列表的自动编号是 Markdown All in One 的第二个高频功能。把光标放在文本开头使用CtrlShift[或CtrlShift]可以快速切换当前行层级在有序列表的任意位置敲回车它会在下一行生成下一个序号删除一行后后面的序号也会自动重排。这看着简单实际用起来非常舒服。我写操作步骤或者记录清单时再也不会因为插了一行内容而手动改正整串序号。要注意的是有序列表的缩进层级不同自动编号的规律也不同。Markdown 里的层级缩进常用 2 个或 4 个空格插件会读取你当前行的缩进风格来匹配所以如果你的文档里混用了 Tab 和空格缩进自动编号偶尔会判断不准。原则就是同一个文档保持同一种缩进风格。任务列表也是有序列表的一种它支持- [ ]和- [x]两种格式。Markdown All in One 提供了快捷键快速切换任务状态默认会绑定一个组合键也可以通过命令面板搜索Toggle task list来执行。对维护开发任务清单、发布检查清单的人来说这个功能非常顺手。3.3 格式化动作到底改写了什么Markdown All in One 的格式化功能通常不被人重视但它其实是统一文稿格式的最快方式。执行ShiftAltF格式化时插件主要干这些事统一表格列宽让表格的管道符对齐修正 Markdown 标题之前和之后的空行数量处理列表前后的空行和缩进清理行尾多余空格。这里想提醒一点格式化并不是无副作用的。它在某些情况下会把表格里的单行文本重新分配列宽如果你的表格单元格里有多行内容格式化后行为可能不符合预期。另外格式化不会主动删掉你的空行它只会修整连续多于一个空行的情况所以不用担心文档间距被暴力压缩。推荐的做法是在写完一段内容或整体初稿后手动执行一次格式化。不建议开启“保存时自动格式化”而同时使用 MarkdownLint因为两者对空行、缩进的判断标准不完全一样偶尔会打架。手动格式化能让你明确看到改动的位置再配合 MarkdownLint 的判断做微调效果最稳。3.4 快捷键与数学公式的日常用法Markdown All in One 内置的快捷键和命令非常多我日常高频使用的主要是这几组CtrlB给选中文字加粗再按一下取消CtrlI给选中文字加斜体再按一下取消CtrlShift]和CtrlShift[快速调整当前段落的标题级别AltShiftF与CtrlShiftP组合实现各种转换操作数学公式是它的一大亮点。在 Markdown 中写$公式$对行内公式$$公式$$独占一行插件自带 KaTeX 渲染和快捷代码很多人在 VS Code 里写技术文档时顺带写数学公式不再需要切换到外部编辑器。快捷键覆盖不了的操作可以按CtrlShiftP搜命令前缀“Markdown”里面有一堆快捷命令生成目录、添加锚点、切换任务列表、打开预览、调整标题层级等等。这个命令面板其实是整个插件的入口值得花十分钟点一遍看看有什么命令知道有哪些能力以后按需调用就行。4. MarkdownLint 常用规则实战解读4.1 影响最大的几条默认规则markdownlint 的规则很多都值得学一遍但我见过团队踩坑最多的其实集中在下面这几条MD001标题级别必须逐级递增不能从 H2 直接跳到 H4。这个规则能帮你在长文档里保持信息结构清晰但也有例外场景比如某些模板文档需要在特定区块里用独立标题层级这时候就得按需关闭。MD013每行最大长度限制。默认 80 字符对中文是一个非常不合理的限制因为中文一个字符占一位但语义上相当于两个英文字母。这条规则的开关在中文团队里作用非常大。MD024不允许相邻的标题内容重复。如果两个小节的标题完全一样比如“使用说明”出现多次规则会报错提醒你明确区分章节标题。MD033不允许行内 HTML。这个规则很适合纯文本场景但碰到需要自定义样式的页面时又会变成绊脚石。MD040代码块必须标注语言。这个规则能让你的代码高亮正常显示对技术文档非常友好。MD041文件的首行必须是一级标题或者 front matter。默认规则强制规定如果你的文档是片段式的就可能被误报。MD045图片必须包含替代文本。即所有图片都要写不能直接写成。这是我个人非常推荐保留的一条既规范又利于无障碍访问。以上规则只用一句话概括可能会有偏差但是理解这些核心规则已经可以覆盖日常文档检查的八成场景了。4.2 用自定义配置关掉或调整规则每个项目的文档风格不一样markdownlint 允许你自定义规则默认规则集里没有的情况可以用自定义规则补充不需要的规则可以改成警告级别或者直接关闭。配置文件里规则的值支持几种写法{ MD013: { line_length: 120, code_blocks: false, tables: false }, MD024: { siblings_only: true }, MD041: false }上面的写法是把MD013的行长度限制从默认 80 改成了 120同时不对代码块和表格做限制把MD024从“不允许重复标题”改成只检查相邻同级标题避免在不同层级出现同样标题时误报MD041直接关闭。这里有一个需要注意的细节不同版本的 markdownlint 对规则参数的支持程度可能不同改了配置后最好在编辑器里重新触发一次检查确认没有红色波浪线告警。如果配置没有生效先排除工作区是否覆盖了该配置文件的问题。我一般建议团队把配置文件放在版本库里名字叫.markdownlint.json这样所有成员克隆下来后VS Code 就能自动使用同一套规范不需要再做任何本地设置。这个做法大幅减少“在我电脑上是好的”这类格式冲突。4.3 与 Prettier 一起用时的冲突处理很多人在项目里同时使用 Prettier 做代码格式化Prettier 也会格式化 Markdown 文件。于是出现了 MarkdownLint 和 Prettier 互相打架的局面Prettier 刚刚把列表缩进改了MarkdownLint 立刻给一条警告Prettier 处理了换行MD013 报行太长。冲突的根本原因在于两边处理 markdown 格式的标准不完全一致。解决办法不是关掉其中一个而是设置统一规范。我的做法是先把 Prettier 格式化 Markdown 的关键选项固定下来比如proseWrap设置为never避免自动换行endOfLine设为lf然后在 markdownlint 里把和换行强相关的规则放宽或关闭比如MD013的line_length调大或者直接关闭。这样 Prettier 负责统一文本结构markdownlint 负责检查结构和命名规则两边基本就不再冲突了。还可以在.prettierignore或 markdownlint 配置里分别指定忽略文件比如某些自动生成的 CHANGELOG 文件不需要格式校验。格式工具和代码检查工具不是互斥关系关键在于配置对齐。5. 实操一整套团队 Markdown 规范落地过程5.1 目标场景与目录结构下面用我自己经历过的场景来演示整个流程。当时我们团队要建一套内部技术文档库十几个仓库、上百个 Markdown 文件还要支持后续持续补充。文档分布在docs目录结构大概是docs ├── README.md ├── guides │ ├── getting-started.md │ ├── workflows.md │ └── faq.md ├── api │ ├── overview.md │ ├── auth.md │ └── errors.md └── assets └── architecture.png团队有工程师、产品、运营和技术写作人员水平参差不齐有些人之前完全不熟 Markdown。还有 GitHub 上的公开仓库和内部仓库两类发布平台不同渲染细节也不一样。在这种背景下没有统一的格式规范后续维护基本是灾难。我的目标是在每个仓库的根目录里放一份.markdownlint.json再让所有成员在 VS Code 里装好两个插件实现打开文件就能看到规范提示保存之前就能改掉绝大多数格式问题。5.2 生成配置文件并逐条调整生成基础配置最省事的办法是先让 markdownlint 跑一遍现有文档把告警全部记录下来然后决定哪些规则要保留、哪些要调整。命令行版本能直接输出问题汇总npx markdownlint docs/**/*.md跑完后会发现告警主要集中在行长度、front matter 缺失、标题重复这几类。这时候打开配置文件调整就行比如我当时的初始配置{ default: true, MD013: { line_length: 120, code_blocks: false, tables: false }, MD024: { siblings_only: true }, MD033: false, MD041: false }设置完成后重新跑一次检查告警数量通常会下降得非常明显。如果数量还是大那就放宽更多规则但要同步审视一下规则放宽是否合理不要一关到底。团队场景里规则的松紧直接决定检查的约束力太严会被绕过太松又没意义。针对刚接触 Markdown 的同事我还写过一个简短的文档规范说明内容只有三句话文件名用小写加连字符标题层级逐级递增代码块必须写明语言。其余细节全部交给插件提示不做硬性要求。5.3 在命令行与 CI 中使用 markdownlint-cli2团队的文档量多了以后只靠 VS Code 的提示不够因为总有人忘了看波浪线和诊断信息。要达到真正的“强制规范”就要在提交前或合并时加一道关卡。推荐用markdownlint-cli2它不仅兼容.markdownlint.json配置文件还支持 glob 匹配、忽略文件和输出多种报告格式。安装比较简单npm install -D markdownlint-cli2然后在 package.json 里加一个脚本{ scripts: { lint:md: markdownlint-cli2 \docs/**/*.md\ \README.md\ } }sac时可以执行npm run lint:md如果文档不规范命令会以非零状态退出这样接入 CI 的时候就能直接阻断构建。GitHub Actions 上我用的是actions/setup-node加上npm run lint:md的组合只要文档变动就触发检查。GitLab CI 同理把命令配到.gitlab-ci.yml里即可。在 CI 里集成的价值不是让 lint 在构建报错后才被看见而是把规范从“个人自觉”变成“团队红线”。这是线上文档质量保障中最便宜牢靠的一环。5.4 配合 Git 钩子做提交前的自动检查CI 跑在远端反馈周期相对长。想更早发现问题可以在本地通过 Git 钩子来跑 markdownlint。常见方案是使用husky加lint-staged这样每次提交前只检查暂存区的 Markdown 文件速度很快。npm install -D husky lint-staged npx husky init然后在package.json里增加{ lint-staged: { *.md: markdownlint-cli2 } }这样git commit时所有暂存的 Markdown 文件都会被过一遍规则出错会直接中断提交直到你改规范通过为止。实际用起来最大的感受是通过 CI 检查是“事后补票”通过 Git 钩子是“事中把关”越早发现问题改造成本越低。如果你不想引入 Node 的依赖链也可以用原生的pre-commit钩子脚本在里面调用 markdownlint 的可执行文件。只是跨平台兼容性要自己注意Windows 上写 shell 脚本会有坑。6. 常见问题与排查技巧实录6.1 TOC 不更新或锚点失效目录不更新是最常见的问题。通常表现为你新增了一个标题但目录区没有变化或者目录根本没有生成。原因基本绕不开这两个一是没有开启保存时自动更新二是手动改动了插件生成的目录注释标记。解决办法如果是前者手动执行一次Create Table of Contents命令即可强制刷新如果想一劳永逸打开设置markdown.extension.toc.updateOnSave。如果是后者检查文档里是否保留着插件生成的注释标记!-- TOC --如果没有就要重新生成一个新的目录区块来自动生成。锚点失效的原因通常跟解析器有关。VS Code 内置预览、GitHub、Typora 等对中文标题、特殊符号的处理规则各不相同。如果是用在 GitHub 上我建议生成目录后手动点几个链接验证最重要的标题尽量使用纯文本或拼音避免特殊字符导致锚点不匹配。还有一种更稳妥的做法是给标题手动添加 HTML 锚点不过会触发MD033所以需要权衡。6.2 表格格式化后反而乱了Markdown All in One 的格式化会自动调整表格对齐把管道符对齐成等宽。如果表格内容里有超长文本、URL、中文和英文混排那格式化后的表格可能非常宽甚至阅读困难。更麻烦的是如果一个单元格里存在多行内容格式化可能会把换行拆到完全不对的位置。我的建议是简单表格直接让插件格式化复杂表格还是保持源文本的可读性格式化前先CtrlZ撤销备份。日常写作中偏长的表格我会尽量把它拆成多个小表格每个表格只保留必要的信息列。这样既减少格式化带来的问题也提升源码可读性。6.3 配置了.markdownlint.json却不生效这是个非常容易中招的点。当你的项目目录是多级仓库的时候markdownlint 默认是从“当前编辑文件所在目录开始往上查找配置”但 VS Code 的工作区可能是某个子目录就可能出现配置没被加载的情况。排查顺序先在命令面板执行Markdownlint: Open configuration看看当前文件实际生效的配置是什么。如果里面没有你设置的内容就检查配置文件名是否准确、是否处于合法位置、文件是否是 UTF-8 编码。配置文件的 JSON 格式错误也会导致它完全被忽略编辑器里通常会在“问题”面板给出提示看到红色波浪线的时候多半是 JSON 写错了。还有一个小技巧用.markdownlint.jsonc自动支持注释方便写注释说明每一条规则为什么关闭。.json文件不支持注释规则的意图只能靠 commit 记录去追。推荐给团队用.markdownlint.jsonc并提交到版本库。6.4 图片 alt 文本和相对路径的配合MD045强制要求图片写替代文本。多数人刚开编辑器都会看到图片相关的红色提示。补齐 alt 文本不只是为满足规则也关系到文档的可访问性。屏幕阅读器用户、图片加载失败场景、或者搜索引擎索引都依赖这段文字。建议把 alt 写成“这张图说明了什么”而不要写“图片”两字。模板化文案没有信息量等于不写。路径方面如果使用相对路径要从当前文件的位置出发而不是从仓库根目录出发。很多人在子目录里的文档写图片路径时带上了docs/前缀结果预览崩了这里建议先把文档与 markdownlint 检查跑起来预览时如果图片挂了优先看相对路径是否准确。6.5 团队协作时的规则争议与处理经验最后聊一下推规范流程时最容易遇到的团队阻力。团队里总有同事觉得 lint 规则太严格是“管太多”。我自己解决这类争议的办法其实很简单每一条规则都对应一个具体问题如果团队里举不出真实存在的问题场景那么这条规则就可以关。比如MD013行长度如果设成 80团队写中文文档的人大概率会抱怨。这时候就调成 120甚至关掉。再比如MD033禁止行内 HTML如果团队经常用 HTML 做表格合并或自定义样式规则就当默认false不需要争辩。规则不是越多越严就好它依赖语境。还有一点值得强调最理想的推广方式不是甩一份规则表让别人背而是让每个人都装上这两个插件实时提示即时消化。文档里出现规范问题插件会在编辑的时候直接标出来而不是等到评审的时候整篇反馈大改这种体验上的因果反馈比较顺团队成员也就更容易接受。我自己的实际体会是花一个下午的时间配置好这一整套工具链之后每一个 Markdown 文件都在同一套规范下生成Review 的时候不用再来回抠格式文档维护成本会肉眼可见地降下来。这套流程不仅适合团队项目个人写博客、维护开源仓库同样适用强烈建议你也花点时间把这两个插件真正用起来。