Markdown 和 Visual Studio Code

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

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

编辑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)手动调用。

Path IntelliSense 还可以帮助您链接到当前文件或另一个 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 文档的 globs 映射到图像目标。图像目标也可以使用一些简单的变量。有关可用变量的信息，请参阅 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)。显示所有指向#my-header的链接在./path/to/file.md中

重命名标题和链接

厌倦了在更改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: Toggle Preview Locking命令锁定Markdown预览，以保持其锁定在当前Markdown文档上。锁定的预览在标题中由[Preview]表示：

注意： Markdown: Toggle Preview Locking 命令仅在 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图像。

我们建议您保持启用Strict安全设置，除非您有充分的理由更改它并且您信任工作区中的所有Markdown文件。

允许不安全内容

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

禁用

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

文档编写者个人资料模板

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

您通过Profiles > Create Profile...下拉菜单选择一个配置文件模板：

一旦你选择了一个配置文件模板，你可以查看设置和扩展，并且如果不想将它们包含在你的新配置文件中，可以移除个别项目。基于模板创建新配置文件后，对设置、扩展或用户界面的更改将保存在你的配置文件中。

Markdown 扩展

除了VS Code提供的开箱即用功能外，您还可以安装扩展以获得更多功能。

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

下一步

继续阅读以了解以下内容：

• CSS, SCSS, and Less - 想要编辑你的CSS吗？VS Code 对 CSS、SCSS 和 Less 编辑有很好的支持。

常见问题

是否有拼写检查？

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

VS Code 是否支持 GitHub 风格的 Markdown？

不，VS Code 使用 markdown-it 库来针对 CommonMark Markdown 规范。GitHub 正在向 CommonMark 规范靠拢，您可以在这篇 更新 中了解更多信息。