Markdown 和 Visual Studio Code

在 Visual Studio Code 中处理 Markdown 文件既简单又有趣。除了 VS Code 的基本编辑功能外，还有几个特定的 Markdown 功能可以帮助你提高生产力。

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

编辑Markdown

文档大纲

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

大纲视图是查看文档标题结构和大纲的绝佳方式。

Markdown片段

VS Code 包含一些有用的片段，可以加速编写 Markdown。这包括代码块、图像等的片段。按⌃Space（Windows, LinuxCtrl+Space）（触发建议）在编辑时可以看到建议的 Markdown 片段列表。你也可以通过在命令面板中选择插入片段来使用专用的片段选择器。

提示： 你可以为Markdown添加自己的用户自定义片段。请查看用户自定义片段以了解更多信息。

转到文件中的标题

使用⇧⌘O（Windows, LinuxCtrl+Shift+O）快速跳转到当前文件中的标题。

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

转到工作区中的标题

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

开始输入标题名称以筛选列表并找到您要查找的标题。

路径完成

路径补全有助于创建文件和图像的链接。这些路径会在您输入图像或链接的路径时自动显示IntelliSense，也可以通过使用⌃Space（Windows, LinuxCtrl+Space）手动请求。

路径以 开始输入：/相对于当前工作区根目录解析，而以 开头的路径./或不带任何前缀的路径将相对于当前文件解析。当您输入时，路径建议会自动显示输入：/ 或者可以使用 ⌃Space （Windows, Linux Ctrl+Space） 手动调用。

Path IntelliSense 也可以帮助你在当前文件或另一个 Markdown 文件内链接到头部。以 开始路径。# 查看文件中所有标头的完成建议（具体取决于您的设置，您可能需要使用 ⌃Space (Windows, Linux Ctrl+Space) 来看到这些)：

您可以禁用路径IntelliSense"markdown.suggest.paths.enabled": false输入：.

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

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

接受其中一个完成来插入到该头文件的完整链接，即使它在另一个文件中：

您可以使用以下配置来设置工作区标题完成的显示条件

• 双哈希（默认）—仅在您输入后显示工作区标题完成##输入：.
• 单哈希或双哈希—在您输入后显示工作区标题完成#或##输入：.
• 从不—从不显示工作区标题完成。

请记住，在当前工作区中查找所有标题可能会很昂贵，因此第一次请求时可能会有一些延迟，特别是对于包含大量Markdown文件的工作区。

插入图片和文件链接

除了路径完成，VS Code 还支持几种其他方式将图像和文件链接插入到你的 Markdown 文档中：

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

如果你更喜欢使用键盘，你也可以复制和粘贴文件或图像数据到一个Markdown编辑器中。当你粘贴一个文件、一个文件链接或一个URL时，你可以选择插入一个Markdown链接或包含链接作为纯文本。

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

插入的图像使用Markdown图像语法![](path/to/image.png). Links 插入一个普通的Markdown链接[](路径/至/文件.md)输入：.

默认情况下，VS Code 会自动将拖放到工作区之外的图像复制到你的工作区。

例如，如果你希望每个Markdown文件都低于/docs在您的工作区中将新媒体文件放入一个图像针对当前文件的目录，你可以写：

"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输入：.

为图像生成替代文本

您可以使用AI为Markdown文件中的图像生成或更新替代文本。要生成替代文本：

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

2. 打开一个Markdown文件。

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

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

   

5. 如果您已经有替代文本，请选择代码操作，并选择优化替代文本。

智能选择

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

智能选择使用以下命令：

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

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

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

链接验证

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

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

有一些设置可以用来定制链接验证：

• markdown.validate.fileLinks.enabled

  • 在 VS Code 中打开
  • 在 VS Code Insiders 中打开
  - 启用/禁用对本地文件链接的验证：[链接](/路径/到/文件.md)
