写在前面

Markdown 的门槛很低，但“能写”和“能高效维护长文档”是两件事。当一篇文章包含几十个标题、大量代码块、图片和相对链接时，工具应该帮我们看清结构、快速跳转、即时预览并在提交前发现问题。

VS Code 对 Markdown 的内置支持已经覆盖编辑、大纲、跳转、预览、智能提示和链接校验等常见需求。本文先用好内置能力，再讨论扩展。

快捷键会受操作系统、键盘布局和用户自定义影响。如果本文键位与本机不同，在命令面板搜索命令名，或打开 Preferences: Open Keyboard Shortcuts 查看当前绑定。

一、把文章目录作为工作区打开

不要只打开一个孤立的 index.md，而是打开项目或文章目录：

1

code .

这样文件搜索、全文搜索、图片路径、Git 差异和工作区标题跳转才有完整上下文。

常用入口：

• Ctrl+P：按文件名快速打开。
• Ctrl+Shift+P：打开命令面板。
• Ctrl+Shift+F：在工作区全文搜索。
• Ctrl+Shift+E：切换到资源管理器。
• Ctrl+Shift+G：查看 Git 更改。

本文快捷键以 Windows / Linux 为主；macOS 可在命令面板中搜索同名命令查看当前绑定。

二、预览 Markdown

• Ctrl+Shift+V：在当前编辑器打开预览。
• Ctrl+K V：在侧边打开预览。

侧边预览最适合写作：左边编辑源码，右边观察标题、列表、代码块和图片的实际结构。VS Code 会在源码与预览之间同步滚动。

预览不等于最终站点渲染。Hugo 主题、Shortcode、Goldmark 配置和自定义 CSS 可能导致差异，因此文章完成后仍要用 Hugo 预览。

三、用大纲审查文章结构

资源管理器底部的 Outline 会把 Markdown 标题显示为树。它不只用于跳转，还能发现结构问题：

• ## 后突然出现 ####，可能跳级。
• 同级标题粒度明显不一致。
• 某一节层级过深，可能需要拆分。

Ctrl+Shift+O 在当前文件的标题间跳转，Ctrl+T 可搜索工作区中的符号，也能找到 Markdown 标题。

长文章中还可使用折叠：点击行号右侧的折叠控件，或通过命令面板执行 Fold All、Unfold All。

四、多光标与批量编辑

• Alt+单击：添加光标。
• Ctrl+Alt+↑/↓：在上下行添加光标。
• Ctrl+D：选中下一个匹配项。
• Ctrl+Shift+L：选中所有匹配项。
• Alt+↑/↓：上下移动当前行或选区。
• Shift+Alt+↑/↓：向上或向下复制。

典型用法包括为多行同时加列表符号、批量更换标题前缀，以及把一组纯文本改成表格列。

五、Markdown 编辑的内置能力

在 Markdown 中按 Ctrl+Space 可触发建议，VS Code 内置了链接、图片和代码块等 Snippet。

输入链接时，VS Code 可以对工作区文件、标题锚点和路径提供补全。对于长期维护的文档库，这比手工输入路径更安全。

建议打开以下编辑器能力：

1
2
3
4
5
6
7
8

{
  "editor.wordWrap": "on",
  "editor.minimap.enabled": false,
  "editor.renderWhitespace": "boundary",
  "files.trimTrailingWhitespace": true,
  "markdown.validate.enabled": true,
  "markdown.updateLinksOnFileMove.enabled": "prompt"
}

markdown.updateLinksOnFileMove.enabled 能在 Markdown 文件或被链接资源移动时提示更新链接。提交前仍应检查 Git Diff，确认没有扩大替换范围。

六、表格、代码块与图片

6.1 表格

表格应优先表达对照关系，不要用它承载长段落。原始 Markdown 不必强行手工对齐，但列数必须一致。

1
2
3
4
5

| Tool | Pipeline | Platform |
| --- | --- | --- |
| Batch | Text | Windows |
| PowerShell | Object | Cross-platform |
| Bash | Text | Unix-like |

6.2 代码块

围栏后注明语言，这会影响语法高亮：

1
2
3

```powershell
Get-ChildItem | Where-Object Length -GT 1MB
```

内层包含三个反引号时，外层示例可以使用四个反引号，避免提前闭合。

6.3 Hugo Leaf Bundle 图片

1
2
3

my-post/
├── index.md
└── pipeline.png

1

![命令处理流程](pipeline.png)

图片与 index.md 放在一起，文章目录移动时资源也会一起移动。不要用只在本机成立的绝对路径。

七、专注写作与阅读

• Ctrl+K Z：进入 Zen Mode，隐藏大部分界面。
• Esc Esc：退出 Zen Mode。
• View: Toggle Centered Layout：将编辑区居中，减少超宽屏上的视线移动。
• View: Toggle Word Wrap：在当前文件切换自动换行。

阅读长文时，可以将预览放在单独的编辑器组，锁定预览后再在左侧切换其他文件，避免预览页被活动文件跟随切换。

八、Snippet：固化文章骨架

通过 Preferences: Configure User Snippets 为 Markdown 创建 Snippet：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "Hugo post skeleton": {
    "prefix": "hpost",
    "body": [
      "+++",
      "date = '${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}T10:00:00+08:00'",
      "draft = true",
      "title = '$1'",
      "categories = ['$2']",
      "tags = ['$3']",
      "+++",
      "",
      "## 写在前面",
      "",
      "$0"
    ],
    "description": "Create a Hugo post skeleton"
  }
}

Snippet 适合固定格式，不适合复制大段通用套话。文章结构应由主题决定，而不是被模板限制。

九、扩展的选择原则

先确认内置功能是否已经满足需求，再安装扩展。常见需求可以分为：

• Markdown lint：检查标题、列表、空行和围栏等风格。
• 拼写检查：适合英文文档，但需为专业词汇维护字典。
• 粘贴图片：将剪贴板图片保存到指定目录并插入链接。
• 表格格式化：降低手工对齐成本。

安装前检查发布者、最近更新、权限和工作区信任模式下的行为。扩展会执行代码，不应把“装得多”当成功能完整的标志。

十、Hugo 文章的完整工作流

10.1 创建文章

1

hugo new posts/devtools/my-post/index.md

10.2 编写时

1. 用 Outline 先建立标题骨架。
2. 使用 Ctrl+K V 侧边预览。
3. 图片放到 index.md 旁边，使用相对路径。
4. 代码围栏注明语言。
5. 使用工作区搜索核对内部链接和系列名。

10.3 本地预览

1

hugo server --buildDrafts --buildFuture

VS Code 的 Markdown 预览负责快速反馈，Hugo 预览负责最终语义。两者不应互相取代。

10.4 提交前

1. 确认 front matter 和 draft 状态。
2. 通过 Outline 检查标题层级。
3. 确认图片都存在。
4. 检查围栏是否成对。
5. 在 Source Control 中逐块阅读差异。
6. 发布文章时同步 posts-index.md。
7. 执行生产等价 Hugo 构建。

十一、最值得记住的快捷键

真正提升 Markdown 体验的不是背下所有快捷键，而是形成稳定闭环：用大纲控制结构，用侧边预览检查表达，用工作区能力管理资源与链接，用 Git Diff 守住最后一关。

参考资料

• Visual Studio Code：Markdown and Visual Studio Code
• Visual Studio Code：Basic Editing
• Visual Studio Code：Default Keyboard Shortcuts