企业官网建设流程全解析

VS Code 的 Markdown 编辑能力一直以“开箱即用”著称，但很多使用者只是把它当成一个带高亮的写字板：写完一边开预览一边复制到其他地方发布。真正把 VS Code 当成主力 Markdown 编辑器之后，才会注意到预览如何同步定位、目录如何生成、表格为什么总是对不齐、粘贴图片之后路径为什么会乱。这篇文章围绕 VS Code 内置并持续更新中的 Markdown 编辑功能，梳理一条从安装、配置、编辑、预览到导出发布的完整路径。文章会区分哪些能力是内置的、哪些需要扩展补齐，并且给出可复现的快捷键、配置文件、扩展组合和常见问题排查方法。适合常写技术文档、博客、接口说明、团队 Wiki 的开发者，也适合想从其他编辑器切换到 VS Code 的写作用户。

1. VS Code 的 Markdown 编辑功能到底包含什么

1.1 先理解“内置”和“扩展”的边界

VS Code 对 Markdown 的支持不是靠某个默认插件完成的，而是核心编辑器自带语言服务。安装完 VS Code 之后，打开.md文件就能获得三块基础能力：Markdown 源码语法高亮、Markdown 预览、基于标题的文件符号跳转。这个语言服务跟随编辑器一起升级，所以“新的 Markdown 编辑功能”通常分成两类：一类是官方在版本迭代中加入的内置能力，比如预览与编辑器同步滚动、任务列表渲染、数学公式支持、相对路径补全；另一类是社区扩展提供的增强能力，比如目录自动生成、格式校验、导出 PDF 或 Word。

写技术文章的人最容易犯的错误，是一上来就装一堆扩展，结果不知道哪些特性是内置的，换一台机器之后写作习惯完全被打乱。正确做法是先摸清内置能力，再针对短板补扩展。这也能解释为什么同一份 Markdown 文件在别人电脑上显示效果不同：要么是扩展不同，要么是预览设置不同。

1.2 编辑链路里值得关注的核心模块

一个完整的 Markdown 写作流程由六个模块组成：编辑、预览、导航、校验、导出、版本管理。VS Code 内置解决前三个，后三个需要靠扩展、命令行工具或工作流补全。

• 编辑：包括源码语法高亮、粗体斜体快捷键、列表缩进、代码块包裹、图片链接路径补全。
• 预览：包括当前页预览、分栏预览、锁定预览、同步滚动、自定义 CSS 样式。
• 导航：包括大纲面板、标题跳转、文档折叠、页内链接跳转。
• 校验：主要靠 markdownlint 等扩展，快速发现标题重复、列表缩进混乱、链接失效等问题。
• 导出：可以靠扩展或 pandoc 等工具，把 Markdown 转成 HTML、PDF、Word。
• 版本管理：Markdown 是纯文本，天然适合放进 Git，这是它作为技术文档格式最大的优势。

之后的章节会按这条链路逐个展开。先准备环境。

2. 安装 VS Code、确认版本与做基础配置

2.1 安装和版本确认

开始之前，先保证本机装的是官方版本，并确认当前版本可用。安装完成后，在终端里执行：

code --version

如果命令不存在，说明安装时没有把可执行文件加入 PATH。常见处理方式：Windows 安装时勾选“添加到 PATH”；macOS 安装后手动打开一次应用；Linux 根据安装包类型确认软链接是否创建。具体以你自己的安装渠道为准。

还可以通过扩展列表确认当前环境是否被改动过：

code --list-extensions

如果看到大量 Markdown 相关扩展，后面排错时就要多考虑扩展冲突。对于团队协作项目，建议先在干净环境里验证内置能力，再逐步加扩展。

2.2 用 settings.json 固定体验

Markdown 预览效果在不同电脑上不一样，很多原因出在用户设置不一致。建议在项目根目录放一个.vscode/settings.json，把写作相关的设置固化下来，而不是全部写在全局用户设置里。

