Markdown 和 Visual Studio Code

在 Visual Studio Code 中处理 Markdown 文件简单、直接且有趣。除了 VS Code 的基本编辑功能外，还有一些 Markdown 特有的功能可以帮助您提高工作效率。

注意：为了帮助您开始编辑 Markdown 文件，您可以使用文档编写器配置文件模板来安装有用的扩展（拼写检查器、Markdown linter）并配置相应的设置值。

编辑 Markdown

文档大纲

大纲视图是文件资源管理器底部的一个独立部分。展开后，它显示当前活动编辑器的符号树。对于 Markdown 文件，符号树就是 Markdown 文件的标题层级结构。

大纲视图是查看文档标题结构和大纲的好方法。

Markdown 代码片段

VS Code 包含一些有用的代码片段，可以加快 Markdown 编写速度。这包括用于代码块、图片等的代码片段。编辑时按 ⌃Space (Windows, Linux Ctrl+Space)（触发建议）可查看建议的 Markdown 代码片段列表。您也可以通过在命令面板中选择 Insert Snippet 来使用专用代码片段选择器。

提示：您可以为 Markdown 添加自己的用户定义代码片段。请参阅用户定义代码片段以了解操作方法。

跳转到文件中的标题

使用 ⇧⌘O (Windows, Linux Ctrl+Shift+O) 快速跳转到当前文件中的标题。

您可以浏览文件中的所有标题，或者开始输入标题名称来查找所需的标题。找到所需标题后，按 Enter 将光标移动到该标题。按 Esc 取消跳转到标题。

跳转到工作区中的标题

使用 ⌘T (Windows, Linux Ctrl+T) 搜索当前工作区中所有 Markdown 文件中的标题。

开始输入标题名称以筛选列表并找到所需的标题。

路径补全

路径补全有助于创建到文件和图片的链接。在您输入图片或链接的路径时，这些路径会由 智能感知 (IntelliSense) 自动显示，也可以通过使用 ⌃Space (Windows, Linux Ctrl+Space) 手动请求。

以 / 开头的路径相对于当前工作区根目录解析，而以 ./ 开头或没有任何前缀的路径相对于当前文件解析。当您键入 / 时会自动显示路径建议，也可以通过使用 ⌃Space (Windows, Linux Ctrl+Space) 手动调用。

路径智能感知还可以帮助您链接到当前文件内或另一个 Markdown 文件内的标题。使用 # 开始路径可查看文件中所有标题的补全（根据您的设置，您可能需要使用 ⌃Space (Windows, Linux Ctrl+Space) 来查看这些建议）

您可以使用 "markdown.suggest.paths.enabled": false 禁用路径智能感知。

创建到另一个文件中标题的链接

需要链接到另一个 Markdown 文档中的标题，但记不住或不想输入完整的文件路径？试试使用工作区标题补全！首先，只需在 Markdown 链接中键入 ## 即可查看当前工作区中所有 Markdown 标题的列表

接受其中一个补全即可插入该标题的完整链接，即使它位于另一个文件中

您可以使用 markdown.suggest.paths.includeWorkspaceHeaderCompletions 设置来配置工作区标题补全是否显示以及何时显示。有效的设置值为

• onDoubleHash（默认）—仅在您键入 ## 后显示工作区标题补全。
• onSingleOrDoubleHash—在您键入 # 或 ## 后显示工作区标题补全。
• never—从不显示工作区标题补全。

请记住，查找当前工作区中的所有标题可能成本较高，因此首次请求时可能会有轻微延迟，尤其是对于包含大量 Markdown 文件的工作区。

插入图片和文件链接

除了路径补全之外，VS Code 还支持其他几种向 Markdown 文档插入图片和文件链接的方法

您可以从 VS Code 的文件资源管理器或您的操作系统中拖放文件到 Markdown 编辑器。首先，从 VS Code 的文件资源管理器中将文件拖到您的 Markdown 代码上，然后按住 Shift 开始将其放到文件中。预览光标会显示您放下文件时将插入的位置。

