你有没有遇到过这种情况在VSCode里写Markdown文档写着写着列表缩进全乱了套表格对齐全靠手动敲空格标题层级一跳就是三级文档里同一级标题还用了几种不同的符号。文档好不容易写完一预览又发现哪里漏了个空格渲染出来格式怪怪的。我之前就有段时间特别抗拒在VSCode里写长文直到把MarkdownLint和Markdown All in One这两个插件真正研究明白才算理顺了整个写作流程。这篇教程就专门讲这两个插件它们各自解决什么问题、怎么配置最顺手、实际写作中会遇到哪些坑以及在图片、表格、预览、导出这一整条工作流里怎么把它们用好。这篇内容适合刚接触VSCode里写Markdown的新手也适合已经装了插件但没搞懂配置逻辑的老手。我会先拆解两个插件的核心定位再逐个功能讲配置细节最后用踩坑记录的方式还原几个实际场景。整个内容基于我长期在VSCode里写技术文档、博客和个人笔记的真实经验可以照着操作。1. 先搞清楚这两款插件各自管哪摊事1.1 Markdown All in One的本质把排版工具集中到一键Markdown All in One的设计思路很直接把Markdown写作过程中最频繁、最机械的排版操作集中起来。它不是一个语法检查工具而是一个效率工具。它的核心能力包括文档格式化、目录生成、标题编号、有序列表续写、表格对齐、常见快捷键加粗、斜体、删除线、任务列表以及数学公式支持。在实际写作里它的价值最典型的场景是格式化。我给你看一个真实的例子。这是格式化之前的一段列表1. 上午安排 - 写周报 - 整理本周数据 2. 下午安排 - 开会 - 改Bug这段列表在预览时虽然能正常渲染但缩进混乱、层级不清晰你很难一眼看出哪些项属于同一个层级。按下格式化快捷键后它会整理成这样1. 上午安排 - 写周报 - 整理本周数据 2. 下午安排 - 开会 - 改Bug缩进清晰了嵌套关系一目了然。这种整理靠手敲既费劲又容易出错尤其当文档很长、嵌套超过两层的时候Markdown All in One就体现出了真正的价值。1.2 MarkdownLint的本质把规范检查变成编译器报错MarkdownLintVSCode插件ID是davidanson.vscode-markdownlint做的事情和代码Lint工具类似。它内置了一整套Markdown规范规则实时扫描你的文档哪里不符合规范就在哪里画出黄色波浪线并且悬停时给出规则编号和修改建议。它检查的不是错别字而是格式规范。比如标题的#后面必须跟一个空格列表项前后必须有空行文档不能连续出现两个以上的空行标题不能重复文件必须以空行结尾。这些规则标准来自Markdown社区长期积累的最佳实践本质上是在帮你维护一个可读性高、可维护性强、跨平台渲染稳定的文档。有意思的是MarkdownLint跟代码编译器一样也会报出你觉得没问题的问题。第一次用的时候你会觉得自己写个笔记怎么到处是黄线。这很正常因为它的规则默认面向通用场景尤其是英文技术文档场景。所以掌握配置规则、按需开关规则是这个插件能否真正好用的关键后面的章节我会详细展开。1.3 两者搭配工作的逻辑一个管格式好看一个管结构正确有人会问格式化工具和Lint工具是不是功能重复其实差异非常明显。Markdown All in One管的是排版好不好看它能把列表缩进整理整齐、把表格管道符对齐、让文档在源码模式下也有阅读舒适度。MarkdownLint管的是结构规不规范它检查的是标题层级是否跳跃、列表是否该有空行、行尾空格是否存在、代码块是否标注了语言。两种工具从不同维度保证Markdown文档的质量。我举个具体场景说明区别你写了一个三级标题前面忘了加空格写成###标题。Markdown All in One的格式化功能不会主动帮你修正这个错误因为它默认尊重你的输入但MarkdownLint会立刻给出MD018/MD019之类的规则警告。反过来列表缩进乱了MarkdownLint同样可能报错但它不会帮你自动整理出好看的层级还是要靠Markdown All in One的格式化一键搞定。一句话总结Markdown All in One是整理档位MarkdownLint是质检环节。先整理再质检或者边写边看质检提示及时整理就是最稳定的写作节奏。2. Markdown All in One的核心功能和配置细节2.1 格式化功能背后的缩进规则Markdown All in One的格式化快捷键Windows/LinuxCtrl K然后Ctrl FmacOSCmd K然后Cmd F这个快捷键跟VSCode内置的格式化文档是同一个入口所以按这个快捷键时VSCode会调用所有支持的格式化器。如果文档里还存在其他格式化器比如prettier也声明支持Markdown那实际生效的可能不是Markdown All in One。如果你只想用Markdown All in One可以在VSCode设置里搜索editor.defaultFormatter针对Markdown文件单独指定格式化器。格式化的核心规则在列表缩进上。默认情况下它采用的是自适应缩进策略也就是根据有序列表的编号宽度动态计算缩进量。比如1.这种单字符编号子项缩进一般是2个空格10.这种双字符编号子项缩进会变成3个空格。这个策略保证了编号宽度变化时子列表文本依然有一个清晰的视觉边界。如果你想固定缩进量可以改这个配置{ markdown.extension.list.indentSize: inherit }可选项是adaptive自适应和inherit继承父级缩进。inherit模式下子项缩进始终和父级文本位置保持固定关系不随编号位数变化。用了一段时间我建议大部分场景保持adaptive默认值视觉效果更整齐如果你有持续发布的文档且希望在源码模式下复制粘贴时更容易对齐可以试inherit。还有一个容易被忽略的配置markdown.extension.orderedList.marker它决定了格式化后有序列表的编号样式。默认one表示所有列表项都写成1.因为Markdown规范里1. 2. 3.不是必须的渲染时会自动递增。如果你想在源码里就看到连续的编号改成ordered即可。2.2 目录生成与标题编号长文档的骨架系统Markdown All in One另一大杀器是自动目录。在文档任意位置打开命令面板CtrlShiftP/CmdShiftP执行Markdown All in One: Create Table of Contents插件会根据当前文档的标题结构自动生成一个带锚点链接的目录列表。目录生成后是纯Markdown列表可以随意调整顺序、删除不想要的项。它还有一个很贴心的设计格式化目录时标题缩进和编号会重新计算如果有标题被删除或者新增你只需要在目录区域上右键选择更新目录或者执行Markdown All in One: Update Table of Contents它会自动同步。在实际项目里我最常用的配置是这几个{ markdown.extension.toc.levels: 1..3, markdown.extension.toc.orderedList: false, markdown.extension.toc.updateOnSave: true, markdown.extension.toc.unorderedList.marker: - }levels目录包含的标题级别。1..3表示只纳入一级到三级标题四级及以下小标题不展示避免目录过长。orderedList目录是否使用有序编号。默认false用无序列表符号。updateOnSave保存文档时自动更新目录。建议开启省掉手动更新的麻烦。unorderedList.marker目录列表使用的符号我偏好-也有人喜欢*按团队规范来就行。标题编号功能在长文档里也很实用。开启后文档中的标题会自动加上1.、1.1这样的编号前缀。可能你会想这和我手写有啥区别区别在于它能在你调整标题层级时自动重新编号整篇文档不会出现编号断层。不过这个功能我个人用得不多因为很多发布平台会自动编号而且源码里带着编号会显得乱。如果你要追求所见即所得的源码整洁度建议在正式发布前关闭{ markdown.extension.showExplorer: false, markdown.extension.syntax.decorations: false, markdown.extension.sectionNumbers: false }2.3 快捷键体系与数学公式支持Markdown All in One提供了一套很完整的快捷操作经常用Markdown写文档的话这套快捷键能显著减少鼠标操作。我整理了一份常用快捷键表功能Windows/LinuxmacOS加粗CtrlBCmdB斜体CtrlICmdI删除线AltSAltS切换任务列表AltCAltC跳到下一个标题CtrlShift]CmdShift]跳到上一个标题CtrlShift[CmdShift[折叠所有区域CtrlShift[CmdShift[格式化文档CtrlK CtrlFCmdK CmdF其中跳到下一个标题在超长文档里非常实用配合折叠功能可以快速导航。任务列表的切换快捷键AltC在待办清单场景里几乎是刚需按一下在[ ]和[x]之间切换比鼠标点选快得多。数学公式支持方面Markdown All in One内置了KaTeX渲染器。你在Markdown里写的$公式$或$$ 块级公式 $$在预览面板中会被渲染成标准的数学公式。这个功能对于写技术文档、算法笔记、统计报告非常友好。注意这个渲染只影响预览保存的源文件里依然是纯Markdown文本换到其他编辑器时公式语法依然通用没有锁定风险。2.4 几个容易被忽略但影响体验的配置项除了上述主要配置还有几个不那么显眼但实际体验影响很大的项markdown.extension.toc.plaintext目录生成时是否使用纯文本形式。默认false意思是生成带链接的Markdown列表如果设置为true目录就只是纯文本行。建议保持false带链接在预览和导出时可以直接点跳转。markdown.extension.preview.autoShowPreviewToSide创建新Markdown文档时是否自动打开预览侧边栏。有人觉得自动弹出来烦人有人觉得省事。我建议关掉避免每次新建文件都被预览面板打断思路。markdown.extension.print.absoluteUrlPath导出HTML时图片是否使用绝对路径。如果文档里用了相对路径导出到其他目录时图片会找不到这个配置有必要看一眼。markdown.extension.italic.indicator斜体用什么符号包裹。默认*也可以改成_。但要注意如果追求通用性建议保持默认部分平台对_包裹的斜体支持不完整。3. MarkdownLint的规则体系拆解从波浪线到规则意识3.1 先建立规则分类视角就不会被几十条规则吓到MarkdownLint内置的规则数量很多VSCode插件默认启用的也有大几十条。我第一次看到设置项里密密麻麻的规则编号时头是大的。但翻了几天之后我发现这些规则其实可以归成几大类规则类型典型规则编号检查内容标题规范MD001/MD003/MD018/MD019/MD025/MD041标题层级递增、标题风格、#后空格、H1数量列表规范MD004/MD005/MD007/MD029/MD030无序列表符号统一、缩进大小、有序列表编号空白与换行MD009/MD010/MD012/MD022/MD031/MD032行尾空格、禁止Tab、空行数量、块级元素前后空行行宽限制MD013单行最大长度内容规范MD024/MD026/MD033/MD034/MD036标题重复、标题行尾标点、内联HTML、裸URL、加粗伪装标题兼容与国际化MD040/MD045/MD047代码块语言标注、图片alt文本、文件末尾空行有了这个分类视角你就知道哪些规则是生命线级别的比如标题不加空行会影响部分平台渲染哪些是风格偏好级别的比如有序列表不用连续编号。没必要全部启用也没必要全部关闭按需调整。3.2 最容易被触发的五条规则以及为什么它们会误伤中文写作实际用起来有几条规则几乎天天见。我先说结论MD013行宽限制——默认80字符中文写作几乎必报。原因很简单80个ASCII字符大约能容纳40个汉字而一行的正常阅读长度远超这个值。所以我强烈建议中文文档直接关闭这条或者把line_length调大比如120。MD024标题重复——很多人忽略。默认情况下同一级标题不能出现重复文字。但如果你写项目背景这种标题在第一章和第三章各出现一次就会触发。VSCode插件支持MD024的siblings_only参数设置为true后只检查同级目录下的兄弟标题是否重复跨父级相同的标题不再报错。这是最贴合实际写作需求的配置。MD033禁止内联HTML——这条要看你是否需要。Markdown语法里有些效果确实只能靠HTML标签实现比如高级表格、自定义样式、部分平台的特定渲染指令。如果完全禁用你会在写复杂布局时被卡住。我的建议是直接关掉或者用行内注释临时禁用。MD036使用加粗代替标题——这条规则把单独成段的加粗文本识别为伪标题并告警。中文写作里很多人习惯用加粗段落做小标题如果不关闭几乎到处黄线。MD041文档首行必须是H1标题——适合要求每篇文档有主标题的场景。但笔记、片段、README的局部区块首行不是标题的情况很常见。建议关闭或配合Markdown All in One实际使用习惯看。3.3 配置方式settings.json里的全局配置和项目级.markdownlint.jsonMarkdownLint的配置有层级。全局配置写在VSCode的settings.json里项目级配置写在项目根目录或指定位置的.markdownlint.json或.markdownlintrc文件里。两者同时存在时项目级配置优先生效。全局配置方式{ markdownlint.config: { MD013: false, MD024: { siblings_only: true }, MD033: false, MD036: false, MD041: false, MD040: false } }项目级配置更灵活因为你可以在不同仓库里用不同规范。比如开源项目需要对Markdown提交保持严格规范项目级配置里减少开关个人博客项目则可以宽松一些。这是.markdownlint.json的推荐示例{ default: true, MD013: false, MD024: { siblings_only: true }, MD033: false, MD036: false, MD041: false, MD046: false, ignores: [ CHANGELOG.md, docs/archive/*.md ] }注意default: true表示先启用全部默认规则再用后面的规则逐个覆盖修改。ignores字段可以指定某些文件或目录不检查比如自动生成的日志、历史归档文档省去每次打开都满屏黄线的干扰。3.4 行内禁用与团队协作场景有时候你不想全局关闭某条规则只想在某个特定段落临时禁用。MarkdownLint支持用HTML注释实现行内开关!-- markdownlint-disable MD013 -- 这一行特别长但我不希望它触发行长检查。 !-- markdownlint-enable MD013 --注意disable和enable之间的内容会被忽略检查。如果你在片段里多次使用要确保每次disable都有对应的enable否则后面整个文档都会被静默。团队协作时我通常建议把基础规则MD001、MD003、MD009、MD012、MD022、MD032、MD047保持开启它们保证了Markdown在任何平台都不会渲染翻车而把MD013、MD033、MD036这类偏风格和中文适配的规则放到团队统一配置文件里管理避免每个人本地配置不同导致互相看不顺眼的告警。另外MarkdownLint还有一个命令面板入口MarkdownLint: Fix all auto-fixable problems。执行它可以自动修复那些可以自动处理的规则问题比如行尾空格、标题后空格、列表前空行等。运行完这个命令再配合Markdown All in One的格式化就是一套非常高效的自动整理流程。4. 从编辑到发布图片、表格、预览和导出的完整链路4.1 图片路径的三种写法与相对路径的坑Markdown里插入图片有三种路径写法相对路径、绝对路径、URL地址。日常写作里最值得关注的是相对路径的坑。# 推荐相对当前文件所在目录  # 不推荐依赖盘符或用户目录的绝对路径  # 在线引用 绝对路径在本地预览可能没问题但一旦把文档发到别的电脑、提交到Git仓库、导入博客系统路径就失效了。相对路径才是跨环境最稳的方案。另一个隐形坑是图片文件名里的空格如果文件名是my image.png直接插入会出现渲染失败因为Markdown对路径中的空格解析可能异常。解决方式有两个一是文件名一律用-或_替代空格二是把空格转义成%20。我习惯前者因为文件名看起来也更干净。VSCode里还有一类插件特别有用Paste Image。它能把剪贴板里的截图直接粘贴成Markdown图片引用同时自动把图片保存到指定目录。结合路径设置能让插图工作流大幅提速。常用配置是这样{ pasteImage.path: ${currentFileDir}/images/${currentFileNameWithoutExt}, pasteImage.namePrefix: ${currentDate}, pasteImage.basePath: ${currentFileDir}, pasteImage.insertPattern:  }这个配置的效果是每篇文章在自己的目录下建一个以文件名命名的图片文件夹截图自动按日期命名插入的引用自动生成相对路径。总之图片这块的经验是路径永远写相对路径文件名不要用中文和空格图片统一放在文档同级的images目录下后续无论预览、导出还是换电脑都不会出幺蛾子。4.2 表格编辑的效率技巧对齐、复制与转ExcelMarkdown表格在源码里如果不对齐阅读体验很差。Markdown All in One的格式化功能会把表格的管道符和单元格内容对齐成规整的网格按一次格式化快捷键就行。表格较长时格式化前后的差异极其明显。很多人写完表格之后需要转成Excel或CSV给同事用。最简单的方法是直接在渲染预览里选中表格内容复制后粘贴到Excel但效果取决于平台和粘贴方式。稳一点的方式是用一个小脚本批量转换。Python的pandas库可以直接读取Markdown文件里的表格import pandas as pd tables pd.read_markdown(document.md) for i, table in enumerate(tables): table.to_excel(ftable_{i}.xlsx, indexFalse)要注意pd.read_markdown需要安装tabulate库否则会报错。这个方案特别适合文档里含多个表格的场景一次性批量导出避免手动复制粘贴漏行错列。反向操作也一样Excel表格也可以借助pandas.to_markdown()直接生成Markdown表格然后粘贴回文档。4.3 预览快捷键与Mermaid图表渲染VSCode里打开Markdown预览的快捷键CtrlShiftVmacOS为CmdShiftV当前编辑标签页直接切到预览模式CtrlK VmacOS为CmdK V在侧边打开预览面板边写边看侧边预览模式是我平时用的最多的方式特别适合长文档写作。一边编辑源文本一边看渲染效果发现问题立刻修改。预览面板顶部还有一个跟随光标同步滚动的按钮点击后预览区会跟随源码光标位置滚动定位非常方便。如果你经常在文档里画流程图、时序图VSCode自带预览对Mermaid的支持有限。实际上Markdown All in One和自带的预览器能渲染基础的Mermaid如果你遇到某些图表不显示可以试试Markdown Preview Enhanced这个插件它对Mermaid、PlantUML等图表语言的兼容性要好很多。这类图表语言的代码块就是一个普通的Markdown代码块只是语言标识不同不影响文档在其他平台的可读性只是渲染效果在不同工具里可能不一致。4.4 从Markdown到Word、HTML的导出工作流最稳的导出工具是Pandoc。它是一个命令行文档转换器可以从Markdown转换出带样式的Word文档、HTML、PDF等格式。基本命令pandoc 输入.md -o 输出.docx只要电脑装了PandocVSCode的终端里执行这一行就够了。默认转换出来的Word样式比较朴素如果想用自定义样式模板可以准备一个reference.docxpandoc 输入.md --reference-doc模板.docx -o 输出.docx这个reference-doc可以通过Pandoc自带的模板生成也可以自己做一个写满样式需求的空Word文档作为模板。HTML导出同理指定-o 输出.html就会生成完整的带样式HTML文件可以直接部署到博客。还有一个容易踩的坑是图片路径。Pandoc默认以原文档所在目录为基准解析相对路径图片如果导出后的文档被移动了位置图片又没跟着走就会碎图。所以在导出前先确认图片路径是相对路径且目标目录下保留了对应的images文件夹。假如你是用无代码工具串的工作流比如把Markdown转Word的自动化流程接到某个自动化平台上底层思路也是一样的搞清楚路径基准和信息流问题就能解决。5. 踩坑记录与排查链路这几个问题我花了不少时间才弄明白5.1 问题一格式化之后有序列表编号全部变成了1现象文档里有1. 2. 3.的编号格式化后源码里全部变成了1.乍一看以为数据丢了。原因Markdown本身不要求有序列表编号连续只要第一行是1.或任意数字渲染时都会自动以1递增。所以Markdown All in One的格式化默认把后续编号统一改成1.以保持源码最规范。处理如果不在乎源码里的编号显示保持默认markdown.extension.orderedList.marker: one就行。如果在乎源码阅读体验改配置{ markdown.extension.orderedList.marker: ordered }改完之后格式化时会保留连续的1. 2. 3.编号。这个坑的特点是格式化后才发现所以第一次遇到时会有点慌。解决办法其实就是一个配置项的事但不知道原理解释的话很容易误以为文档内容被破坏了。5.2 问题二表格格式化后中文对齐看起来还是歪的现象表格里混有中文和英文内容时即使格式化完源码模式下的列对齐依然不整齐。原因Markdown表格的对齐是按半角字符计算的全角中文字符宽度是半角字符的两倍。Markdown All in One格式化时依然按显示宽度计算所以当某列同时有中文和英文时源码模式下肉眼看起来就是歪的。处理首先明确一个概念表格渲染的最终效果跟源码模式的列对齐没有关系。只要表格语法正确预览和导出的文档都是对齐好的。源码里的歪在渲染层面完全不存在。如果你实在不能接受源码里歪唯一办法是保证同一列的字符类型一致全中文或全英文但这对正常写作来说太刻意了。我最终的选择是接受源码模式的不完美对齐把注意力放到预览面板上。这个心态转变之后反而再没被这个问题困扰过。5.3 问题三MarkdownLint在中文写作场景下满屏黄线的排查链路现象新建一篇中文文档还没写几行编辑器底下已经报了一串规则告警。排查过程先看黄线悬停提示里显示的规则编号比如MD013、MD036。查这些规则的具体内容判断是真错误还是风格偏好。同一文档里如果多条规则都跟中文排版习惯相关直接在配置里一次性处理。改完配置后通过命令面板执行MarkdownLint: Fix all auto-fixable problems自动修复可修复项。如果还有个别的告警确实需要保留比如某条确实违规但你又不想全局关闭规则用行内禁用注释。根因在于MarkdownLint的默认规则面向的是通用英文Markdown文档中文写作时MD013行宽、MD036粗体段落、MD024重复标题这三条几乎必然会造成干扰。中文写作场景下的推荐配置就是我上一章给的JSON示例实测下来能把满屏黄线降到几乎为零同时保留真正有价值的规范检查比如标题层级、空行规范、列表缩进、代码块语言标注这些硬质检。5.4 问题四不同平台的兼容性差异尤其是Obsidian、WordPress和JupyterVSCode里写好的Markdown换到其他平台时经常发现渲染效果不一样。这不一定是你的问题而是Markdown方言的差异。我踩过的几个典型场景Obsidian它支持标准Markdown也支持不少特有语法比如Callout提示块、双链[[笔记名]]、折叠块等。这些语法在VSCode里会显示为普通文本或代码块不算错误但预览效果完全不同。反过来在VSCode里用Markdown All in One生成的目录锚点链接格式可能与Obsidian的解析略有差异有时需要手动调整锚点格式。WordPress经典编辑器不解析Markdown必须依赖插件或者用古腾堡编辑器的HTML块。你从VSCode复制过去的Markdown不会自动变成排版好的内容。如果你用Markdown Pandoc导出的HTML再粘贴进去效果会稳定很多。Jupyter NotebookNotebook里写Markdown单元时标题锚点跳转格式必须手动维护。Markdown All in One的目录生成功能不能直接用在Notebook里通常要靠Notebook扩展比如nbextensions的Table of Contents插件来实现类似效果。这些差异的排查思路是先确认当前平台对标准Markdown语法的支持程度再检查你用的语法是否有方言属性。基础语法标题、列表、表格、引用、链接、图片、代码块在所有平台的表现基本一致扩展语法Callout、双链、折叠、Mermaid、数学公式才是差异重灾区。写作时如果知道文档要发布到多个平台就尽量只用基础语法或者在发布前用Pandoc转换成目标平台的格式再粘贴。用这两个插件真正顺手的标志不是黄线全部消失而是你清楚每一处黄线的来源、知道该让它消失还是该让它保留。我自己的配置稳定下来之后写作流程变成了这样用Markdown All in One的格式化整理列表和表格用MarkdownLint把关结构规范用侧边预览确认渲染效果最后按需用Pandoc导出分发。这些工具不是让你放弃对文档质量的判断而是把那些重复、机械的操作接管过去让你把精力放在内容本身。配置这东西没有绝对标准按你自己的写作场景调一调稳定下来就是最适合你的方案。