{ "editor.wordWrap": "on", "editor.quickSuggestions": { "other": "on", "comments": "off", "strings": "off" }, "files.encoding": "utf8", "files.autoGuessEncoding": true, "files.eol": "\n", "markdown.preview.fontSize": 15, "markdown.preview.lineHeight": 1.8, "markdown.preview.breaks": false, "markdown.preview.scrollPreviewWithEditor": true, "markdown.preview.scrollEditorWithPreview": true, "markdown.preview.doubleClickToSwitchToEditor": true, "markdown.styles": [] }

关键设置项说明如下：

这里特别说明markdown.preview.breaks。把它设为 true 时，预览看起来更像普通富文本编辑器，但发布到 GitHub、掘金等平台时换行规则通常不同，容易造成“本地这样、发布后那样”的错觉。如果以跨平台发布为目标，建议保持 false，依赖空行分段。

2.3 验证配置是否生效

修改配置后不需要重启。打开任意.md文件，按Ctrl+Shift+V打开预览；对比预览和源码区，字体、行距、换行应符合预期。也可以在命令面板里输入“Open User Settings (JSON)”检查当前生效的文件路径。

注意：settings.json 分全局、工作区和文件夹三级，工作区配置会覆盖全局配置。排错时先看当前工作区是否生效了错误的配置，再考虑扩展问题。

3. 预览、快捷键与大纲：把内置功能用熟练

3.1 三种预览方式

VS Code 内置的 Markdown 预览并不只一种打开方式：

• Ctrl+Shift+V：在当前标签页切换预览。
• Ctrl+K V：在右侧打开分栏预览，这是写作时最常用的方式。
• 命令面板里输入 “Markdown: Open Preview to the Side”，也可以实现分栏预览。

分栏预览和编辑器之间默认会同步滚动。光标在源码中移动时，预览会滚动到对应位置；反过来，双击预览中的内容，会跳回源码对应行。这个能力由markdown.preview.doubleClickToSwitchToEditor控制。

如果同时打开多个 Markdown 文件，可以执行 “Markdown: Open Locked Preview” 锁定某个文件对应的预览，避免切换文件时预览跟着跳走。这个功能在对比两份文档时很好用。

3.2 高频编辑快捷键

Markdown 文件里能用的快捷键，一部分是编辑器的通用能力，一部分是 Markdown 语言服务提供的。常用如下：

默认键位可能被某些扩展覆盖。如果按Ctrl+B没反应而弹出了其他功能，基本可以判断是键位冲突；需要在键盘快捷方式里搜索对应的加粗命令，检查绑定情况。具体命令名称以当前版本的命令面板显示为准。

3.3 大纲、折叠与目录定位

大纲是内置编辑器里最容易被低估的功能。资源管理器下方的 OUTLINE 面板会按标题层级生成文档结构。光标放在某个标题上，大纲中会同步高亮；点击大纲项会跳到源码对应位置。这个面板对 500 行以上的长文档尤其有用。

