如果你正在纠结用什么工具写技术文档我的答案基本都是同一句话打开 Visual Studio Code装上几个顺手的 Markdown 插件这套组合拳能覆盖日常八成以上的写作需求。别误会我不是要给编辑器排名只是这两年做项目文档、写技术博客、维护团队知识库踩过不少工具切换的坑之后确实觉得 VS Code 加 Markdown 是性价比最高的选择。它免费、轻量、跨平台对 Markdown 有原生支持插件生态又足够丰富从随手记笔记到带数学公式、流程图和自动目录的正式文档都能在一个窗口里完成。这篇文章不打算给你讲那些玄乎的概念只讲从安装配置、插件选择、再到最后导出 PDF 和 Word 的完整链路。无论你是刚开始接触 VS Code 的新手还是已经在用但觉得流程不够顺的老手应该都能从里面找到一点能直接上手的东西。1. 第一次装 VS Code下载、选项和中文化1.1 下载和安装时被我反复叮嘱的三个选项VS Code 的官网很好找打开就是大大的下载按钮。这里建议选择稳定版不要碰 Insider。Insider 是预览版功能更新快但偶尔会和插件不兼容等你装完一堆插件后出了问题排查起来非常头疼。稳定版虽然“保守”但日常写作完全够用。安装时 Windows 用户容易被一堆勾选框带跑。我的建议是至少勾上这三项将“Code”添加到 PATH、将“Code”添加到“打开方式”列表、将“Code”注册为受支持文件的编辑器。尤其是第一项添加 PATH 后可以在任意终端里直接敲code .打开当前目录这个动作在后续配合 Git、命令行工具时会非常高频。很多朋友一开始嫌麻烦不勾后来想用命令行打开项目又总报“code 不是内部或外部命令”只能回去重装。所以这一步别跳过。macOS 上把下载的应用拖到 Applications 即可Linux 用户根据发行版选择官方 .deb 或 .rpm 包安装过程基本没有坑。装完之后顺手在命令面板CtrlShiftP里跑一下Shell Command: Install code command in PATH这样终端里那条code .一样能用。安装这一步看起来简单但很多人后面遇到大量“文件打不开”“右键没有 VS Code 选项”的问题核心都出在安装时漏了环境关联。1.2 中文界面设置装完立刻要做的一件事安装完成后第一次打开 VS Code 是全英文界面。用是可以用的但对刚上手的朋友会平添很多心理负担。我推荐直接安装官方中文语言包左侧扩展图标CtrlShiftX搜索“Chinese”找到中文简体语言包点击 Install然后按提示重启 VS Code。重启后如果界面还是英文大概率是语言配置没生效。可以按 CtrlShiftP 打开命令面板输入Configure Display Language从列表里选择 zh-cn。这条命令本质上是改写locale.json文件里的语言标记比手动翻设置快得多。要注意一点语言包只是把界面翻译成中文不会影响 Markdown 内容的渲染效果所以不用有任何顾虑。还有一个小技巧我在团队内部培训时会让新人先打开设置面板Ctrl,搜索“auto save”把自动保存改成afterDelay延迟设成 1000ms。再顺手把files.encoding确认成utf8。这样写文档时不用反复 CtrlS中文乱码问题也基本能避免。基础配置不用一次调完但自动保存和编码这两项越早改越省心。1.3 几个值得提前调整的编辑体验参数除了自动保存编辑体验上还有三个参数我每次在新环境都会设置字体大小、自动换行、缩进线。editor.fontSize默认一般是 14嫌小可以改成 16眼睛轻松很多。editor.wordWrap改成on让长段落自动换行。写 Markdown 时这一段尤其重要否则一个很长的句子会无限向右延伸。editor.renderWhitespace可以选all让空格和制表符显形。Markdown 的换行有时依赖两个空格如果看不见空格容易排查不到问题。这些设置写在 settings.json 里即可。你也可以直接在设置界面搜索对应项去改效果一样。顺带说一句VS Code 的设置分为 User 和 Workspace 两层如果你不想把个人偏好带进团队项目团队类的格式化规则建议放在 Workspace 设置里避免污染全局环境。这个分层思路在写团队协作文档时特别有用。2. Markdown 编辑与实时预览先把写作流跑起来2.1 Markdown 对文档工作流的价值恰恰在“不折腾”很多人第一次接触 Markdown 会问这和 Word 有什么区别我的理解是Markdown 的目的是把内容结构和排版样式分离开来。你写文档时只需要关心“这里是一级标题”“这是列表”“这是代码块”至于渲染成什么样子交给编辑器或转换工具去处理。这样写出来的源文件是纯文本体积小任何编辑器都能打开也方便用 Git 做版本管理。VS Code 对 Markdown 的支持属于“开箱即用”新建一个.md文件语法高亮和基础预览马上就能用。但内置能力只覆盖标准语法像数学公式、流程图、更强大的导出功能都需要插件扩展。这也是我为什么一直强调“VS Code Markdown 插件”三者要放在一起说。单独用 VS Code 缺了插件体验能少一半只有装了插件整套工作流才完整。2.2 创建 Markdown 文件和打开预览的三种姿势第一个操作是新建文件。在 VS Code 里按 CtrlN 新建文件右下角语言模式默认可能是纯文本。这时按 CtrlK M或者点击右下角语言模式选择 Markdown语法高亮就出来了。更常见的做法是直接保存成xxx.mdVS Code 会自动识别。预览有几种方式直接按 CtrlShiftV当前编辑器标签页会切到预览模式。按 CtrlK再按 V会在右侧打开一个分屏预览左侧写、右侧看这是我日常用的最多的方式。打开右上角的“打开预览到侧边”图标效果和分屏预览一样。分屏预览最实用因为你能实时看到格式变化。光标在左侧文档和右侧预览之间会相互定位快速跳转非常方便。这里有一个我强调很多次的点Markdown 不是纯粹的“所见即所得”但 VS Code 的实时预览让差距缩小了很多。写完一行马上能看到效果不需要手动渲染这就是写作流能顺畅跑起来的关键。2.3 换行和表格新手最容易翻车的两个坑我见过太多人一开始写 Markdown换行不生效。原因很简单Markdown 的普通换行在标准语法里不会被认为是段落换行必须在前一行末尾敲两个空格或者用一个空行来分隔。VS Code 原生预览和部分插件预览可以改设置忽略这个规则比如在 settings.json 里设置markdown.preview.breaks: true但导出 PDF 或 Word 的时候格式标准又会变。保险的做法是老老实实按标准语法写否则文档换个环境渲染段落就挤成一团了。表格是另一个高发区。Markdown 表格的基本格式是第一行写表头中间用管道符分隔第二行写对齐标记后面是数据行。例如项目说明名称VS Code类型编辑器这种写法本身不难但手敲管道符和冒号容易歪列多了尤其痛苦。我一般会先随便写两行然后用 Markdown All in One 的“格式化表格”功能一键对齐。这个细节到下一章讲插件时会再展开。3. Markdown 插件怎么选我用下来最有用的几款3.1 Markdown All in One格式化、目录、列表缩进一步到位Markdown All in One 可以说是 Markdown 写作类插件的“头号种子”。它的主要功能有三个自动格式化表格、快速生成目录、优化列表操作。安装后在任意.md文件里按 CtrlShiftP输入Markdown: 格式化文档表格会被自动排齐缩进错乱也会被修正。写文档前先随手格式化一下比手动对齐省力太多。目录功能也很常用。在文档开头想插入目录时把光标放到对应位置打开命令面板执行Markdown: 创建目录插件会生成一个基于标题结构的 TOC。标题改动后可以再次执行更新目录。注意它默认用!-- /TOC --标记目录块的边界平时写正文千万别把这段注释删掉否则后续更新目录会失效。列表操作方面它支持在列表项内按 Tab 缩进、ShiftTab 降级回车会自动延续列表项序号。对于经常写技术文档、习惯用大量嵌套列表的人来说这个体验几乎不可替代。加粗和斜体的快捷键它也有比如选中文字后按 CtrlB 就会自动包上两个星号这对中文输入法切换频繁的作者非常友好。3.2 Markdown Preview Enhanced把预览能力拉满如果只允许我装一个 Markdown 预览增强插件我选 Markdown Preview Enhanced简称 MPE。它支持上下滚动同步、自定义 CSS、数学公式渲染、Mermaid 流程图以及一键导出 HTML/PDF 等功能。很多人的 Markdown 体验从“能用”变成“好用”转折点就是装了它。安装 MPE 后原来的预览快捷键依然有效但内容渲染由 MPE 接管。它内置了 KaTeX/MathJax 的数学公式支持写在$...$和$$...$$里的公式都能正常显示Mermaid 图表也支持只要在代码块中指定 mermaid 语言预览区就会自动渲染成图。对写技术方案、算法笔记、项目架构说明的人来说这项能力几乎必装。MPE 的自定义 CSS 功能也值得一提。你可以在插件设置里指定一个 CSS 文件统一调整预览页面的字体、间距、标题颜色。我一般会准备一份简单的 site.css固定用中文字体、行高 1.8、标题颜色统一这样导出的 HTML 也能保持同样的观感。CSS 配置属于加分项刚入门的朋友可以先跳过等预览和导出样式不一致的问题出现时再回头配置。3.3 图片粘贴与路径管理Paste Image 解决截图痛点写文档避不开插图。最痛的操作方式是“截图-保存文件-回到编辑器-输入图片语法-修改路径”这一连串动作太割裂。Paste Image 插件能把截图直接粘贴到 Markdown 文档中并且自动保存为图片文件。安装后按 CtrlAltV剪贴板里的截图会以默认格式通常是 PNG保存到指定目录同时在光标处插入类似的语法。你可以在插件设置里配置保存目录和文件名规则。我最常用的配置是把图片统一存到当前文档所在目录下的assets文件夹文件名用时间戳防止重名pasteImage.path: ${currentFileDir}/assets, pasteImage.namePrefix: ${currentFileNameWithoutExt}_, pasteImage.insertPattern: 路径问题集中在三处一是用了绝对路径换个文件夹就失效二是文件名带中文或空格导出时容易出幺蛾子三是图片文件根本没和.md文件放在一起。我的建议很简单统一用相对路径图片放assets目录文件名用英文字母加数字。这一条建议能避开 90% 的图片不显示问题。3.4 其他顺手插件和插件安装的兜底方案除了上述三款还有几个“看场景装”的插件Markdown TOC 的老版本用户可以直接被 Markdown All in One 替代Code Spell Checker 可以在写英文技术文档时避免低级拼写错误GitLens 对用 Git 管理文档的人很有用但它和 Markdown 本身关系不大锦上添花而已。插件的安装渠道主要依赖左侧扩展市场。正常联网环境搜索名字、点击安装即可。如果遇到公司内网限制或者插件市场搜索不到可以去 VS Code 插件市场官网下载对应版本的.vsix文件然后在编辑器里执行从 VSIX 安装...或者用命令行code --install-extension /path/to/plugin.vsix这个方式是官方支持的离线安装手段也是我在受限环境下的兜底方案。需要提醒的是下载 VSIX 时一定留意版本和来源尽量选择官方市场页面提供的下载别在来历不明的第三方站点随便点安装包。4. 交付环节PDF、Word 和 Excel 的格式转换路线4.1 导出 PDF 时PrinceXML 和 Chrome 两条路线怎么选很多人在 VS Code 里写完 Markdown第一个需求就是导出 PDF。MPE 提供的导出方式里最常用的是“PDF (via Chrome)”和“PDF (via Prince)”。具体操作是在预览页面右键选择“Export”再选对应格式。如果你用 Chrome 方案MPE 会调用本机的 Chrome/Chromium 把预览渲染成 PDF基本不需要额外配置只要电脑上装了 Chrome 即可。这个方案我在 Windows 和 macOS 上都测试过中文显示正常格式还原度高适合大多数场景。PrinceXML 则是另一套渲染引擎适合对排版精细度要求更高的场景。如果你在导出时选择 PDF (Prince)编辑器可能会提示找不到 prince 可执行文件。这时你需要去 Prince 官网下载对应系统版本并安装。Windows 安装时一般会自动加入 PATHmacOS 和 Linux 可能需要手动把安装路径写进环境变量。装好后重启 VS Code再回到 MPE 里导出就能识别了。我个人的经验是日常导出用 Chrome需要批量或更精细排版的场景再用 Prince。不要一上来就去折腾 PrinceXML能解决当前问题的工具就是好工具。若你已经装了还是提示找不到可以在 MPE 的设置项中手动指定 Prince 的路径路径千万别带空格或中文。4.2 Markdown 转 WordPandoc 是开源圈子的标准答案有些团队交付文档要求 .docx 格式这时候 Pandoc 就派上用场了。Pandoc 是一个开源文档格式转换工具可以把 Markdown、HTML、LaTeX、docx、epub 等几十种格式互相转换命令非常简单pandoc input.md -o output.docx安装好 Pandoc 后在终端里执行这条命令就能得到一个 Word 文档。转换后标题、列表、代码块这些结构基本能保留但复杂表格和图片位置可能需要手工微调。这也是文档格式转换的常态自动转换负责把内容搬过去排版细节还得人过一遍。如果你不想装 Pandoc也有一个折中流程先用 MPE 把 Markdown 导出成 HTML再用 Word 打开 HTML 文件另存为 docx。优点是顺手缺点是样式经常乱尤其是表格和代码高亮需要花时间重新整理。我在给客户交付正式文档时还是用 Pandoc 居多毕竟它能写进自动化脚本改一个文件名就能批量转换非常适合维护多文档的项目。顺带一提很多人搜索“任意格式转换为 Markdown 开源项目”最后找到的也是 Pandoc。它能把 docx、epub、HTML 甚至部分 PDF 转成 Markdown虽然转换结果不一定完美但在大部分开源方案里它确实是覆盖格式最广的那一个。如果你有批量整理文档的需求Pandoc 值得花半小时研究。4.3 表格复制到 Excel直接粘贴乱掉要先“分列”Excel 用户经常会碰到这样的场景从 Markdown 预览里复制了一个表格粘贴到 Excel 后所有内容挤在同一列。原因很简单Markdown 表格的单元格是用管道符|连接的Excel 默认不会把它当分隔符。正确的做法是先把表格内容复制到一个空白单元格然后选中这一列在 Excel 菜单栏选择“数据 → 分列”分隔符选“其他”输入|再完成分列。这样表头和数据就能自动拆开。如果表格带有管道符前后的空格可以在分列时顺便勾上“连续分隔符号视为单个处理”或者先统一把空格替换掉结果会更干净。反向操作从 Excel 表格转成 Markdown 格式我通常的做法是安装一个叫 “Excel to Markdown table” 的插件选中区域后直接复制就会得到 Markdown 表格语法。不方便装插件时也可以在 Excel 里把内容以制表符或管道符导出成 CSV再用脚本处理。关于在线工具我不是太推荐除非你处理的是无敏感性的公开数据否则内部数据不要随随便便贴到网页上。5. Markdown 语法速查照着写就不会出错5.1 基础文本样式标题、强调、列表、引用很多人以为 Markdown 语法很多其实日常写作高频用到的不到二十种。标题用井号加粗用两个星号斜体用一个星号无序列表用减号或星号有序列表用“数字加点”引用用大于号。# 一级标题 ## 二级标题 **加粗** *斜体* - 无序列表项 1. 第一个有序项 引用内容这些基础语法在不同编辑器里的渲染基本一致属于“记下就不会错”的东西。注意#后面要加空格-后面也要加空格否则会被当成普通文本。语法高亮里如果标题没变色通常就是空格少了。5.2 链接、图片、代码块注意括号和路径细节链接和图片的写法很像区别是图片开头多一个感叹号[VS Code 官网](https://code.visualstudio.com/) 图片路径是重灾区。用相对路径时./表示当前目录../表示上一级目录。如果你的.md文件在docs目录图片在docs/assets那路径写./assets/xxx.png就对了如果放在项目根目录的images下则要写../images/xxx.png。判断基准就是“以当前 Markdown 文件所在的目录为起点”。这个规则理解了比背一百条路径规则都管用。代码块用三个反引号包裹后面可以标注语言python print(hello)很多文档系统会根据这个语言标注做代码高亮不写语言也能渲染但写上是习惯问题。行内代码用单个反引号比如 npm install 适合在正文中强调命令或变量名。 ### 5.3 数学公式、任务列表和扩展语法 标准 Markdown 本身不支持数学公式但 MPE 这类插件在预览阶段内置了支持。行内公式用单美元符括起来比如 $x^2 y^2 z^2$独立公式用两个美元符写在单独的一行。 任务列表是 GitHub Flavored Markdown 里很实用的一种语法 markdown - [x] 已完成安装 - [ ] 配置插件方括号里的 x 表示已完成在 VS Code 里可以直接点击勾选团队流程类文档用起来很方便。MPE 还支持 Mermaid 流程图和时序图这也是很多人选择 VS Code 写技术方案的关键原因。你只要在代码块中指定mermaid语言预览区就会自动渲染成图表不用再单独开画图软件。语法速查不一定非要把所有规则背下来。我的建议是把最常用的标题、列表、加粗、链接、图片、代码块这六类记牢其他语法用的时候查一下就行。写文档的流畅度来自思路顺畅而不是把所有语法都塞进脑子里。6. 踩坑实录我在 VS Code 里用 Markdown 遇到的那些问题6.1 图片显示不出来先按顺序排查这四步图片问题在 Markdown 写作中出现的频率最高而且每次原因都类似。我总结了一个四步排查顺序先确认图片文件是否真的存在于路径对应位置。最直接的办法是在文件资源管理器里打开路径看文件名是否一致。很多“明明路径对却显示不出来”的案例最后都发现是文件名大小写写错了。检查路径分隔符。Windows 的路径一般是反斜杠但 Markdown 图片语法里推荐用正斜杠/用反斜杠容易在部分渲染器里出问题。检查文件名是否包含空格或中文。空格可以改成下划线中文路径虽然 VS Code 能显示但导出 PDF 时可能变成%20或乱码尽早规避。检查是不是用了绝对路径。绝对路径在本地能用换一台电脑或换一个目录就失效。我自己的项目里全部统一为相对路径并且图片集中放在assets目录下。上次一个同事的文档怎么都显示不出图最后发现他把图片放在了桌面上而.md文件在项目目录里路径自然就错了。新建项目时顺手在根目录建一个assets文件夹这个习惯能省去很多后面找图的时间。6.2 预览和导出样式不一致从“能用”到“统一”的方法很多朋友会遇到一个现象在 VS Code 里预览很漂亮一旦导出 PDF字体、间距就和预览完全不同。原因很简单预览时用的是编辑器或插件的默认样式导出时用的是目标渲染引擎内置样式。这两个样式没有强制同步自然会出现偏差。想统一最简单的办法是为 Markdown Preview Enhanced 设置自定义 CSS。在 MPE 的预览页面右键选择“Open Preview Settings”或在用户设置里找到markdown-preview-enhanced.customCss指定一个 CSS 文件路径。CSS 里可以定义正文行高、字体、标题颜色等。这样每次预览时都套用这套风格再基于预览页面导出 PDF结果就会稳定很多。另一个经验是先确认你导出的目标是哪种引擎再按引擎调整。比如 Prince 的排版精度比 Chrome 高但中文字体需要额外配置Chrome 导出则相对省心适合日常交付。样式不一致不是一个“错误”而是工作流里最常见的细节提前用 CSS 把基调定下来能少很多最后一刻的调整。6.3 插件市场搜索不到或安装失败常见原因和处理思路插件装不上的问题我有几次在外地培训时也遇到过。最常见的有三种情况一是搜索时的关键词不对。VS Code 扩展搜索匹配的是扩展名称和描述想搜“Markdown 插件”直接搜“markdown”比搜中文靠谱二是因为当前 VS Code 版本过旧新版本插件兼容不了旧编辑器这种情况升级 VS Code 就好三是网络环境问题公司内网可能限制了对插件市场的访问。遇到环境限制我的建议是先检查一下当前网络是否能正常访问外部网站如果是因为企业策略导致访问不了应该向网络管理员咨询是否可放行。不要自己去用不明手段绕过这在企业合规上是给自己找麻烦。如果等不及审批就用官方市场页面下载 VSIX 文件通过“从 VSIX 安装”在本地安装。这个方法不依赖在线市场也能正常完成导入。要注意VSIX 文件一定要从官方渠道下载版本要和当前 VS Code 匹配。如果插件和 VS Code 版本跨度太大安装时会提示不兼容。遇到这样的情况优先升级 VS Code然后再装插件不要强行降低插件版本来适配旧编辑器——旧版本插件可能带有已知 bug反而浪费更多时间。最后补充一个小习惯我会在每次新建 Markdown 项目时顺手把项目模板建好包括 README.md、assets 目录、一份简短的写作规范。这样不管是我自己还是接手的人都能在同一个框架下写作。工具不负责帮你写好内容但它能把格式、路径、转换这些噪音尽量降到最低让你把注意力留给真正该思考的部分。希望这套 VS Code Markdown 的工作流也能帮你少踩几个坑。
VS Code + Markdown：从安装配置到插件选型与PDF导出全指南
如果你正在纠结用什么工具写技术文档我的答案基本都是同一句话打开 Visual Studio Code装上几个顺手的 Markdown 插件这套组合拳能覆盖日常八成以上的写作需求。别误会我不是要给编辑器排名只是这两年做项目文档、写技术博客、维护团队知识库踩过不少工具切换的坑之后确实觉得 VS Code 加 Markdown 是性价比最高的选择。它免费、轻量、跨平台对 Markdown 有原生支持插件生态又足够丰富从随手记笔记到带数学公式、流程图和自动目录的正式文档都能在一个窗口里完成。这篇文章不打算给你讲那些玄乎的概念只讲从安装配置、插件选择、再到最后导出 PDF 和 Word 的完整链路。无论你是刚开始接触 VS Code 的新手还是已经在用但觉得流程不够顺的老手应该都能从里面找到一点能直接上手的东西。1. 第一次装 VS Code下载、选项和中文化1.1 下载和安装时被我反复叮嘱的三个选项VS Code 的官网很好找打开就是大大的下载按钮。这里建议选择稳定版不要碰 Insider。Insider 是预览版功能更新快但偶尔会和插件不兼容等你装完一堆插件后出了问题排查起来非常头疼。稳定版虽然“保守”但日常写作完全够用。安装时 Windows 用户容易被一堆勾选框带跑。我的建议是至少勾上这三项将“Code”添加到 PATH、将“Code”添加到“打开方式”列表、将“Code”注册为受支持文件的编辑器。尤其是第一项添加 PATH 后可以在任意终端里直接敲code .打开当前目录这个动作在后续配合 Git、命令行工具时会非常高频。很多朋友一开始嫌麻烦不勾后来想用命令行打开项目又总报“code 不是内部或外部命令”只能回去重装。所以这一步别跳过。macOS 上把下载的应用拖到 Applications 即可Linux 用户根据发行版选择官方 .deb 或 .rpm 包安装过程基本没有坑。装完之后顺手在命令面板CtrlShiftP里跑一下Shell Command: Install code command in PATH这样终端里那条code .一样能用。安装这一步看起来简单但很多人后面遇到大量“文件打不开”“右键没有 VS Code 选项”的问题核心都出在安装时漏了环境关联。1.2 中文界面设置装完立刻要做的一件事安装完成后第一次打开 VS Code 是全英文界面。用是可以用的但对刚上手的朋友会平添很多心理负担。我推荐直接安装官方中文语言包左侧扩展图标CtrlShiftX搜索“Chinese”找到中文简体语言包点击 Install然后按提示重启 VS Code。重启后如果界面还是英文大概率是语言配置没生效。可以按 CtrlShiftP 打开命令面板输入Configure Display Language从列表里选择 zh-cn。这条命令本质上是改写locale.json文件里的语言标记比手动翻设置快得多。要注意一点语言包只是把界面翻译成中文不会影响 Markdown 内容的渲染效果所以不用有任何顾虑。还有一个小技巧我在团队内部培训时会让新人先打开设置面板Ctrl,搜索“auto save”把自动保存改成afterDelay延迟设成 1000ms。再顺手把files.encoding确认成utf8。这样写文档时不用反复 CtrlS中文乱码问题也基本能避免。基础配置不用一次调完但自动保存和编码这两项越早改越省心。1.3 几个值得提前调整的编辑体验参数除了自动保存编辑体验上还有三个参数我每次在新环境都会设置字体大小、自动换行、缩进线。editor.fontSize默认一般是 14嫌小可以改成 16眼睛轻松很多。editor.wordWrap改成on让长段落自动换行。写 Markdown 时这一段尤其重要否则一个很长的句子会无限向右延伸。editor.renderWhitespace可以选all让空格和制表符显形。Markdown 的换行有时依赖两个空格如果看不见空格容易排查不到问题。这些设置写在 settings.json 里即可。你也可以直接在设置界面搜索对应项去改效果一样。顺带说一句VS Code 的设置分为 User 和 Workspace 两层如果你不想把个人偏好带进团队项目团队类的格式化规则建议放在 Workspace 设置里避免污染全局环境。这个分层思路在写团队协作文档时特别有用。2. Markdown 编辑与实时预览先把写作流跑起来2.1 Markdown 对文档工作流的价值恰恰在“不折腾”很多人第一次接触 Markdown 会问这和 Word 有什么区别我的理解是Markdown 的目的是把内容结构和排版样式分离开来。你写文档时只需要关心“这里是一级标题”“这是列表”“这是代码块”至于渲染成什么样子交给编辑器或转换工具去处理。这样写出来的源文件是纯文本体积小任何编辑器都能打开也方便用 Git 做版本管理。VS Code 对 Markdown 的支持属于“开箱即用”新建一个.md文件语法高亮和基础预览马上就能用。但内置能力只覆盖标准语法像数学公式、流程图、更强大的导出功能都需要插件扩展。这也是我为什么一直强调“VS Code Markdown 插件”三者要放在一起说。单独用 VS Code 缺了插件体验能少一半只有装了插件整套工作流才完整。2.2 创建 Markdown 文件和打开预览的三种姿势第一个操作是新建文件。在 VS Code 里按 CtrlN 新建文件右下角语言模式默认可能是纯文本。这时按 CtrlK M或者点击右下角语言模式选择 Markdown语法高亮就出来了。更常见的做法是直接保存成xxx.mdVS Code 会自动识别。预览有几种方式直接按 CtrlShiftV当前编辑器标签页会切到预览模式。按 CtrlK再按 V会在右侧打开一个分屏预览左侧写、右侧看这是我日常用的最多的方式。打开右上角的“打开预览到侧边”图标效果和分屏预览一样。分屏预览最实用因为你能实时看到格式变化。光标在左侧文档和右侧预览之间会相互定位快速跳转非常方便。这里有一个我强调很多次的点Markdown 不是纯粹的“所见即所得”但 VS Code 的实时预览让差距缩小了很多。写完一行马上能看到效果不需要手动渲染这就是写作流能顺畅跑起来的关键。2.3 换行和表格新手最容易翻车的两个坑我见过太多人一开始写 Markdown换行不生效。原因很简单Markdown 的普通换行在标准语法里不会被认为是段落换行必须在前一行末尾敲两个空格或者用一个空行来分隔。VS Code 原生预览和部分插件预览可以改设置忽略这个规则比如在 settings.json 里设置markdown.preview.breaks: true但导出 PDF 或 Word 的时候格式标准又会变。保险的做法是老老实实按标准语法写否则文档换个环境渲染段落就挤成一团了。表格是另一个高发区。Markdown 表格的基本格式是第一行写表头中间用管道符分隔第二行写对齐标记后面是数据行。例如项目说明名称VS Code类型编辑器这种写法本身不难但手敲管道符和冒号容易歪列多了尤其痛苦。我一般会先随便写两行然后用 Markdown All in One 的“格式化表格”功能一键对齐。这个细节到下一章讲插件时会再展开。3. Markdown 插件怎么选我用下来最有用的几款3.1 Markdown All in One格式化、目录、列表缩进一步到位Markdown All in One 可以说是 Markdown 写作类插件的“头号种子”。它的主要功能有三个自动格式化表格、快速生成目录、优化列表操作。安装后在任意.md文件里按 CtrlShiftP输入Markdown: 格式化文档表格会被自动排齐缩进错乱也会被修正。写文档前先随手格式化一下比手动对齐省力太多。目录功能也很常用。在文档开头想插入目录时把光标放到对应位置打开命令面板执行Markdown: 创建目录插件会生成一个基于标题结构的 TOC。标题改动后可以再次执行更新目录。注意它默认用!-- /TOC --标记目录块的边界平时写正文千万别把这段注释删掉否则后续更新目录会失效。列表操作方面它支持在列表项内按 Tab 缩进、ShiftTab 降级回车会自动延续列表项序号。对于经常写技术文档、习惯用大量嵌套列表的人来说这个体验几乎不可替代。加粗和斜体的快捷键它也有比如选中文字后按 CtrlB 就会自动包上两个星号这对中文输入法切换频繁的作者非常友好。3.2 Markdown Preview Enhanced把预览能力拉满如果只允许我装一个 Markdown 预览增强插件我选 Markdown Preview Enhanced简称 MPE。它支持上下滚动同步、自定义 CSS、数学公式渲染、Mermaid 流程图以及一键导出 HTML/PDF 等功能。很多人的 Markdown 体验从“能用”变成“好用”转折点就是装了它。安装 MPE 后原来的预览快捷键依然有效但内容渲染由 MPE 接管。它内置了 KaTeX/MathJax 的数学公式支持写在$...$和$$...$$里的公式都能正常显示Mermaid 图表也支持只要在代码块中指定 mermaid 语言预览区就会自动渲染成图。对写技术方案、算法笔记、项目架构说明的人来说这项能力几乎必装。MPE 的自定义 CSS 功能也值得一提。你可以在插件设置里指定一个 CSS 文件统一调整预览页面的字体、间距、标题颜色。我一般会准备一份简单的 site.css固定用中文字体、行高 1.8、标题颜色统一这样导出的 HTML 也能保持同样的观感。CSS 配置属于加分项刚入门的朋友可以先跳过等预览和导出样式不一致的问题出现时再回头配置。3.3 图片粘贴与路径管理Paste Image 解决截图痛点写文档避不开插图。最痛的操作方式是“截图-保存文件-回到编辑器-输入图片语法-修改路径”这一连串动作太割裂。Paste Image 插件能把截图直接粘贴到 Markdown 文档中并且自动保存为图片文件。安装后按 CtrlAltV剪贴板里的截图会以默认格式通常是 PNG保存到指定目录同时在光标处插入类似的语法。你可以在插件设置里配置保存目录和文件名规则。我最常用的配置是把图片统一存到当前文档所在目录下的assets文件夹文件名用时间戳防止重名pasteImage.path: ${currentFileDir}/assets, pasteImage.namePrefix: ${currentFileNameWithoutExt}_, pasteImage.insertPattern: 路径问题集中在三处一是用了绝对路径换个文件夹就失效二是文件名带中文或空格导出时容易出幺蛾子三是图片文件根本没和.md文件放在一起。我的建议很简单统一用相对路径图片放assets目录文件名用英文字母加数字。这一条建议能避开 90% 的图片不显示问题。3.4 其他顺手插件和插件安装的兜底方案除了上述三款还有几个“看场景装”的插件Markdown TOC 的老版本用户可以直接被 Markdown All in One 替代Code Spell Checker 可以在写英文技术文档时避免低级拼写错误GitLens 对用 Git 管理文档的人很有用但它和 Markdown 本身关系不大锦上添花而已。插件的安装渠道主要依赖左侧扩展市场。正常联网环境搜索名字、点击安装即可。如果遇到公司内网限制或者插件市场搜索不到可以去 VS Code 插件市场官网下载对应版本的.vsix文件然后在编辑器里执行从 VSIX 安装...或者用命令行code --install-extension /path/to/plugin.vsix这个方式是官方支持的离线安装手段也是我在受限环境下的兜底方案。需要提醒的是下载 VSIX 时一定留意版本和来源尽量选择官方市场页面提供的下载别在来历不明的第三方站点随便点安装包。4. 交付环节PDF、Word 和 Excel 的格式转换路线4.1 导出 PDF 时PrinceXML 和 Chrome 两条路线怎么选很多人在 VS Code 里写完 Markdown第一个需求就是导出 PDF。MPE 提供的导出方式里最常用的是“PDF (via Chrome)”和“PDF (via Prince)”。具体操作是在预览页面右键选择“Export”再选对应格式。如果你用 Chrome 方案MPE 会调用本机的 Chrome/Chromium 把预览渲染成 PDF基本不需要额外配置只要电脑上装了 Chrome 即可。这个方案我在 Windows 和 macOS 上都测试过中文显示正常格式还原度高适合大多数场景。PrinceXML 则是另一套渲染引擎适合对排版精细度要求更高的场景。如果你在导出时选择 PDF (Prince)编辑器可能会提示找不到 prince 可执行文件。这时你需要去 Prince 官网下载对应系统版本并安装。Windows 安装时一般会自动加入 PATHmacOS 和 Linux 可能需要手动把安装路径写进环境变量。装好后重启 VS Code再回到 MPE 里导出就能识别了。我个人的经验是日常导出用 Chrome需要批量或更精细排版的场景再用 Prince。不要一上来就去折腾 PrinceXML能解决当前问题的工具就是好工具。若你已经装了还是提示找不到可以在 MPE 的设置项中手动指定 Prince 的路径路径千万别带空格或中文。4.2 Markdown 转 WordPandoc 是开源圈子的标准答案有些团队交付文档要求 .docx 格式这时候 Pandoc 就派上用场了。Pandoc 是一个开源文档格式转换工具可以把 Markdown、HTML、LaTeX、docx、epub 等几十种格式互相转换命令非常简单pandoc input.md -o output.docx安装好 Pandoc 后在终端里执行这条命令就能得到一个 Word 文档。转换后标题、列表、代码块这些结构基本能保留但复杂表格和图片位置可能需要手工微调。这也是文档格式转换的常态自动转换负责把内容搬过去排版细节还得人过一遍。如果你不想装 Pandoc也有一个折中流程先用 MPE 把 Markdown 导出成 HTML再用 Word 打开 HTML 文件另存为 docx。优点是顺手缺点是样式经常乱尤其是表格和代码高亮需要花时间重新整理。我在给客户交付正式文档时还是用 Pandoc 居多毕竟它能写进自动化脚本改一个文件名就能批量转换非常适合维护多文档的项目。顺带一提很多人搜索“任意格式转换为 Markdown 开源项目”最后找到的也是 Pandoc。它能把 docx、epub、HTML 甚至部分 PDF 转成 Markdown虽然转换结果不一定完美但在大部分开源方案里它确实是覆盖格式最广的那一个。如果你有批量整理文档的需求Pandoc 值得花半小时研究。4.3 表格复制到 Excel直接粘贴乱掉要先“分列”Excel 用户经常会碰到这样的场景从 Markdown 预览里复制了一个表格粘贴到 Excel 后所有内容挤在同一列。原因很简单Markdown 表格的单元格是用管道符|连接的Excel 默认不会把它当分隔符。正确的做法是先把表格内容复制到一个空白单元格然后选中这一列在 Excel 菜单栏选择“数据 → 分列”分隔符选“其他”输入|再完成分列。这样表头和数据就能自动拆开。如果表格带有管道符前后的空格可以在分列时顺便勾上“连续分隔符号视为单个处理”或者先统一把空格替换掉结果会更干净。反向操作从 Excel 表格转成 Markdown 格式我通常的做法是安装一个叫 “Excel to Markdown table” 的插件选中区域后直接复制就会得到 Markdown 表格语法。不方便装插件时也可以在 Excel 里把内容以制表符或管道符导出成 CSV再用脚本处理。关于在线工具我不是太推荐除非你处理的是无敏感性的公开数据否则内部数据不要随随便便贴到网页上。5. Markdown 语法速查照着写就不会出错5.1 基础文本样式标题、强调、列表、引用很多人以为 Markdown 语法很多其实日常写作高频用到的不到二十种。标题用井号加粗用两个星号斜体用一个星号无序列表用减号或星号有序列表用“数字加点”引用用大于号。# 一级标题 ## 二级标题 **加粗** *斜体* - 无序列表项 1. 第一个有序项 引用内容这些基础语法在不同编辑器里的渲染基本一致属于“记下就不会错”的东西。注意#后面要加空格-后面也要加空格否则会被当成普通文本。语法高亮里如果标题没变色通常就是空格少了。5.2 链接、图片、代码块注意括号和路径细节链接和图片的写法很像区别是图片开头多一个感叹号[VS Code 官网](https://code.visualstudio.com/) 图片路径是重灾区。用相对路径时./表示当前目录../表示上一级目录。如果你的.md文件在docs目录图片在docs/assets那路径写./assets/xxx.png就对了如果放在项目根目录的images下则要写../images/xxx.png。判断基准就是“以当前 Markdown 文件所在的目录为起点”。这个规则理解了比背一百条路径规则都管用。代码块用三个反引号包裹后面可以标注语言python print(hello)很多文档系统会根据这个语言标注做代码高亮不写语言也能渲染但写上是习惯问题。行内代码用单个反引号比如 npm install 适合在正文中强调命令或变量名。 ### 5.3 数学公式、任务列表和扩展语法 标准 Markdown 本身不支持数学公式但 MPE 这类插件在预览阶段内置了支持。行内公式用单美元符括起来比如 $x^2 y^2 z^2$独立公式用两个美元符写在单独的一行。 任务列表是 GitHub Flavored Markdown 里很实用的一种语法 markdown - [x] 已完成安装 - [ ] 配置插件方括号里的 x 表示已完成在 VS Code 里可以直接点击勾选团队流程类文档用起来很方便。MPE 还支持 Mermaid 流程图和时序图这也是很多人选择 VS Code 写技术方案的关键原因。你只要在代码块中指定mermaid语言预览区就会自动渲染成图表不用再单独开画图软件。语法速查不一定非要把所有规则背下来。我的建议是把最常用的标题、列表、加粗、链接、图片、代码块这六类记牢其他语法用的时候查一下就行。写文档的流畅度来自思路顺畅而不是把所有语法都塞进脑子里。6. 踩坑实录我在 VS Code 里用 Markdown 遇到的那些问题6.1 图片显示不出来先按顺序排查这四步图片问题在 Markdown 写作中出现的频率最高而且每次原因都类似。我总结了一个四步排查顺序先确认图片文件是否真的存在于路径对应位置。最直接的办法是在文件资源管理器里打开路径看文件名是否一致。很多“明明路径对却显示不出来”的案例最后都发现是文件名大小写写错了。检查路径分隔符。Windows 的路径一般是反斜杠但 Markdown 图片语法里推荐用正斜杠/用反斜杠容易在部分渲染器里出问题。检查文件名是否包含空格或中文。空格可以改成下划线中文路径虽然 VS Code 能显示但导出 PDF 时可能变成%20或乱码尽早规避。检查是不是用了绝对路径。绝对路径在本地能用换一台电脑或换一个目录就失效。我自己的项目里全部统一为相对路径并且图片集中放在assets目录下。上次一个同事的文档怎么都显示不出图最后发现他把图片放在了桌面上而.md文件在项目目录里路径自然就错了。新建项目时顺手在根目录建一个assets文件夹这个习惯能省去很多后面找图的时间。6.2 预览和导出样式不一致从“能用”到“统一”的方法很多朋友会遇到一个现象在 VS Code 里预览很漂亮一旦导出 PDF字体、间距就和预览完全不同。原因很简单预览时用的是编辑器或插件的默认样式导出时用的是目标渲染引擎内置样式。这两个样式没有强制同步自然会出现偏差。想统一最简单的办法是为 Markdown Preview Enhanced 设置自定义 CSS。在 MPE 的预览页面右键选择“Open Preview Settings”或在用户设置里找到markdown-preview-enhanced.customCss指定一个 CSS 文件路径。CSS 里可以定义正文行高、字体、标题颜色等。这样每次预览时都套用这套风格再基于预览页面导出 PDF结果就会稳定很多。另一个经验是先确认你导出的目标是哪种引擎再按引擎调整。比如 Prince 的排版精度比 Chrome 高但中文字体需要额外配置Chrome 导出则相对省心适合日常交付。样式不一致不是一个“错误”而是工作流里最常见的细节提前用 CSS 把基调定下来能少很多最后一刻的调整。6.3 插件市场搜索不到或安装失败常见原因和处理思路插件装不上的问题我有几次在外地培训时也遇到过。最常见的有三种情况一是搜索时的关键词不对。VS Code 扩展搜索匹配的是扩展名称和描述想搜“Markdown 插件”直接搜“markdown”比搜中文靠谱二是因为当前 VS Code 版本过旧新版本插件兼容不了旧编辑器这种情况升级 VS Code 就好三是网络环境问题公司内网可能限制了对插件市场的访问。遇到环境限制我的建议是先检查一下当前网络是否能正常访问外部网站如果是因为企业策略导致访问不了应该向网络管理员咨询是否可放行。不要自己去用不明手段绕过这在企业合规上是给自己找麻烦。如果等不及审批就用官方市场页面下载 VSIX 文件通过“从 VSIX 安装”在本地安装。这个方法不依赖在线市场也能正常完成导入。要注意VSIX 文件一定要从官方渠道下载版本要和当前 VS Code 匹配。如果插件和 VS Code 版本跨度太大安装时会提示不兼容。遇到这样的情况优先升级 VS Code然后再装插件不要强行降低插件版本来适配旧编辑器——旧版本插件可能带有已知 bug反而浪费更多时间。最后补充一个小习惯我会在每次新建 Markdown 项目时顺手把项目模板建好包括 README.md、assets 目录、一份简短的写作规范。这样不管是我自己还是接手的人都能在同一个框架下写作。工具不负责帮你写好内容但它能把格式、路径、转换这些噪音尽量降到最低让你把注意力留给真正该思考的部分。希望这套 VS Code Markdown 的工作流也能帮你少踩几个坑。
