Markdown 和 Visual Studio Code

在 Visual Studio Code 中使用 Markdown 文件非常简单、直接，也很有趣。除了 VS Code 的基本编辑功能外，还有一些特定于 Markdown 的功能可以帮助您提高效率。

注意：为了帮助您开始编辑 Markdown 文件，您可以使用 Doc Writer 配置文件模板 安装有用的扩展（拼写检查器、Markdown 代码检查器）并配置适当的设置值。

编辑 Markdown

文档大纲

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

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

Markdown 代码片段

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

提示：您可以为 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) 手动调用。

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

您可以使用 "markdown.suggest.paths.enabled": false 禁用路径 IntelliSense。

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

需要链接到另一个 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 文档匹配的 通配符 映射到图像目标。图像目标也可以使用一些简单的变量。有关可用变量的信息，请参阅 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 下创建。

智能选择

智能选择可以让您快速扩展和缩小 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 - 跳过验证的链接通配符列表。如果您链接到磁盘上不存在但 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)。您可以使用正在编辑的文件并排查看预览 (⌘K V (Windows、Linux Ctrl+K 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 文档。锁定的预览在标题中用 [Preview] 表示

注意：仅当 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 预览中使用您自己的 CSS，方法是使用 "markdown.styles": [] 设置。这将列出要在 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 加载内容。

Doc Writer 配置文件模板

配置文件 让您根据当前项目或任务快速切换扩展、设置和 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 使用 CommonMark Markdown 规范，并使用 markdown-it 库。GitHub 正在转向 CommonMark 规范，您可以在此 更新 中阅读相关信息。