折叠功能配合标题层级也很顺手。当光标停在一个标题行时，行号区会出现小箭头，点击即可折叠整个章节；也可以使用Ctrl+Shift+[折叠区域。注意 Markdown 的折叠依赖标题层级，如果文档里把###当加粗用，大纲和折叠都会变得混乱。

4. 公式、任务列表、目录与图片：把长文档写得更专业

4.1 数学公式渲染

VS Code 内置预览支持数学公式渲染，所以.md里可以直接写 LaTeX 风格的公式。行内公式用单个美元符号包起来，独立公式用两个美元符号包起来，而且独立公式的$$前后通常要单独占一行，否则解析可能失败。

能量守恒可以用行内公式 $E=mc^2$ 表示。 $$ \int_{-\infty}^{+\infty} e^{-x^2} dx = \sqrt{\pi} $$

预览中如果公式显示为纯文本，先检查是不是把$写成了中文全角符号，或者公式内容里包含了预览不支持的语法。内置公式渲染支持的语法和完整 LaTeX 有差异，比较复杂的宏包命令需要先查当前版本支持范围。

4.2 GFM 任务列表与其他扩展语法

VS Code 的 Markdown 预览遵循 GitHub Flavored Markdown 子集，所以任务列表、删除线、自动链接、表格都支持。

- [ ] 整理环境 - [x] 完成配置 - [x] 写作正文

这里要注意列表和代码块的缩进关系。如果任务列表项下面再嵌套代码块，代码块需要缩进到列表级别，否则会被当成新的顶层代码块。表格的列对齐符号也不是随便写的，分隔行至少需要三个短横线，否则表格不会被识别。

4.3 标题锚点与快速目录定位

Markdown 里的标题可以直接做页内跳转，形式是[文字](#标题)。GitHub 风格锚点规则是：标题英文小写、空格转短横、去除标点。例如标题“VSCode 基础配置”对应锚点#vscode-基础配置。这属于内置能力，不需要插件。

更省事的方式是使用Ctrl+Shift+O快速跳标题。如果是生成真正意义上的目录，建议交给扩展而不是手工维护，因为标题一旦改动，手工目录很容易过期。后面介绍扩展时再细说。

4.4 图片路径的正确写法

写作中插图片，最大的坑是路径。推荐在项目里固定一个图片目录：

docs/ README.md assets/ images/ 01-preview.png

在 README.md 里引用时写相对路径：

![预览效果](./assets/images/01-preview.png)

VS Code 在源码里输入图片路径时，可以通过Ctrl+Space触发路径补全，这是内置能力。路径中尽量使用正斜杠和英文文件名；图片放进 Git 仓库，发布到 GitHub 等平台也能继续显示。如果图片只存在于本地绝对路径，发布后必然失效。

5. 用扩展补齐短板：校验、目录与导出

5.1 Markdown All in One：目录、格式化与写作提速

Markdown All in One 是社区里最常用的 Markdown 写作扩展之一。它解决的问题都很具体：自动生成 TOC、列表自动延续、加粗斜体快捷键、选中文字转链接、标题升降级等。例如命令 “Markdown: Create Table of Contents” 会根据文档标题生成目录，并支持刷新。它也会在按回车时自动延续列表，减少手工输入。

这类扩展是“内置能力不够用”时的补充。要避免的是装了扩展却不了解它的默认行为，比如有些扩展会重排列表编号，可能和你自己的排版习惯冲突。

5.2 markdownlint：把格式问题拦在发布前

markdownlint 是按规则检查 Markdown 格式的扩展。它以 MD 开头作为规则编号，常见的有：

可以在项目根目录放.markdownlint.json：

{ "default": true, "MD013": false, "MD024": { "siblings_only": true } }

这样团队里所有人打开项目都会遵守同一套校验规则，避免格式问题反复出现在 Code Review 里。

5.3 导出 HTML、PDF 与 Word

VS Code 内置预览主要解决“看效果”的问题，发布和交付通常需要导出。Markdown PDF 这类扩展可以导出 HTML、PDF、PNG；pandoc 更适合批量转换和复杂文档：

pandoc input.md -o output.docx

pandoc input.md -o output.html -s --metadata title="标题"

日常写作里，导出 Word 的需求很常见。比较稳妥的路线是先用 pandoc 转换 Docx，再在 Word 里做少量排版。如果团队已经在使用 Coze 这类工作流平台，也可以把“Markdown 转 Word”封装成自动化工作流，减少本地重复操作。这类工作流的具体配置依赖平台当前能力，落地前先确认支持的格式范围。

6. 个人写作和团队文档的落地差异

6.1 个人笔记与生产环境的取舍

个人笔记场景追求快速：在全局 settings.json 里打开 word wrap，按Ctrl+K V直接预览，不需要 lint。团队文档场景追求稳定：项目根目录必须有统一的 settings.json、.markdownlint.json、图片目录约定，并且建议在 CI 里加一道 Markdown 格式检查，防止每个人提交的文档风格不一致。

生产环境还要考虑文档发布到哪里、链接是相对路径还是绝对路径、图片是否托管在仓库内。这些决定换平台时是否需要批量改路径。我的建议是：个人笔记可以自由，团队仓库必须有约定，因为文档的可维护性往往取决于这些细节。

6.2 一个可复用的团队文档目录

如果团队还没有约定，可以按下面结构起步：

docs/ .vscode/ settings.json .markdownlint.json README.md guide/ _index.md install.md specification/ api.md assets/ images/

约定：所有图片放进 assets/images，正文只使用相对路径引用；每个子目录可以有 README 作为入口；settings.json 和 markdownlint 放根目录，确保不同成员体验一致。这个目录不是强制标准，而是给新项目一个能直接复用的起点。

6.3 写作前检查清单

发布或提交之前，建议按下面清单快速过一遍：

• 文件编码为 UTF-8，换行符统一。
• 标题层级连续，不出现 1 级直接跳到 3 级的情况。
• 重复标题已处理，避免锚点冲突。
• 所有图片路径存在，且使用相对路径。
• 表格分隔行完整，列数一致。
• 代码块都带语言标记。
• markdownlint 没有 Error 级别问题。
• 预览中公式、任务列表、链接跳转均正常。

这个清单同样可以放进团队文档模板里，作为 PR 检查项。

7. 常见问题排查：预览空白、表格错乱、图片不显示

7.1 预览打不开或显示空白

现象：按Ctrl+Shift+V没反应，或者预览窗口一片空白。

按顺序排查：

1. 检查当前文件后缀是不是.md。后缀为.txt时不会启用 Markdown 预览。
2. 在命令面板执行 “Markdown: Open Preview”，确认命令是否正常。
3. 检查是否被扩展覆盖了快捷键，在键盘快捷方式里搜索markdown.showPreview查看绑定。
4. 禁用最近安装的 Markdown 相关扩展，再打开预览。
5. 如果预览空白但源码正常，检查是否有自定义markdown.styles引用了不存在的 CSS。

7.2 表格没有渲染成表格

现象：写好的表格在预览里变成普通纯文本。

最常见原因是分隔行不对。正确的表格必须有表头、分隔行和至少一行数据：

| 名称 | 用途 | | --- | --- | | 内置预览 | 快速查看渲染效果 |

错误写法常常是少了|---|---|这一行，或者把分隔行写成了单横线。另一个问题是单元格内部有竖线，比如时间|2024，需要使用转义字符\|，否则表格结构会被截断。

7.3 图片显示为破图

现象：源码路径正确，预览里却显示图片加载失败。

检查顺序：

1. 路径大小写是否和实际文件名完全一致。
2. 相对路径的基准是否正确，相对路径从当前文件所在目录开始计算。
3. 文件名是否包含中文、空格或特殊符号。本地预览可能正常，发布到平台后编码规则不同会失效。
4. 是否使用了C:\Users\...这样的绝对路径，换成相对路径再验证。

7.4 修改标题后源码里的 # 不见了

现象：鼠标移到标题行时能看到 #，光标移开后 # 消失，或者标题显示成富文本样式。

这通常不是 VS Code 内置源码视图的行为，而是某个 Markdown 增强扩展开启了“所见即所得”模式，把 Markdown 语法标记隐藏了。处理方法：打开扩展管理，检查最近安装或正在使用的 Markdown 写作增强插件，在插件设置里搜索 hide、marker、source、WYSIWYG 等关键词，关闭对应的隐藏语法标记选项。更稳妥的方式是暂时禁用该扩展，回到源码视图完成编辑，再决定是否重新开启。

7.5 预览和源码不同步

现象：源码滚动，预览不动，或预览滚动源码不跟随。

检查设置中的markdown.preview.scrollPreviewWithEditor和markdown.preview.scrollEditorWithPreview是否为 true。如果文档里使用了大量 HTML 块或自定义锚点，同步定位偶尔会不准，属于正常现象，不需要过度处理。

8. 最佳实践与扩展方向

8.1 一套可以直接复制的写作配置

把下面的 settings.json 作为个人写作起点，再根据显示器、字体和团队要求微调：

{ "editor.wordWrap": "on", "editor.fontSize": 15, "files.encoding": "utf8", "files.eol": "\n", "files.trimTrailingWhitespace": true, "markdown.preview.fontSize": 15, "markdown.preview.lineHeight": 1.8, "markdown.preview.breaks": false, "markdown.preview.scrollPreviewWithEditor": true, "markdown.preview.scrollEditorWithPreview": true }

8.2 高频快捷键速查

8.3 下一步可以扩展的方向

如果已经熟悉内置功能，下一步可以按场景扩展：做演示文稿可以用 Marp 类扩展，用 Markdown 写幻灯片；需要统一预览样式，可以把 `markdown.st