基于VS Code的Markdown写作工作流完整指南

之前写技术文档时总在几个 Markdown 编辑器之间来回切换有的在线编辑器样式好看但无法离线使用有的桌面端功能强大但预览效果一般有的插件丰富但配置复杂。直到我把 VS Code 当作主力 Markdown 编辑器使用后才发现原来“代码编辑器”也能把文档写作这件事做得这么顺手。本文就把这套基于 VS Code 的 Markdown 写作工作流完整拆解一遍内容涵盖环境配置、语法基础、插件搭配、导出方案和常见报错排查不管是刚接触 Markdown 的新手还是想搭建个人知识库的开发者都可以参考这套方案落地。1. 为什么选择 VS Code 作为 Markdown 编辑器1.1 VS Code 是什么VS CodeVisual Studio Code是微软推出的一款免费开源代码编辑器支持 Windows、macOS、Linux 三大平台。它的核心优势在于插件生态极其丰富通过安装不同扩展可以把它变成代码 IDE、文本编辑器、Markdown 写作工具、远程开发客户端等。从 Markdown 编辑的角度来看VS Code 自带以下能力内置 Markdown 预览面板编辑时实时渲染。支持 GitHub 风格的 Markdown 语法GFM。内置 Markdown 语法高亮和快捷命令。安装插件后支持导出 PDF、Word、HTML 等格式。所以“VS Code 是代码编辑器”这个印象没有错但它同时也是一款功能完整的 Markdown 编辑器。很多开发者写技术文档、项目 README、个人博客都是在 VS Code 里完成编辑和预览的。1.2 和专用 Markdown 编辑器的区别市面上常见的 Markdown 编辑器大致分两类在线编辑器如一些网页版 Markdown 工具优点是免安装、打开即用缺点是受网络影响、文件管理弱、隐私数据存在云端。桌面编辑器如 Typora、Mark Text 等专注 Markdown 写作体验实时渲染效果好但扩展能力相对有限。VS Code 属于“编辑器里的瑞士军刀”。它专不专“纯 Markdown 写作”说实话它的写作体验不一定比 Typora 那种“所见即所得”的风格更丝滑但 VS Code 真正的优势在于一个工具解决所有文字类工作写 Markdown、写代码、写配置文件、做 Git 提交、跑脚本全都在同一个窗口完成。Markdown 只是无数插件能力中的一种你随时可以扩展出图表、思维导图、Todo 列表、PDF 导出、代码块运行等功能。配置和笔记都是纯文本文件可以用 Git 做版本管理不依赖任何私有格式。1.3 适合哪些场景结合日常使用经验以下场景特别适合使用 VS Code 来写 Markdown技术文档编写API 文档、开发文档、接口说明、架构设计稿。项目 README 维护写清楚项目简介、安装步骤、使用方式。个人知识库管理配合 Obsidian 风格的笔记目录用 Markdown 存储所有笔记VS Code 负责编辑。博客写作先写 Markdown再导出为 HTML 发布。技术分享稿件写文章大纲、演讲稿用 Markdown 的列表和引用格式组织内容。2. 环境准备安装 VS Code 与基础配置2.1 下载与安装访问 VS Code 官网根据操作系统选择对应的安装包即可。Windows 环境下下载.exe安装包后一路 Next 完成安装。安装类型建议勾选“添加到 PATH”这样可以在终端中直接使用code命令打开项目和文件。安装完成后打开 VS Code按下快捷键Ctrl Shift PmacOS 为Cmd Shift P可以打开命令面板这是 VS Code 最常用的操作入口之一。2.2 打开终端工具如果习惯使用命令行可以安装后顺便确认一下code命令是否可用。Windows 下打开 PowerShell 或 CMD执行code --version如果提示找不到命令说明安装时没有勾选“添加到 PATH”可以重新安装或者在 VS Code 内使用快捷键 Ctrl 打开内置终端。2.3 基础设置进入设置页面Windows/LinuxCtrl ,macOSCmd ,推荐修改以下几项{ editor.fontSize: 16, editor.wordWrap: on, editor.minimap.enabled: false, files.autoSave: afterDelay, files.autoSaveDelay: 1000, markdown.preview.fontSize: 16, markdown.preview.lineHeight: 1.6 }这些配置的含义editor.fontSize编辑区字体大小写长文时 16px 比较舒适。editor.wordWrap自动换行避免长段落横向滚动。editor.minimap.enabled关闭右侧缩略图让编辑区更干净。files.autoSave延迟自动保存写完立即保存不用手动按Ctrl S。markdown.preview.*预览面板的字体和行高。2.4 安装必要插件在扩展面板快捷键Ctrl Shift X中搜索安装以下插件插件名称作用Markdown All in One提供自动补全、目录生成、列表缩进、快捷键等能力Markdown Preview Enhanced增强预览效果支持导出 PDF、HTML、Word支持图表Paste Image粘贴剪贴板图片并自动保存到本地路径markdownlintMarkdown 语法规范检查帮助写出更规范的文档Path Autocomplete自动补全文件路径写图片链接时很好用安装完成后重启 VS Code 或重新加载窗口即可生效。3. Markdown 核心语法与 VS Code 的对应能力3.1 Markdown 基础语法Markdown 是一种轻量级标记语言用简单的符号表达文档的格式。以下是高频使用的语法# 一级标题 ## 二级标题 ### 三级标题 **加粗文字** *斜体文字* ~~删除线文字~~ 引用内容 - 无序列表项 - 无序列表项 1. 有序列表项 2. 有序列表项 [链接文字](https://example.com)  行内代码 python print(代码块)列1列2单元格单元格这些语法在 VS Code 中都可以实时渲染。输入时可能觉得麻烦但熟练之后效率很高尤其是表格和代码块比传统 Word 排版方便得多。 ### 3.2 使用内置预览 编辑 Markdown 文件时按以下快捷键可以打开预览 - Ctrl Shift V在右侧打开预览面板。 - Ctrl K V在独立的编辑页中打开预览。 预览是实时刷新的左侧写右侧看非常适合一边写一边确认格式。 ### 3.3 GFM 扩展语法 VS Code 默认支持 GitHub 风格 MarkdownGFM主要包括 - 任务列表 markdown - [x] 已完成事项 - [ ] 待办事项删除线~~这是删除效果~~表格| 姓名 | 年龄 | | --- | --- | | 张三 | 20 |自动链接https://www.example.com这些功能在 GitHub、GitLab 等平台同样支持所以用 VS Code 写完文档直接推送到远程仓库渲染效果基本一致。3.4 常见误区提醒新手使用 Markdown 时容易遇到几个问题列表嵌套时忘记缩进导致层级混乱。表格的行列数不一致渲染时错位。代码块没有指定语言导致没有语法高亮。标题符号#后面没有加空格Markdown 不识别为标题。这些在 VS Code 的预览面板中都能直观看到问题。安装 markdownlint 插件后编辑器还会用波浪线提示格式问题非常方便。4. 完整实战用 VS Code 搭建 Markdown 写作工作流下面以一个“技术博客写作项目”为例从零搭建一个完整的 Markdown 写作环境。整个流程包括创建项目结构、安装插件、编写文档、插入图片、导出文件这几个环节。4.1 创建项目结构先在本地创建一个文件夹作为博客项目目录例如my-blog。然后在 VS Code 中打开该文件夹mkdir my-blog cd my-blog code .项目目录结构如下my-blog/ ├── docs/ │ └── article-1.md ├── images/ │ └── screenshot.png ├── .vscode/ │ ├── settings.json │ └── snippets/ └── README.md说明docs/存放 Markdown 文章。images/存放文章中用到的图片。.vscode/项目级配置目录把设置和代码片段放在这里团队成员同步后配置一致。4.2 配置 Markdown 插件Markdown All in One安装后在 Markdown 文件中可以享受以下能力输入#后按空格自动识别为标题。选中多行文字按Tab键整体缩进。输入[时会触发链接补全。右键菜单中可以直接生成目录Create Table of Contents。常用快捷键快捷键功能Ctrl B加粗Ctrl I斜体Ctrl Shift ]标题级别提升Ctrl Shift [标题级别降低Paste Image写文章时经常需要截图插入。Paste Image 插件支持剪贴板图片直接粘贴到 Markdown 中并自动保存到本地目录。使用方式截图复制到剪贴板。在 Markdown 文件中按Ctrl Alt V。选择图片保存路径插件会自动插入图片语法。建议先在项目设置中配置图片保存路径。在.vscode/settings.json中写入{ pasteImage.path: ${projectRoot}/images, pasteImage.basePath: ${projectRoot}, pasteImage.namePrefix: ${currentFileNameWithoutExt}_, pasteImage.insertPattern:  }这样每次粘贴图片时图片会自动保存到images/目录并生成对应的 Markdown 图片语法。4.3 编写一篇完整 Markdown 文档在docs/下新建一个文件article-1.md写入以下内容作为示例# 使用 VS Code 写 Markdown 的完整指南 ## 为什么选择 VS Code VS Code 是一款功能强大的编辑器它不仅仅适合写代码也非常适合写 Markdown 文档。下面是几个核心理由 - 内置 Markdown 预览编辑实时渲染 - 支持 GFM 语法与 GitHub 渲染效果一致 - 插件生态丰富可扩展出 PDF 导出、图片粘贴、语法检查等功能 ## 基础语法示例 ### 任务列表 - [x] 安装 VS Code - [ ] 安装 Markdown 插件 - [ ] 编写第一篇文档 ### 代码块 python print(Hello Markdown)表格功能是否支持预览支持导出 PDF支持图片粘贴支持小结VS Code 对于 Markdown 写作来说是一个可靠的选择通过简单的配置就能获得完整的写作体验。### 4.4 使用预览检查效果 按下 Ctrl K V 打开独立预览页面可以看到 Markdown 被实时渲染成带格式的文档。如果安装了 Markdown Preview Enhanced 插件预览效果会更丰富支持目录、数学公式、流程图等。 预览面板的右上角还有一个锁定按钮点击后可以固定预览内容便于一边滚动文档一边查看指定位置。 ### 4.5 导出 PDF 与 Word 写完后通常需要导出为 PDF 文件用于分享或归档。 #### 方案一Markdown Preview Enhanced 导出 PDF 在预览页面右键选择“Export to PDF”即可。插件会调用浏览器内核完成导出生成的 PDF 保留了 Markdown 渲染后的样式。 #### 方案二使用 Pandoc 导出 Word 和 PDF Pandoc 是一个通用的文档转换工具支持 Markdown 转 Word、PDF、HTML 等格式。安装 Pandoc 后在终端中执行 bash pandoc article-1.md -o article-1.docx导出 PDF 则需要 LaTeX 环境Windows 下比较复杂建议优先选择 Markdown Preview Enhanced 导出 PDF。方案三安装 Vditor 或 Markdown PDF 插件在扩展市场搜索Markdown PDF安装后可以直接在命令面板输入Markdown PDF: Export (pdf)即可将当前 Markdown 文件导出为 PDF 文件。这种方式配置最少适合快速导出。4.6 使用 Git 管理文档版本Markdown 是纯文本天然适合 Git 管理。在项目目录初始化仓库git init git add . git commit -m init: 创建 Markdown 博客项目以后每次修改文档都可以通过 Git 记录变更。写文档和写代码一样保存每一版历史需要的时候可以随时回退。5. 常见问题与排查思路在实际使用 VS Code 写 Markdown 的过程中会有一些高频问题。这里整理成表格方便遇到报错时快速定位。问题现象常见原因解决思路预览面板显示空白插件冲突或扩展未生效重新加载窗口禁用其他 Markdown 插件后逐个排查图片粘贴后不显示图片路径错误检查 Markdown 中图片路径确认Paste Image的basePath配置正确导出 PDF 时中文乱码系统中文字体或渲染引擎问题在 Markdown Preview Enhanced 设置中选择支持中文的字体GitHub 上表格错位书写时列数不对齐在 VS Code 中格式化表格或使用 markdownlint 检查语法Ctrl B没有生效Markdown All in One 插件未安装安装插件并重新加载窗口自动补全不出现不在 Markdown 文件中确认文件后缀为.md代码块点击无法运行 Code Runner 相关命令没有安装 Code Runner 插件在扩展面板安装 Code Runner 后再运行markdownlint 报了很多警告书写规范不一致阅读警告信息按提示修改格式或在设置中调整规则5.1 预览不刷新如果修改 Markdown 内容后预览长时间不更新可能是渲染进程卡住了。解决办法在预览面板点击刷新按钮。按下Ctrl Shift P输入Developer: Reload Window重新加载窗口。检查是否安装了多个 Markdown 预览插件某些插件之间会互相干扰。5.2 图片路径问题Markdown 中的图片路径有相对路径和绝对路径两种写法。推荐使用相对路径这样整个项目迁移时图片不会失效。例如项目根目录为my-blog图片在images/下Markdown 中写法为如果图片放在docs/下则路径应写成注意..表示上一级目录。5.3 代码块无法复制运行很多 Markdown 中的代码块本意是示例但读者直接复制可能报错原因通常是代码块内包含复制时多余的缩进。代码依赖特定环境而读者环境未满足。代码块语言标记错误导致没有高亮和可执行识别。所以在写 Markdown 文档时代码块一定要指定语言类型例如python、java、bash、yaml等并且保持缩进正确这样读者在 VS Code 中阅读时体验更好。6. 最佳实践与工程建议6.1 规范项目结构写 Markdown 不要把所有文档都堆在同一个目录下。建议按功能拆分目录project/ ├── docs/ │ ├── guide/ │ ├── api/ │ └── blog/ ├── images/ ├── templates/ ├── scripts/ ├── .vscode/ └── README.md技术文档的命名建议使用英文小写多个单词用连字符分隔例如getting-started.md、deploy-guide.md。这样在 Git 和命令行中操作时不会遇到大小写问题。6.2 坚持相对路径引用资源不论图片、附件还是其他文档都坚持使用相对路径避免出现这种绝对路径写法一旦项目整体移动或换电脑图片就会全部失效。相对路径写法适配更灵活也方便团队协作。6.3 用 markdownlint 保持格式统一团队协作时格式不统一会大幅增加 review 成本。推荐开启 markdownlint 插件并在.vscode/settings.json中选择适合团队的规则{ markdownlint.config: { MD024: false, MD033: false, MD041: false } }这三条的含义MD024允许不同标题下出现重复的小标题。MD033允许在 Markdown 中使用内联 HTML。MD041允许 Markdown 文件不强制以一级标题开头。实际项目中规则按团队习惯调整即可。6.4 自动化工作流把 Markdown 接入自动化流程可以极大提高效率使用 Git Hook 在提交时检查 Markdown 格式。使用 GitHub Actions 或 CI 将 Markdown 自动构建为 HTML 或 PDF。使用脚本扫描 Markdown 中的死链损坏的链接和图片。例如用 Node.js 写一个简单的脚本检查 Markdown 中引用的图片路径是否存在const fs require(fs); const path require(path); function checkImages(mdPath) { const content fs.readFileSync(mdPath, utf-8); const regex /!\[[^\]]*\]\(([^)])\)/g; let match; while ((match regex.exec(content)) ! null) { const imagePath path.resolve(path.dirname(mdPath), match[1]); if (!fs.existsSync(imagePath)) { console.log(图片不存在: ${match[1]}); } } } checkImages(./docs/article-1.md);这样每次写完文档后执行一次脚本就能排查缺失图片的问题。6.5 关于安全与隐私如果你用 Markdown 记录的是技术笔记、内部文档或涉及敏感信息的材料有几点建议不要把包含密钥、密码、内网地址的文档推到公开仓库。使用 Git 时配置.gitignore排除本地临时文件和敏感配置。如果使用云同步功能先确认服务端加密策略。生产环境和公司内部文档建议遵循团队最小权限原则只在授权范围内访问和分享。7. 总结VS Code 并不仅仅是一个代码编辑器它通过内置的 Markdown 预览、GFM 语法支持以及丰富的插件生态完全可以成为日常写 Markdown 的主力工具。从环境安装、基础配置到插件搭配、导出 PDF、Git 版本管理整套工作流都是基于纯文本文件不依赖私有格式长期使用稳定性高。如果你刚开始接触 Markdown建议先从这篇文章中的基础语法开始在 VS Code 里新建一个.md文件一边输入一边用Ctrl Shift V查看渲染效果很快就能熟悉。如果你已经积累了大量 Markdown 文档不妨试试把图片管理、格式检查和导出方案一并接入项目让写作和发布流程更顺滑。下一步可以继续研究 Pandoc 的更多转换能力、GitHub Actions 自动化构建以及如何把 Markdown 文档与个人博客、团队知识库打通。