如果你写过几个GitHub项目的README或者在公司里维护了一套技术文档肯定遇到过这种时刻写的时候很爽看的时候崩溃。一份几千行的Markdown文件标题层级乱成一锅粥表格的竖线对不齐目录要自己手动数标题编号改一个章节名就得全文再排查一遍。这不是你一个人的问题是所有长期用Markdown写作的人共同的痛点。我自己的文档工作流里Markdown All in One负责把所有重复劳动变成快捷键MarkdownLint负责在我写出不规范的格式时第一时间提醒两个插件配合起来基本可以把Markdown写作从“手工排版”变成“只管内容”。这篇教程就来好好聊一聊Markdown All in One和MarkdownLint这两个VS Code插件的完整用法插件下载安装、核心功能拆解、配置调优、配合使用的完整流程以及我踩过的一些坑。适合刚接触VS Code写文档的新手也适合想看看到底还有哪些隐藏技巧的老手。1. Markdown All in One先把手头最烦的活儿干掉1.1 插件下载与安装别在扩展市场里找错版本先解决插件从哪里来。打开VS Code左侧扩展面板搜索“Markdown All in One”确认Publisher是Yu Zhang这是最主流的版本插件下载量在千万级别还在持续维护。需要注意扩展市场里有一些名字很像的插件下载前先看一眼发行者和更新时间避免装到很久不维护的替代品。安装完成后VS Code会提示重新加载窗口不用急重启一次就行。装完之后别急着开写先花两分钟把基础配置过一次。这个插件大部分功能是开箱即用的真正需要手动配置的不多但有两个开关我建议一上来就设置好一是“Markdown Auto Guess Encoding”如果你经常打开其他工具生成的Markdown文件开启后可以避免中文乱码二是文件关联配置确保.md、.markdown后缀的文件都被识别为Markdown语言而不是纯文本否则插件功能不会触发。这里也顺手回应一下一直有人问的“markdown all in one 插件下载”问题不要从非官方渠道下载打包好的插件文件直接在VS Code扩展市场安装最省心升级也方便。如果网络环境不稳定导致下载失败可以多试几次或者用VS Code的离线安装包方式加载本地vsix文件但版本兼容性需要自己确认不如在线安装省事。1.2 目录生成、表格格式化、快捷键操作到底怎么用Markdown All in One最核心的几个功能我觉得是目录生成、表格格式化和基于光标的编辑辅助。先说目录生成。当你写了一份带多级标题的长文档在顶部手动列目录是一件极其痛苦的事每加一个章节都要跑去更新编号。这个插件只需要在想要插入目录的位置打开命令面板CtrlShiftPmacOS上是CmdShiftP输入“Markdown All in One: Create Table of Contents”回车目录就会自动生成。生成后的目录自带锚点链接点击就能跳到对应标题。以后标题改动只需要运行“Update Table of Contents”就能同步目录不用再人工维护。这里有个小细节很多人没用上目录生成命令并不是只能生成一级目录。插件默认会按照当前文档的标题层级生成多级目录但如果你只想生成两级可以在设置项里调整toc levels参数。我一般设置成2也就是只生成一级和二级标题的目录这样看文档的人不会被过长的目录淹没维护起来也更轻松。目录的样式也可以调整默认是普通列表形式可以改成带引用块的样式这个看团队风格不强求。再说表格格式化。Markdown里写表格真正对齐的其实是渲染后的效果而源码里如果不对齐审阅源码时会特别难受。这个插件的格式化能力会把表格的各列按最长内容补齐空格让源码中的竖线整整齐齐。实际操作时不用专门跑去格式化表格直接全选表格内容右键选择“格式化文档”或者配置好保存自动格式化一保存就自动对齐。举个实际例子。下面这种常见的歪歪扭扭的表格| 功能 | 快捷键 | 说明 | | --- | --- | --- | | 加粗 | CtrlB | 选中文字加粗 | | 斜体 | CtrlI | 选中文字斜体 | | 链接 | CtrlV | 粘贴链接并选中文字 |格式化之后会变成| 功能 | 快捷键 | 说明 | | ---- | ------ | ---------------- | | 加粗 | CtrlB | 选中文字加粗 | | 斜体 | CtrlI | 选中文字斜体 | | 链接 | CtrlV | 粘贴链接并选中文字 |格式化的意义不只是好看。表格长期不对齐在多人协作时合并冲突会变得非常难处理因为每个人改动的列位置在源码里是错位的。采用保存即格式化之后整个团队的表格源码格式就能保持一致这对代码评审非常有帮助。再说快捷键。这个插件提供了一组很顺手的Markdown编辑快捷键最常用的几个CtrlB加粗、CtrlI斜体、CtrlM切换数学环境公式块、AltShiftF格式化文档、CtrlShiftK删除整行。这些快捷键表面上看是省了个鼠标操作但真正用顺之后写文档的节奏会明显加快因为你不再需要把手从键盘挪到鼠标上去点按钮了。还有几个隐藏的编辑辅助功能在列表项里按Tab可以让当前行缩进成为子列表项按ShiftTab可以提升一级在列表连续输入时回车会自动延续列表连续按两次回车可以退出列表如果你在写任务清单可以直接用快捷键切换复选框状态。这些功能看起来简单但组合起来已经覆盖了日常Markdown写作的大部分重复操作。2. MarkdownLint写规范文档的“格式警察”2.1 认识规则体系MD编号背后到底是一条什么规则MarkdownLint是一个针对Markdown格式的静态检查工具作用类似于代码里的ESLint。它会把文档里不符合规范的写法标记出来并给出对应的规则编号和说明。在VS Code里安装“markdownlint”扩展后打开一个Markdown文件有问题的行会在编辑器里以波浪线标出鼠标悬停可以看到问题描述和规则编号例如MD013表示行长度超限MD024表示标题重复。初次接触MarkdownLint的人最容易被那堆MD编号吓到。其实规则本质上就三大类一类是可自动修复的格式问题比如MD003要求标题样式统一、MD009要求行尾不要多余空格一类是结构性约束比如MD025要求文档中只能有一个一级标题、MD001要求标题层级不能跳级还有一类是风格建议比如MD013对行长度的限制、MD036要求不要把普通文本加粗当成标题用。把这些规则分成大类去理解就不会觉得每条规则都需要背遇到某条报错时只要想一下“这条管的是格式还是结构是必须修还是可以接受”处理起来就很快了。常见规则的解读可以整理成一张速查表规则编号检查内容常见触发场景MD001标题层级递增从一级直接跳到三级MD003标题样式一致混用#和##样式MD013单行长度限制默认80字符长URL或长中文句子MD024不同章节内出现相同标题两个“背景”小节MD025文档中只能有一个一级标题文件开头有多个#标题MD033内联HTML文档里写了原始标签MD036加粗文本被当作标题使用用标题代替了#标题MD041文档首行应为标题文件第一行是空行或正文这张表不用背遇到问题再查就行。重点是要理解每一条规则存在的意义比如MD025要求文档只能有一个一级标题是因为很多文档工具会默认把第一个一级标题当作页面大标题出现两个的话可能影响目录生成和页面结构。2.2 按团队习惯定制规则别让警察管得太宽MD013这条我第一个关掉。默认行长度限制是80字符这个阈值对中文很不友好一行中文句子很容易就超过80字符而且中文文本的换行逻辑和英文完全不同强行换行反而影响阅读。我自己在个人项目中会直接关闭MD013在公司文档中则把阈值调到120并坚持“一句一段不要过长”的写作习惯。关闭某条规则有三种常见方式。第一种是在工作区的settings.json里配置markdownlint的enable规则。VS Code里可以通过命令面板输入“Preferences: Open Workspace Settings (JSON)”打开工作区设置文件然后写入{ markdownlint.config: { MD013: false, MD024: { siblings_only: true }, MD033: false } }第二种是在项目根目录放一个.markdownlint.json或.markdownlintrc文件这个文件能被所有支持MarkdownLint的工具读取包括VS Code扩展、命令行工具和一部分CI平台。示例{ default: true, MD013: false, MD024: { siblings_only: true }, MD033: false, MD041: false }第三种是局部禁用。如果某个特殊情况确实需要违反规则可以在文件顶部或代码块内使用注释禁用。文件顶部加上这样一行就会对整个文件关闭指定规则!-- markdownlint-disable MD013 MD033 --需要恢复时在文件指定位置加!-- markdownlint-enable MD033 --这种局部禁用适合那些规则本身合理、但某个文件因为内容特殊确实无法遵守的情况不要把局部禁用当成日常手段否则规则形同虚设。我的经验是先全量开启跑一次团队现有的文档库看哪几条规则反复误报再一次性调优不要一上来就关一堆规则那样还不如不装Lint。3. 从零配置一套能自动修复的Markdown工作区3.1 搭建项目级配置一次配置多人受益如果你只是自己写两篇笔记直接在VS Code用户设置里把两个插件装好就够了。但如果是在团队项目里维护文档我的建议是把配置放进项目跟随版本库走这样每个开发者的编辑器行为都会一致不会出现“你保存时格式化过了我没过格式”的混乱。具体操作流程是这样的。首先在项目根目录创建.markdownlint.json写入团队统一的规则配置。比如我们团队的使用习惯是关闭MD013和MD033调整MD024为同级标题允许重复其余规则保持默认。然后打开工作区设置配置以下内容{ editor.formatOnSave: true, editor.codeActionsOnSave: { source.fixAll.markdownlint: explicit }, [markdown]: { editor.defaultFormatter: yzhang.markdown-all-in-one, editor.formatOnSave: true } }这里第一个配置是打开保存时格式化第二个配置是保存时自动执行MarkdownLint可以自动修复的规则。注意第二个配置的值在不同版本的VS Code里写法略有区别老版本写成source.fixAll.markdownlint: true就行新版本建议用“explicit”这种显式写法。第三个配置是把Markdown的默认格式化器指定为Markdown All in One这个很关键否则保存时可能用的是VS Code自带的格式机制行为不受控制。配置完成后团队里每个人拉取代码后打开任意Markdown文件保存时就会自动格式化并修复Lint问题大家提交到仓库里的文档格式天然一致。3.2 从新建文件到规范提交一次完整的写作闭环演示理论讲了不少这里跑一遍完整的实操流程跟着做就能搭好一个每天都会用的Markdown写作环境。第一步创建一个新的Markdown文件test.md第一行先写一级标题“产品需求文档”。验证一下如果此时文件首行是空行MarkdownLint会报MD041错误因为规则要求文档首行应该是标题。接着写一个二级标题“背景”回车后光标会被自动带入新的段落此时连续输入几段文字其中一段故意写得很长超过120字符看你配置的MD013阈值会不会报错。如果你按上面的示例关闭了MD013这里就不会有波浪线否则会看到提示。第二步故意用两种标题样式混写比如“背景”用##开头“目标”用一个三级###开头且前面没有二级标题直接出现三级那么MD001会立刻提示标题层级跳级。这种问题在写作过程中很常见其实大部分人并不是故意跳级而是复制粘贴时把级别弄乱了有Lint在旁边提示就能第一时间发现。第三步写一个表格故意不按列对齐保存。这时候Markdown All in One会自动把表格格式化所有列宽被补齐。同时MarkdownLint里关于表格的规则会检查表格前后是否需要空行如果你表格前面紧贴文字没空行会被提示。格式化完成后从标题、正文、表格到列表都应该是没有错误提醒的状态。第四步在文首生成目录。把光标放到一级标题和二级标题之间运行“Markdown All in One: Create Table of Contents”目录会插入到当前光标位置。生成后你会发现目录里“背景”和“目标”都在并且带锚点链接。后续你在文档中间加了一节新的二级标题再次运行“Update Table of Contents”目录会同步更新。最后一步打开预览确认整体排版没有异常。到这里一个文档从零到“格式规范、目录齐全、表格整齐”的全过程就完成了。这套流程熟练后写一份再长的文档也不需要在排版上花太多心思主要是把精力留给内容本身。4. 高频问题与排查实录4.1 表格格式化后对不齐或者整个文件被改乱Markdown All in One格式化表格有一个常见坑当表格里有很长的URL、中英文混排或者Markdown内联格式时格式化结果可能和预期不一致。比如一列里有很长的一串URL格式化后会把整个表格撑得很宽看起来更加凌乱。这其实不是插件出错而是Markdown表格的渲染规则就是这样任何额外加的空格都只是为了源码整齐最终显示宽度不受源码空格的左右。另一种情况是格式化后文件乱掉了。排查思路是先确认是不是格式化给扩大了范围。默认的格式化命令会处理整个文件如果你只想格式化一个表格不要用全文档格式化直接右键选“格式化选定内容”或者选中表格区域后再运行格式化文档。另外如果文件前几行有非Markdown的模板代码比如某些文档生成器需要YAML头信息而配置了错误的默认格式化器或没有正确识别语言范围保存时就有可能把不该动的部分也动了。遇到这种文件先在设置里把这个文件的关联语言改成markdown或者在工作区设置里关掉保存自动格式化改用CtrlShiftP手动格式化问题一般就能解决。4.2 MarkdownLint报错看不懂有些规则明明不需要最多人问的问题是“MD013行长度限制报错怎么办”原因前面已经说过这一条建议按团队实际情况调整。第二个高频问题是MD024重复标题很多文档结构里不同章节下出现相同的小标题是很正常的比如“安装步骤”和“常见问题”下面都有“注意事项”这时候MD024默认会报错。解决方案是把它配置成siblings_only模式只检查同一父级下的兄弟标题是否重复这样“安装步骤”下的“注意事项”和“常见问题”下的“注意事项”就都能合法存在了。第三个高频问题是MD033内联HTML有些人喜欢在文档里嵌入自定义的div容器或图片宽度设置这确实会踩到这条规则。MD033本身是为了保证文档的Markdown纯粹性但如果团队确实需要写一些受限的HTML可以把MD033关掉或者用局部禁用注释只关掉相关文件的检查。还有一类误报来自标题里的中文冒号、括号等字符比如使用全角标点时某些规则可能会误判。遇到这种报错不用硬着头皮改文档先查看规则文档里的参数看能不能通过配置规避。我的建议是准备一个团队级的.markdownlint.json把规则讨论清楚后固化下来新成员一进来就不用纠结。处理问题时直接在VS Code底部打开Problems面板里面会列出当前文件所有MarkdownLint错误及编辑器语法问题点击任意一条都能跳转到具体行比在编辑区里逐个找波浪线快得多。4.3 保存自动修复没有生效怎么排查配置都写好了保存文件却发现没有自动修复这是另一个常见问题。检查顺序我建议这样来先确认安装的是“markdownlint”扩展而不是命令行工具命令行工具本身不会在VS Code里画波浪线和自动修复再看编辑器右下角的语言模式确保不是纯文本模式纯文本模式下MarkdownLint不会运行接着按CtrlShiftP打开命令面板输入“Markdownlint: Fix all”如果能执行成功说明规则和配置都在问题出在保存触发上。保存触发这一环最常见的原因是你使用的VS Code版本中editor.codeActionsOnSave的写法不对或者和你安装的其他插件形成了冲突。比如有一个常见的场景同时装了Prettier和其他Markdown格式化工具默认格式化器被抢走保存时Prettier先跑了一遍把Markdown Lint的修复结果又覆盖了。排查方法非常直接把其他候选格式化器暂时禁用只保留Markdown All in One再试一次保存。如果好了就是抢格式化器的问题把[markdown]的defaultFormatter固定成yzhang.markdown-all-in-one即可。另外一个小提醒如果你在公司使用远程开发容器或GitHub Codespaces插件是在容器里跑的配置文件也是容器工作区里的别改反了。只改本地的settings.json不能影响容器内环境一切以工作区设置和项目里的.markdownlint.json为准。用了这么久的Markdown All in One和MarkdownLint我最大的变化其实不是文档更好看而是终于可以放心大胆地写长文档了。以前写一份几十页的文档光是整理标题层级、调表格、改目录就能耗掉半天现在保存一下全都自动处理剩下那点报错信息一眼就能看懂。如果你刚开始搭这套环境别追求一步到位先装插件、把保存自动格式化打开把MD013这类明显不适合中文的规则关掉用一段时间之后再按自己的写作习惯慢慢收敛规则。宁可少配几条规则也要保证每条规则都真的有价值否则规范很快就形同虚设了。