如果您更喜欢使用键盘，您还可以复制并粘贴文件或图片数据到 Markdown 编辑器。当您粘贴文件、文件链接或 URL 时，您可以选择插入 Markdown 链接或将其作为纯文本包含。

或者您可以使用Markdown: 从工作区插入图片命令来插入图片，使用Markdown: 从工作区插入文件链接命令来插入文件链接。

插入的图片使用 Markdown 图片语法 ![](path/to/image.png)。链接插入普通的 Markdown 链接 [](path/to/file.md)。

默认情况下，VS Code 会自动将工作区外部拖放或粘贴的图片复制到您的工作区中。markdown.copyFiles.destination 设置控制新图片文件的创建位置。此设置将与当前 Markdown 文档匹配的 glob 模式映射到图片目标位置。图片目标位置还可以使用一些简单变量。有关可用变量的信息，请参阅 markdown.copyFiles.destination 设置的描述。

例如，如果您希望工作区中 /docs 下的每个 Markdown 文件都将新的媒体文件放入特定于当前文件的 images 目录中，您可以这样编写

"markdown.copyFiles.destination": {
  "/docs/**/*": "images/${documentBaseName}/"
}

现在，当新文件粘贴到 /docs/api/readme.md 中时，图片文件将在 /docs/api/images/readme/image.png 创建。

您甚至可以使用简单的正则表达式以类似于代码片段的方式转换变量。例如，此转换在创建媒体文件时仅使用文档文件名的第一个字母

"markdown.copyFiles.destination": {
  "/docs/**/*": "images/${documentBaseName/(.).*/$1/}/"
}

当新文件粘贴到 /docs/api/readme.md 中时，图片现在将在 /docs/api/images/r/image.png 创建。

为图片生成 alt 文本

您可以使用 AI 为 Markdown 文件中的图片生成或更新 alt 文本。要生成 alt 文本

1. 请确保您已在 VS Code 环境中设置 Copilot。您可以免费开始使用 Copilot。

2. 打开一个 Markdown 文件。

3. 将光标放在图片链接上。

4. 选择代码操作（灯泡）图标并选择生成 alt 文本。

   

5. 如果您已有 alt 文本，请选择代码操作，然后选择优化 alt 文本。

智能选择

智能选择让您可以快速扩展和收缩 Markdown 文档中的选择范围。这可用于快速选择整个块元素（如代码块或表格）以及选择 Markdown 文件中标题部分的全部内容。

智能选择使用以下命令

• 扩展: ⌃⇧⌘→ (Windows, Linux Shift+Alt+Right)
• 收缩: ⌃⇧⌘← (Windows, Linux Shift+Alt+Left)

选择范围适用于以下内容，并遵循传统的层级模式

• 标题
• 列表
• 块引用
• 围栏式代码块
• Html 代码块
• 段落

链接验证

链接验证会检查 Markdown 代码中的本地链接，以确保它们有效。这可以捕获常见错误，例如链接到已重命名的标题或磁盘上不再存在的文件。

链接验证默认处于关闭状态。要启用它，请设置 "markdown.validate.enabled": true。然后，VS Code 会分析指向标题、图片和其他本地文件的 Markdown 链接。无效链接会报告为警告或错误。所有链接验证都在本地进行，不检查外部 http(s) 链接。

您可以使用一些设置来自定义链接验证

