VS Code 写 Markdown 全指南：从编辑、预览到文档工作流

VS Code 的 Markdown 编辑功能现在其实已经远超“给 .md 文件上色”的定位。你可以直接在编辑器里写博客草稿、项目 README、接口说明、测试报告也能通过预览、大纲、目录、图片粘贴、代码块校验和导出工具把文档工作流完整收进编辑器。很多朋友问过我为什么自己写出的 Markdown 格式在别人电脑上打开就乱为什么预览里图片不显示为什么目录生成不出来。大多数时候问题不在一行语法上而是没有把 VS Code 的编辑方式、预览方式和扩展边界弄明白。这篇内容适合想用 VS Code 写 Markdown 的开发者、需要维护项目文档的工程师以及从其他标记编辑器迁移过来、想搞清楚表格和图片为什么会失效的博主。下面按我的实际使用顺序从最小可运行环境开始拆。1. 先搞清楚 VS Code 的 Markdown 编辑到底能做什么1.1 编辑器侧、渲染侧、文件侧各管各的事先建立一个基本认知Markdown 写作在三层同时发生。编辑器侧负责语法高亮、折叠、自动补全、多光标、快捷键、代码块识别。渲染侧负责把 Markdown 文本变成 HTML 效果也就是我们看到的预览窗口。VS Code 的预览有自己的一套解析规则和主题样式。文件侧Markdown 本质是纯文本文件因此它也受到文件路径、编码、图片目录、Git 版本管理的影响。最容易踩的坑就是认为“语法对了预览就一定和发布平台一致”。实际不是这样。同一段 Markdown在 VS Code 预览、GitHub 渲染、静态博客生成器里呈现可能完全不同。比如换行比如标题锚点比如图片大小语法。先分清楚这三层后面遇到问题才知道该去改编辑器配置、改渲染规则还是检查文件路径。1.2 它适合哪些场景不适合哪些场景VS Code 的 Markdown 编辑能力适合这几类工作技术文档和项目 README。博客文章、公众号外部排版前的中间稿。接口文档、操作手册、测试记录。个人知识库配合 Git 做版本管理。不适合的场景也很明确如果你要做复杂的图文排版、大量固定样式的商业文档或者需要严格所见即所得Markdown 和 VS Code 的组合并不合适。VS Code 给的不是“零学习成本的排版”而是“用文本结构控制文档生成流程”。这也是我长期使用它的原因文档可追溯、可 diff、可自动化。1.3 环境准备稳定版加一个空文件夹就够了开始之前做最小准备。从 VS Code 官网下载稳定版按系统安装。不建议为了体验新功能直接上每日构建版写作场景需要稳定。不需要一开始就装大量插件。先建一个空文件夹新建test.md。打开文件后看右下角语言模式。如果显示的不是 Markdown按CtrlK M手动切换。如果之后要长期维护文档建议在项目里建一个docs目录图片单独放到docs/images或docs/assets。如果你的环境是远程开发比如通过 SSH、容器、开发云打开项目还需要注意扩展是否同步、下载是否正常。预览打不开时不要急着怀疑语法先看环境。2. 从新建文件到预览先跑通最基本的编辑闭环2.1 用一份最小文件验证基础流程我建议第一次使用时不要写太复杂的内容先建test.md录入下面这段# 项目说明 这是一段正文。 ## 安装步骤 1. 下载依赖 2. 安装依赖 3. 启动服务 ## 常见问题 - 问题一 - 问题二保存文件然后打开预览。只有这段内容能正常渲染后面的表格、图片、代码块才值得继续测试。2.2 预览的两种打开方式VS Code 里有两种 Markdown 预览方式使用命令面板CtrlShiftP输入Markdown: Open Preview在当前编辑器页打开预览。使用快捷键CtrlShiftV打开预览。CtrlK V在右侧并排打开预览。我日常用得最多的是CtrlK V。因为写文档要边写边看左侧是源码右侧是渲染结果。预览并不是实时保存的它会跟随文件内容的变化刷新但我仍然建议养成CtrlS保存的习惯尤其当项目里还有 Git 时保存习惯可以减少很多问题。如果你打开预览时发现内容空白先不要动文档。可能原因有文件没有保存、工作区未被信任、某个预览相关扩展拦截了渲染。最小验证方式是禁用所有扩展后再打开预览。2.3 目录不是靠手打先看大纲面板很多人问“在 VS Code 中如何把 Markdown 文件的目录显示出来”。这里有两种目录容易搞混。第一种是编辑器左侧的“大纲”面板。当你打开 Markdown 文件视图里的“大纲”会列出所有标题点击可以跳转。如果大纲没显示可以在资源管理器右侧的“视图”列表里把它打开或者运行命令Outline: Focus。大纲依赖标准的#标题语法。如果标题不是用#写的或者用了 HTML 标签临时渲染大纲就不会认。第二种是文档页面上方的“目录”。这个通常需要扩展生成比如 Markdown All in One 的 TOC 功能。也可以自己手写目录链接但维护成本高。建议在文档稳定后再生成目录改完标题要重新更新一次。除了大纲面板CtrlShiftO可以快速打开当前文档的标题列表适合长文档跳转。CtrlP后输入也能打开符号列表Markdown 里的符号就是各级标题。2.4 基础编辑辅助折叠、多光标、任务清单Markdown 文件默认支持折叠。鼠标移到编辑器左侧装订线可以看到小箭头。标题和代码块都可以折叠长文档里很好用。多光标也很有用。按住Alt再点击多个位置可以同时编辑多个列表项或图片路径。批量给多个链接补前缀、给多段代码补语言标记都可以用多光标完成。任务清单用这种格式- [ ] 待办事项 - [x] 已完成事项VS Code 预览通常可以显示成可点击的复选框但点击结果不一定自动写回文件。不要把它当成持久化交互它只是预览效果。真正打勾直接编辑[ ]和[x]更可靠。3. 表格、图片、代码块、链接的编辑细节3.1 换行规则大多数人第一个坑Markdown 换行一直有争议因为不同解析器表现不同。我们在 VS Code 里最需要记住的是想分成两个段落两个段落之间必须有一个空行。想在同一段落内换行可以在上一行行尾加两个空格再回车但很多平台会把这种换行忽略掉。列表项内如果内容太多最好让每行缩进对齐避免渲染时断成两个列表项。很多新手写正文时习惯每句话都敲一个回车。这样在源码里很整齐但预览里可能会全部连成一行。最简单稳妥的写法是一句话一个自然段段与段之间空行。如果文档要发布到不同平台不要依赖“行尾两个空格”这种细节尽量用空行控制结构。3.2 表格对齐、格式化和复制粘贴Markdown 表格的基本写法是| 项目 | 是否支持 | 说明 | | ---- | -------- | ---- | | 预览 | 是 | 默认支持 | | 目录 | 部分支持 | 需要扩展 |VS Code 预览可以正常显示这张表。但编辑器里可能看起来列没有对齐这是正常的不影响预览。如果想在源码层面对齐可以运行Format Document很多 Markdown 扩展会把表格整理成等宽列。表格最麻烦的场景是“从网页或 Excel 复制过来”。网页表格复制进 VS Code 时经常粘贴成 HTML 或带制表符的纯文本不会自动变成 Markdown 表格。遇到这种情况建议先粘贴为纯文本再用查找替换把\t换成|或者使用带表格转换功能的扩展。不要指望复制后直接能用。表格列的多少也需要控制。Markdown 表格在移动端阅读体验很差超过五列就很容易横向滚动。文档里的表格尽量精简列数把次要信息放到正文。3.3 图片相对路径、粘贴和发布路径Markdown 引入图片有三种常见方式  本地图片最容易出现的问题有三个路径写错、文件名大小写不对、中文空格导致不同平台失效。建议统一用正斜杠比如./images/demo.png不要用 Windows 的反斜杠.\images\demo.png。文件命名用短横线或下划线避免空格和中文。如果想把剪贴板截图直接粘贴进 Markdown建议安装图片粘贴类扩展。这类扩展会读取剪贴板图片保存到指定目录再自动插入相对路径。这里有一个关键配置必须把图片保存目录固定好否则图片会散落到项目根目录。我一般会建一个docs/images目录并在项目.vscode/settings.json里把扩展的默认图片目录指向它。图片路径一旦固定后续转 Word、转 PDF、部署博客都会省很多时间。3.4 链接和页内锚点Markdown 链接可以分为外部链接和站内链接。[官网](https://example.com) [查看安装文档](./install.md) [跳转到标题](#安装步骤)外部链接比较好处理。站内链接要特别注意相对路径链接是相对于当前 Markdown 文件所在目录不是相对于项目根目录。如果install.md在docs目录下当前readme.md在根目录那么链接应该写成docs/install.md。页内锚点在 VS Code 的 GitHub 风格解析里通常可以使用但不同平台对中文标题的锚点处理方式不一样。文档发布到 GitHub、博客、内部系统后锚点可能失效。最稳妥的做法是尽量用英文标题或者少用页内跳转改用目录大纲。VS Code 新版本里写链接时编辑器会补全文件路径鼠标悬停链接也能看到预览地址。这个能力很实用建议在写长文档时多利用路径补全而不是手打路径。3.5 代码块语言标记和注释快捷键Markdown 里的代码块用三个反引号包裹。反引号后面写语言标识编辑器就会按对应语言高亮。print(hello)std::cout hello std::endl;语言标记写错或者不写高亮会失效但不会影响渲染。这个问题很常见很多人以为是编辑器坏了其实只是语言标识拼写不对。如果你在 Markdown 里写大段代码折叠功能比翻页更好用。代码块也可以折叠只要把鼠标移到代码块左侧装订线。关于注释快捷键Ctrl/可以切换单行注释ShiftAltA可以切换块注释。这是 VS Code 的通用编辑能力不仅限 Markdown。因为 Markdown 里的代码块本质上是普通文本VS Code 能否正确识别注释取决于光标是否落在代码块内以及语言标识是否正确。3.6 数学公式和特殊字符当前版本的 VS Code 预览已经能渲染常见数学公式写法是行内公式 $a^2 b^2 c^2$ 独立公式 $$ \int_0^1 x^2 dx $$这个能力在本地预览里很好用但发布到博客或文档平台时不一定会被解析。很多平台默认关闭数学公式渲染需要额外开启插件或配置。所以不要以本地预览作为唯一标准。特殊字符方面普通角度符号、小于号、大于号在 Markdown 正文里没有太大问题但在 HTML 标签里会被当作标签处理。如果要在文档里展示div这类标签请放进代码块不要直接写在正文。4. 安装扩展前先想清楚不然后面全是坑4.1 最小组合Markdown All in One 加 markdownlint我不建议一次装十几个 Markdown 扩展。刚上手时先装两个就够了。第一个是 Markdown All in One。它解决的是日常写作效率问题。常用能力包括生成和更新目录。格式化表格。列表缩进控制。选择文本后一键加粗、斜体。把选中文本包成链接。第二个是 markdownlint。它像编码规范检查器一样会在“问题”面板里提示 Markdown 格式问题比如标题前面没有空行、列表符号不一致、代码块语言缺失。很多格式化问题其实它都能自动修复。运行“快速修复”或“修复所有问题”就能清理一批格式错误。这两个扩展覆盖了写作和规范检查先跑通这两项再考虑其他。4.2 图片粘贴类扩展需要先配置再使用图片粘贴扩展解决的问题很现实从剪贴板截图直接粘贴到 Markdown扩展自动保存图片并插入路径。但这类扩展如果配置不好会带来新的混乱。最常见的情况是图片保存到项目根目录几十张图堆在一起文件管理直接崩溃。我建议先建好固定目录再修改工作区设置。比如在.vscode/settings.json里配置图片保存路径确保所有截图进入docs/images。发布文档时图片目录跟着文档一起拷贝相对路径才不会失效。粘贴的图片最好补上替代文本。图片扩展自动插入的语法通常只有没有描述文字。这时 markdownlint 可能会给提示不要嫌麻烦补一句图片内容说明对无障碍阅读和搜索引擎都更友好。4.3 导出和转换Markdown 到 HTML、Word、PDFMarkdown 写得再漂亮最终也可能需要输出成 Word 或 PDF。常见路径有三条用 VS Code 导出类扩展右键文档直接导出 PDF 或 HTML。适合单文件、少量转换。用 Pandoc 这类命令行工具适合批量转换和格式稳定输出。用在线转换工具适合临时用不适合批量。我一般用 Pandoc 做本地转换至少保证图片相对路径和编码问题可控。给一个最简示例pandoc docs/readme.md -o docs/readme.docx如果你需要把一堆 Markdown 文件批量转成 Word可以写一个循环脚本逐个处理目录下的.md文件。这里真正要解决的往往不是转换命令本身而是文档内的图片路径和命名规则。先把源文件结构理好转换过程才会顺畅。4.4 注意扩展之间的规则冲突Markdown 相关扩展多了之后经常出现相互干扰。典型的例子A 扩展要求在标题后空一行B 扩展会强制删掉空行。两个扩展都启用文件保存时就可能反复横跳。定位这类问题不是去改文档而是先确认是哪个扩展在起作用。排查方式很简单把可能冲突的扩展逐个禁用再运行格式化或检查问题面板。启用扩展尽量按工作区隔离不要所有项目都全局加载。比如 PDF 导出扩展只在写书的项目里启用markdownlint 在短笔记项目里可以禁用。5. 预览空白、表格乱、目录不显示按这个顺序排查5.1 预览空白或打不开如果 Markdown 预览不渲染不要一上来就重装 VS Code按这个顺序排查确认当前文件语言模式是 Markdown。检查工作区信任状态。VS Code 遇到不信任的文件夹部分预览和任务脚本可能被限制。禁用所有扩展后再打开预览。新建一个空test.md录入最简单的一行标题再打开预览。查看“开发人员工具”里的错误日志确认是不是扩展报错。大多数预览空白并不是 Markdown 解析失败而是扩展冲突或缓存问题。禁用扩展后能立刻定位。5.2 表格贴进来全乱了表格乱的关键原因是“数据来源格式”和“Markdown 格式”不一致。从 Excel 复制过来的内容粘贴进 VS Code 后通常带制表符而不是竖线。从网页复制的内容可能直接带 HTML 标签。先粘贴为纯文本再统一转换比手工修要快。如果是在表格内部多复制了一行渲染结果可能多出空行。检查每个表格行的竖线数量是否一致。Markdown 表格解析对行列数很敏感。还要记住表格格式在不同平台兼容性一般。VS Code 预览正常的表格粘贴到某些笔记软件里可能显示成纯文本。最终发布到哪个平台就要在那个平台上复核。5.3 目录不显示先分清是“左侧大纲不显示”还是“文档内 TOC 不显示”。左侧大纲不显示大概率是标题写法问题。比如## 标题 #标题最后的#会被当作文本标题前有不必要的缩进或者标题用了巨大的加粗文字而不是#。把标题改成标准 Markdown 标题语法大纲立刻就会识别。文档内 TOC 不显示大概率是生成 TOC 后改变了标题结构。很多 TOC 扩展需要手动重新运行“更新目录”。写完文档后改标题是一种常态所以每次调整完标题记得重新生成目录。5.4 图片显示不出来图片失效时我会按这个顺序检查图片文件是否真的存在。文件名大小写是否一致。相对路径是否以当前 Markdown 文件所在目录为基准。路径里是否用了反斜杠。文件名是否包含空格或中文。当前环境有没有权限访问本地或网络图片。最直接的验证方式是把图片路径复制到浏览器地址栏里打开。如果浏览器能打开说明文件没问题问题出在 Markdown 路径写法或预览环境。发布到博客后图片失效一般就要去检查远程存储路径和防盗链而不是继续在 VS Code 里改。5.5 输入的 # 消失或标题变成纯文本有人遇到过这种情况写完标题后发现#不见了或者标题变成了普通文本。原因通常是这几类误触了“减少标题级别”或“切换代码块”相关命令。输入法在中文状态下把#吞掉或转换成全角符号。文件语言模式被切回了纯文本。某些扩展自动折叠了标题看起来像消失实际还在。处理时先按CtrlZ撤销再检查语言模式。不要急着重新打字否则原来的标题层级会乱。如果是输入法问题切换到英文输入法再输入#。5.6 不同平台打开同一个 Markdown 后格式不一致这是最容易被忽略的问题。VS Code 预览只是参考不是真相。GitHub 的渲染规则、博客平台的渲染规则、笔记软件的渲染规则彼此之间都有差异。我写文档时会遵循两个原则一是基础语法尽量标准化用最常见的标题、列表、表格、代码块二是平台特有语法尽量少。比如某些平台的注释语法、自定义容器、提示块在另一个平台可能直接显示成原始文本。发布前一定要在目标平台预览一遍。这不是麻烦这是 Markdown 工作流的最后一环。6. 把 Markdown 写进开发文档和发布流程6.1 先规划好项目文档结构文档不是越多越好而是越清晰越好。一个比较常见的结构是docs/ README.md images/ architecture.png guides/ install.md deploy.md图片集中放在images目录文档按用途分目录。命名用短横线不要用大写开头加空格因为大小写问题在 Linux 和线上环境里很容易出问题。Markdown 文档进入 Git 管理后每次修改都能用 diff 看到变化。这是 Markdown 相比 Word 最大的优势之一。写错一个命令回滚和评审都更清楚。6.2 文档里的示例命令和代码也要验证技术文档里如果写了安装命令、启动命令建议真的在项目环境里跑一遍。否则用户复制完命令仍然是坏的文档信任度会快速下降。我一般会把文档中出现的命令整理成独立脚本放在scripts/目录里。脚本可以测试文档引用脚本输出示例。代码块里也要写清楚运行前提比如需要 Python 版本、需要 Node 版本。不要只丢一行命令就结束。6.3 用 lint 在提交前拦下格式问题Markdown 格式问题如果靠人眼检查效率很低。可以在 CI 或 pre-commit 阶段加入 Markdown lint 检查。比如在使用 npm 的项目里npx markdownlint-cli docs/**/*.md这条命令会检查docs目录下所有 Markdown 文件的格式规范。如果发现错误构建或提交会中断提示先修复。配置规则可以按团队习惯调整不一定全按默认规则。加入 lint 的意义是“让机器替人检查基础格式”这样文档评审时可以把精力放在内容上。6.4 Markdown 转 HTML、Word、PDF 的自动化思路如果只是临时转一个文件手工用扩展或 Pandoc 就够。如果需要反复转换可以固定一条脚本链路。最基本的流程是写 Markdown 源文件。用脚本批量处理图片路径。用 Pandoc 转成目标格式。检查输出目录。示例pandoc README.md -o README.html pandoc README.md -o README.docx自动化链路里要提前定好输出目录避免和源文件混在一起。还要注意Pandoc 对部分扩展语法支持有限比如某些主题里的自定义容器。转换前先用一个小文件验证不要等到终极版本才发现格式坏了。很多前端项目也内置了 Markdown 解析能力比如把 Markdown 文件在构建阶段渲染成页面。这时候要额外注意预览正常不代表构建后的页面正常。构建产出的 HTML 要实际部署看一次。6.5 长期维护文档的几条经验最后留几条自己长期使用的判断标准。单文档控制在合理长度。README 超过一定规模后拆分到docs子目录比堆在一个文件里更好维护。图片目录固定之后不要随便迁移迁移必须同步修改所有引用。每次改完标题重新生成目录。每个 Markdown 文件开头先写清楚“这个文档解决什么问题”比写一大段背景有用。格式化工具和 lint 规则定了就尽量统一执行不要手工逐行调整。如果你只是第一次用 VS Code 写 Markdown我的建议是先把内置预览和大纲用熟再去装扩展。装完扩展后不要一次全开按用途做减法。这样下来你用 VS Code 维护文档的时间会明显少于开一个云文档反复调整排版的成本。