• markdown.validate.fragmentLinks.enabled

  • 在 VS Code 中打开
  • 在 VS Code Insiders 中打开
  - 启用/禁用对当前文件中标题链接的验证：[链接](#_some-header)
• markdown.验证.文件链接.markdown片段链接

  • 在 VS Code 中打开
  • 在 VS Code Insiders 中打开
  - 启用/禁用验证链接到另一个 markdown 文件中的标题：[链接](其他文件.md#某个标题)
• markdown.validate.referenceLinks.enabled

  • 在 VS Code 中打开
  • 在 VS Code Insiders 中打开
  - 启用/禁用参考链接验证：[链接][参考]输入：.
• markdown.validate.ignoredLinks

  • 在 VS Code 中打开
  • 在 VS Code Insiders 中打开
   - 一个跳过验证的链接通配符列表。这在你链接到存在于Markdown发布后但在磁盘上不存在的文件时很有用。

查找所有引用标题和链接

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

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

• 标题:# 我的标题显示所有链接到#我的标题输入：.
• 外部链接:[文本](http://example.com)显示所有链接到http://example.com输入：.
• 内部链接：[text](./path/to/file.md)显示所有链接到./路径/至/文件.md
• 链接中的片段：[text](./path/to/file.md#my-header)显示所有链接到#我的标题在./路径/至/文件.md

重命名标题和链接

厌倦了在更改Markdown标题时意外打断链接？尝试使用重命名符号 (F2)。在你输入新的标题名称并按回车后，VS Code会更新标题并自动更新所有到该标题的链接：

你也可以使用 F2 在：

• 标题:# 我的标题. 这更新了所有链接到#我的标题输入：.
• 外部链接:[文本](http://example.com/page). 这更新了所有链接到 的地方http://example.com/page
• 内部链接：[text](./path/to/file.md). 这将重命名文件./路径/至/文件.md并更新所有到它的链接。
• 链接中的片段：[text](./path/to/file.md#my-header). 这将重命名标头./路径/至/文件.md并更新所有到它的链接。

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

通过自动Markdown链接更新，VS Code会在任何时候自动更新Markdown链接，如果链接到的文件被移动或重命名。你可以通过以下方式启用此功能

• 从不（默认） — 不要自动尝试更新链接。
• 提示— 更新链接前请确认。
• 总是— 自动更新链接，无需确认。

自动链接更新检测Markdown文件、图像和目录的重命名。你可以通过以下方式启用它来处理其他文件类型

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文档中。锁定的预览在标题中用[预览]表示：

注意： 只有在Markdown预览是活动标签时，Markdown: 切换预览锁定 命令才可用。

编辑器和预览同步

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

您可以使用以下选项禁用滚动同步

当前在编辑器中选中的行在Markdown预览中通过左 margin中的浅灰色条表示：

此外，双击Markdown预览中的一个元素将自动打开该文件的编辑器，并滚动到最接近所点击元素的行。

数学公式渲染

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

内联数学方程用单美元符号包裹：

内联数学: $x^2$

你可以用双美元符号来创建一个数学方程块：

数学块:

$$
\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。这些样式表可以是对不起，我无法访问特定的网页内容或链接。如果你能提供具体的文本内容，我可以帮助你进行翻译。URLs，或当前工作区中本地文件的相对路径。

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

// 将您的设置放在这个文件中以覆盖默认和用户设置。
{
  "markdown.styles": ["Style.css"]
}

保持 trailing 空格以创建换行符

为了创建硬性换行，Markdown要求在行尾留有两个或更多的空格。根据你的用户或工作区设置，VS Code可能会被配置为删除尾随空格。为了仅在Markdown文件中保留尾随空格，你可以向你的settings.json输入：:

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

Markdown 预览安全性

出于安全原因，VS Code 限制了在Markdown预览中显示的内容。这包括禁用脚本执行，并且只允许通过加载资源。对不起，我无法访问特定的网页内容或链接。如果你能提供具体的文本内容，我可以帮助你进行翻译。输入：.

当Markdown预览阻止页面上的内容时，预览Windows右上角会显示一个警报弹出Windows：

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

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

以下是每个安全级别的详细信息：

严格

这是默认设置。仅加载受信任的内容并禁用脚本执行。阻止对不起，我无法处理你提供的内容。图像。

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

允许不安全的内容

保持脚本禁用，但允许内容加载对不起，我无法处理你提供的内容。输入：.

禁用

禁用预览Windows中的附加安全功能。这允许脚本执行，并允许内容通过加载对不起，我无法处理你提供的内容。输入：.

文档撰写者个人资料模板

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

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

一旦你选择了一个配置文件模板，你就可以查看设置和扩展，并且如果你不希望将某些项目包含在新的配置文件中，可以移除单独的项目。在基于模板创建新的配置文件后，对设置、扩展或用户界面所做的更改将持久化到你的配置文件中。

Markdown 扩展

除了 VS Code 提供的基本功能之外，您可以通过安装扩展来获得更多的功能。

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

下一步

继续阅读，了解：

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

常见问题

是否有拼写检查？

没有与 VS Code 一起安装，但有拼写检查扩展。查看 VS Code 市场 以寻找有用的扩展来帮助您的工作流程。

VS Code 支持 GitHub 风格的 Markdown 吗？

不，VS Code 使用 CommonMark Markdown 规范，通过 markdown-it 库。GitHub 正在向 CommonMark 规范靠拢，你可以在这个 更新 中阅读到。