• markdown.validate.fileLinks.enabled - 启用/禁用指向本地文件的链接验证：[link](/path/to/file.md)
• markdown.validate.fragmentLinks.enabled - 启用/禁用指向当前文件中标题的链接验证：[link](#_some-header)
• markdown.validate.fileLinks.markdownFragmentLinks - 启用/禁用指向其他 markdown 文件中标题的链接验证：[link](other-file.md#some-header)
• markdown.validate.referenceLinks.enabled - 启用/禁用引用链接验证：[link][ref]。
• markdown.validate.ignoredLinks - 跳过验证的链接 glob 列表。如果您链接到磁盘上不存在但 Markdown 发布后存在的文件，这将很有用。

查找标题和链接的所有引用

使用查找所有引用 (⇧⌥F12 (Windows, Linux Shift+Alt+F12)) 命令查找当前工作区中引用 Markdown 标题或链接的所有位置

查找所有引用支持以下内容：

• 标题：# My Header。显示所有指向 #my-header 的链接。
• 外部链接：[text](http://example.com)。显示所有指向 http://example.com 的链接。
• 内部链接：[text](./path/to/file.md)。显示所有指向 ./path/to/file.md 的链接。
• 链接中的片段：[text](./path/to/file.md#my-header)。显示 ./path/to/file.md 中所有指向 #my-header 的链接。

重命名标题和链接

厌倦了更改 Markdown 标题时意外破坏链接？试试使用重命名符号 (F2)。在您输入新标题名称并按 Enter 后，VS Code 会更新标题并自动更新所有指向该标题的链接。

您还可以在以下内容上使用 F2：

• 标题：# My Header。这将更新所有指向 #my-header 的链接。
• 外部链接：[text](http://example.com/page)。这将更新所有链接到 http://example.com/page 的位置。
• 内部链接：[text](./path/to/file.md)。这将重命名文件 ./path/to/file.md 并更新所有指向它的链接。
• 链接中的片段：[text](./path/to/file.md#my-header)。这将重命名 ./path/to/file.md 中的标题并更新所有指向它的链接。

文件移动或重命名时自动更新链接

启用自动 Markdown 链接更新后，VS Code 会在链接的文件被移动或重命名时自动更新 Markdown 链接。您可以使用 markdown.updateLinksOnFileMove.enabled 设置启用此功能。有效的设置值为

• never（默认）— 不自动尝试更新链接。
• prompt — 更新链接前确认。
• always — 无需确认自动更新链接。

自动链接更新可检测 Markdown 文件、图片和目录的重命名。您可以使用 markdown.updateLinksOnFileMove.include 为其他文件类型启用此功能。

Markdown 预览

VS Code 原生支持 Markdown 文件。您只需开始编写 Markdown 文本，将文件保存为 .md 扩展名，然后即可在代码和 Markdown 文件预览之间切换编辑器的视图；显然，您也可以打开现有的 Markdown 文件并开始使用它。要在视图之间切换，请在编辑器中按 ⇧⌘V (Windows, Linux Ctrl+Shift+V)。您可以将预览与正在编辑的文件并排显示，并在编辑时实时看到更改反映在预览中。

这是一个简单文件的示例。

提示：您也可以右键单击编辑器选项卡并选择打开预览 (⇧⌘V (Windows, Linux Ctrl+Shift+V))，或使用命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行Markdown: 打开侧边预览命令 (⌘K V (Windows, Linux Ctrl+K V))。

动态预览和预览锁定

默认情况下，Markdown 预览会自动更新以预览当前活动的 Markdown 文件

您可以使用Markdown: 切换预览锁定命令锁定 Markdown 预览，使其保持锁定到当前 Markdown 文档。锁定的预览在标题中显示为 [预览]

注意：Markdown: 切换预览锁定命令仅在 Markdown 预览是活动选项卡时可用。

编辑器和预览同步

VS Code 会自动同步 Markdown 编辑器和预览窗格。滚动 Markdown 预览时，编辑器会滚动以匹配预览的视口。滚动 Markdown 编辑器时，预览会滚动以匹配其视口。

您可以使用 markdown.preview.scrollPreviewWithEditor 和 markdown.preview.scrollEditorWithPreview 设置来禁用滚动同步。

编辑器中当前选定的行在 Markdown 预览左侧边距中以浅灰色条表示

此外，双击 Markdown 预览中的元素会自动打开相应文件的编辑器并滚动到最接近单击元素的行。

数学公式渲染

VS Code 内置的 Markdown 预览使用 KaTeX 渲染数学公式。

内联数学公式用单个美元符号包裹

Inline math: $x^2$

您可以用双美元符号创建数学公式块

Math block:

$$
\displaystyle
\left( \sum_{k=1}^n a_k b_k \right)^2
\leq
\left( \sum_{k=1}^n a_k^2 \right)
\left( \sum_{k=1}^n b_k^2 \right)
$$

您可以将 "markdown.math.enabled": false 设置为禁用 Markdown 文件中的数学公式渲染。

扩展 Markdown 预览

扩展可以为 Markdown 预览贡献自定义样式和脚本，以改变其外观并添加新功能。以下是一些自定义预览的示例扩展集

使用您自己的 CSS

您还可以使用 "markdown.styles": [] 设置在 Markdown 预览中使用您自己的 CSS。此设置列出了要在 Markdown 预览中加载的样式表的 URL。这些样式表可以是 https URL，或当前工作区中本地文件的相对路径。

例如，要在当前工作区的根目录加载名为 Style.css 的样式表，请使用 文件 > 首选项 > 设置打开工作区 settings.json 文件并进行此更新

// Place your settings in this file to overwrite default and user settings.
{
  "markdown.styles": ["Style.css"]
}

保留末尾空格以便创建换行

要创建硬换行，Markdown 需要在一行的末尾有两个或更多空格。根据您的用户或工作区设置，VS Code 可能配置为移除末尾空格。为了仅在 Markdown 文件中保留末尾空格，您可以将以下行添加到您的 settings.json 中

{
  "[markdown]": {
    "files.trimTrailingWhitespace": false
  }
}

Markdown 预览安全性

出于安全原因，VS Code 会限制 Markdown 预览中显示的内容。这包括禁用脚本执行，并且仅允许通过 https 加载资源。

当 Markdown 预览阻止页面上的内容时，会在预览窗口右上角显示一个警告弹出窗口

您可以通过单击此弹出窗口或在任何 Markdown 文件中运行Markdown: 更改预览安全设置命令来更改 Markdown 预览中允许的内容。

Markdown 预览安全设置适用于工作区中的所有文件。

以下是关于这些安全级别中的每一个的详细信息

严格

这是默认设置。仅加载可信内容并禁用脚本执行。阻止 http 图片。

建议您保持 严格 安全性启用，除非您有非常好的理由更改它并且您信任工作区中的所有 Markdown 文件。

允许不安全内容

保持脚本禁用，但允许通过 http 加载内容。

禁用

禁用预览窗口中的额外安全设置。这允许脚本执行，并允许通过 http 加载内容。

文档编写器配置文件模板

配置文件让您可以根据当前的项目或任务快速切换扩展、设置和 UI 布局。为了帮助您开始编辑 Markdown，您可以使用文档编写器配置文件模板，这是一个精选的包含有用扩展和设置的配置文件。您可以直接使用配置文件模板，或将其作为起点根据您自己的工作流程进一步自定义。

通过配置文件 > 创建配置文件... 下拉菜单选择配置文件模板

选择配置文件模板后，您可以查看设置和扩展，并删除不想包含在新配置文件中的单个项目。基于模板创建新配置文件后，对设置、扩展或 UI 所做的更改将保留在您的配置文件中。

Markdown 扩展

除了 VS Code 原生提供的功能之外，您还可以安装扩展以获得更强大的功能。

提示：选择一个扩展磁贴阅读描述和评论，以决定哪个扩展最适合您。在市场中查看更多信息。

后续步骤

继续阅读以了解关于

• CSS、SCSS 和 Less - 想要编辑您的 CSS 吗？VS Code 对 CSS、SCSS 和 Less 编辑提供了很好的支持。

常见问题

有拼写检查功能吗？

未随 VS Code 安装，但有拼写检查扩展。请查看VS Code 市场以查找有助于您工作流程的有用扩展。

VS Code 支持 GitHub Flavored Markdown 吗？

不，VS Code 使用 markdown-it 库实现 CommonMark Markdown 规范。GitHub 正在向 CommonMark 规范靠拢，您可以在这篇更新中了解详情。