Markdown 和 Visual Studio 代码

在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）快速跳转到当前文件中的页首。

你可以浏览文件中的所有头部，或者开始输入头部名，找到你想要的那个。找到页眉后，按回车键将光标移动到那里。按Esc键取消跳转到头部。

在工作区中返回页眉

使用 ⌘T（Windows，Linux Ctrl+T）来搜索当前工作区中所有 Markdown 文件的头部。

开始输入一个头部名称，筛选列表，找到你想要的头部。

路径补全

路径补全有助于创建文件和图片的链接。这些路径会由IntelliSense自动显示，当你输入图片或链接的路径时，也可以手动请求使用⌃Space（Windows，Linux Ctrl+Space）。

以 为起点的路径相对于当前工作区根节点解析，而以 为 的路径则是/./或没有任何前缀，相对于当前文件解析。路径建议在你输入时会自动显示，或者可以通过使用⌃Space（Windows，Linux的Ctrl+Space）手动调用。/

Path IntelliSense 还可以帮助你链接当前文件中的头部或另一个 Markdown 文件中的标记。从路径开始，可以看到文件中所有头部的完成（根据你的设置，可能需要用⌃空格（Windows，Linux Ctrl+Space）来查看）：#

你可以用“markdown.suggest.paths.enabled”： false.

创建指向另一个文件头部的链接

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

接受以下补全之一以插入该头部的完整链接，即使它在另一个文件中：

你可以在工作区头完成显示时设置

• 在DoubleHash上（默认）——仅在输入 后显示工作区头部完成。##
• 在SingleOrDoubleHash上—— 在输入后显示工作区头部补全。###
• 绝不——永远不要显示工作区头的完成。

请记住，查找当前工作区中所有头部可能很昂贵，所以第一次请求时可能会有轻微延迟，尤其是对于包含大量 Markdown 文件的工作区。

插入图片和文件链接

除了路径补全外，VS Code 还支持几种其他方式将图片和文件链接插入你的 Markdown 文档中：

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

如果你喜欢用键盘，也可以把文件或图片数据复制粘贴到Markdown编辑器里。当你粘贴文件、文件链接或网址时，可以选择插入Markdown链接，或将链接作为纯文本包含。

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

插入的图片使用Markdown图像语法![]（路径/去/image.png）.链接插入普通的Markdown链接[]（path/to/file.md）.

默认情况下，VS Code 会自动将工作区外的放置或粘贴图片复制到你的工作区。该

例如，如果你想让每个Markdown文件都被/文档在你的工作区中，将新的媒体文件放入图片当前文件的专用目录，你可以写：

"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”： true.VS Code 随后分析指向头部、图片及其他本地文件的 Markdown 链接。无效链接会被报告为警告或错误。所有链接验证均在本地进行，且不检查外部 http（s）链接。

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

• markdown.validate.fileLinks.enabled

  • 在VS代码中打开
  • 在VS Code Insiders中开放
  - 启用/禁用本地文件链接验证：[链接]（/path/to/file.md）
• markdown.validate.fragmentLinks.enabled

  • 在VS代码中打开
  • 在VS Code Insiders中开放
  - 启用/禁用当前文件中指向头部的链接验证：[链接]（#_some头）
• markdown.validate.fileLinks.markdownFragmentLinks

  • 在VS代码中打开
  • 在VS Code Insiders中开放
  - 启用/禁用对其他标记文件中头部链接的验证：[链接]（other-file.md#some-头部）
• markdown.validate.referenceLinks.enabled

  • 在VS代码中打开
  • 在VS Code Insiders中开放
  - 启用/禁用引用链接验证：[链接][参考资料].
• markdown.validate.ignoredLinks

  • 在VS代码中打开
  • 在VS Code Insiders中开放
  - 跳过验证的链接块列表。如果你链接到磁盘上不存在但发布后仍然存在的文件，这很有用。

查找所有对头部和链接的引用

使用“查找所有引用”（⇧⌥F12（Windows，Linux Shift+Alt+F12））命令，查找当前工作区中所有引用 Markdown 头或链接的位置：

查找所有参考文献支持：

• 标题：# 我的头条.显示所有链接#my 头.
• 外部链接：[正文]（http://example.com）.显示所有链接http://example.com.
• 内部链接：[正文]（./path/to/file.md）.显示所有链接./path/to/file.md
• 链接中的片段：[正文]（./path/to/file.md#my-header）.显示所有链接#my 头在./path/to/file.md

重命名头部和链接

厌倦了更改Markdown头时不小心导致链接断裂？试试用重命名符号（F2）。输入新头部名称并按回车后，VS Code 会更新头部并自动更新该头部的所有链接：

你也可以在以下情况下使用F2：

• 标题：# 我的头条.此更新更新了所有链接至#my 头.
• 外部链接：[正文]（http://example.com/page）.这更新了所有链接到的网站http://example.com/page
• 内部链接：[正文]（./path/to/file.md）.这会重新命名文件./path/to/file.md并且会更新所有相关链接。
• 链接中的片段：[正文]（./path/to/file.md#my-header）.这会重新命名./path/to/file.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预览中，当前选择的行由左边框的浅灰色条表示：

此外，在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。这些样式表可以是httpsURL，或当前工作区中本地文件的相对路径。

例如，加载一个名为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 预览的安全设置会应用到工作区内的所有文件。

以下是这些安全级别的详细信息：

严格

这是默认设置。只加载可信内容并禁用脚本执行。方块http图片。

我们建议你保持严格启用了安全，除非你有非常充分的理由去更改，并且你信任工作区里所有的Markdown文件。

允许不安全内容

它会禁用脚本，但允许内容加载http.

停用

在预览窗口中禁用额外安全性。这允许脚本执行，同时也允许内容加载http.

Doc Writer 个人资料模板

配置文件可以让你根据当前项目或任务快速切换扩展、设置和界面布局。为了帮助你开始编辑Markdown，可以使用Doc Writer配置文件模板，这是一个经过精心策划的配置文件，带有实用的扩展和设置。你可以直接使用配置文件模板，也可以作为起点，进一步定制自己的工作流程。

你可以通过个人资料>创建个人资料......下拉菜单选择模板：

一旦你选择了个人资料模板，就可以查看设置和扩展，如果你不想把单个项目包含在新个人资料中，可以移除它们。创建基于模板的新配置文件后，设置、扩展或界面的更改会保留在你的配置文件中。

Markdown 扩展

除了VS Code开箱即用的功能外，你还可以安装扩展以增强功能。

提示：选择一个扩展图块阅读描述和评价，决定哪个扩展最适合你。更多内容请见市场。

下一步

继续阅读，了解：

• CSS、SCSS及更少——想编辑你的CSS？VS Code 对 CSS、SCSS 和 Less 编辑支持非常出色。

常见问题

有拼写检查吗？

虽然没有用VS Code安装，但有拼写检查扩展。可以查看VS Code市场，寻找有助于你工作流程的实用扩展。

VS Code 支持 GitHub 风格的 Markdown 吗？

不，VS Code 是通过 markdown-it 库针对 CommonMark Markdown 规范。GitHub正在向CommonMark规范发展，你可以在本次更新中阅读相关内容。