适用于 Visual Studio Code 的 Learn 创作包

Learn 创作包是 Visual Studio Code 扩展集合，用于辅助 Microsoft Learn content 的 Markdown 创作。 此包可在 VS Code Marketplace 中获得，包含以下扩展：

• Learn Markdown：为 Microsoft Learn 上的内容提供 Markdown 创作帮助，包括对基本 Markdown 语法以及自定义 Markdown 语法（如警报、代码片段和不可本地化文本）的支持。 现在还包括一些基本 YAML 创作帮助，例如插入 TOC 条目。
• markdownlint：David Anson 推出的一种非常受欢迎的 Markdown Linter，可帮助确保 Markdown 有效。
• 代码拼写检查器：Street Side Software 推出的完全脱机的拼写检查器。
• Learn 预览：使用 Microsoft Learn CSS 进行更准确的 Markdown 预览，包括自定义 Markdown。
• Learn 文章模板：使用户能够搭建 Learn 模块基架并将 Markdown 框架内容应用于新文件。
• Learn YAML：提供 YAML 架构验证和自动补全。
• Learn 图像：提供图像压缩以及重新调整文件夹和单个文件大小的功能，为 Microsoft Learn 内容的作者提供帮助。

前提条件和假设

要使用 Learn Markdown 扩展插入相关链接、图像和其他嵌入内容，须将 VS Code 工作区的范围限定于所克隆的公开发布系统 (OPS) 存储库的根路径。 例如，如果已将文档存储库克隆到 C:\git\SomeDocsRepo\，请在 VS Code 中打开该文件夹或子文件夹：选择“文件”>“打开文件夹”菜单，或者从命令行使用 code C:\git\SomeDocsRepo\。

扩展支持的一些语法（如警报和片段）是 OPS 的自定义 Markdown。 除非已通过 OPS 发布，否则将无法正确呈现自定义 Markdown。

如何使用 Learn Markdown 扩展

要访问“Learn Markdown”菜单，请键入 Alt+M。 可单击或使用上下箭头来选择所需的命令。 或者，可键入内容以开始筛选，然后当你所需的功能在菜单中突出显示时按 Enter。

请参阅“Learn Markdown 自述文件”以获取最新的命令列表。

如何生成主重定向文件

Learn Markdown 扩展包括一个脚本，用于基于单个文件中的 redirect_url 元数据生成或更新存储库的主重定向文件。 此脚本可检查存储库中每个 Markdown 文件是否具有 redirect_url、将重定向元数据添加到存储库的主重定向文件 (.openpublishing.redirection.json)，还可将已重定向的文件移至存储库以外的文件夹。 若要运行该脚本，请执行以下操作：

1. 选择 F1 打开 VS Code 命令面板。
2. 开始键入“Learn: Generate...”
3. 选择命令 Learn: Generate main redirection file。
4. 该脚本完成运行后，重定向结果将显示在 VS Code 输出窗格中，并且已删除的 Markdown 文件将添加到默认路径下的 Learn Authoring\redirects 文件夹中。
5. 查看结果。 如果结果与预期一样，请提交拉取请求以更新存储库。

如何分配键盘快捷方式

1. 依次键入 Ctrl+K 和 Ctrl+S，打开“键盘快捷方式列表”。

2. 搜索要创建自定义键绑定的命令，例如 formatBold。

3. 鼠标悬停在该行上时，单击命令名称旁边出现的加号。

4. 在显示新的输入框后，键入想要绑定到特定命令的键盘快捷方式。 例如，要将常见快捷方式用于加粗操作，则键入 Ctrl+B。

5. 在键绑定中插入 when 子句是个不错的主意，这样便无法在 Markdown 以外的文件中使用该快捷方式。 为此，请打开 keybindings.json，在命令名称下方插入以下行（请确保在行之间添加逗号）：

   "when": "editorTextFocus && editorLangId == 'markdown'"
   

   自定义键绑定完成后，在 keybindings.json 中看起来应如下所示：

   [
       {
           "key": "ctrl+b",
           "command": "formatBold",
           "when": "editorTextFocus && editorLangId == 'markdown'"
       }
   ]
   

   提示

   将键绑定放在此文件中以覆盖默认值

6. 保存 keybindings.json。

有关键绑定的详细信息，请参阅 VS Code 文档。

如何显示旧的“Gauntlet”工具栏

名为“Gauntlet”的扩展代码的前用户会注意到，安装 Learn Markdown 扩展时，在 VS Code 窗口的底部不再显示创作工具栏。 这是因为工具栏占据了 VS Code 状态栏的大量空间，而且未遵循扩展 UX 的最佳做法，因此在新扩展中被弃用。 但是，可以通过更新 VS Code settings.json 文件来选择性地显示工具栏，如下所示：

1. 在 VS Code 中，转到“文件”>“首选项”>“设置”，或者选择 Ctrl+,。

2. 选择“用户设置”，更改所有 VS Code 工作区的设置，或选择“工作区设置”，更改当前工作区的相关设置。

3. 选择“扩展”>“Learn Markdown 扩展配置”，然后选择“在底部状态栏中显示旧工具栏”。

   

做出选择后，VS Code 会更新 settings.json 文件。 系统将提示你重新加载窗口，以使更改生效。

添加到扩展的更新的命令在工具栏中不可用。

如何使用 Learn 模板。

使用 Learn 文章模板扩展，VS Code 中的编写者可以从集中存储中提取 Markdown 模板并将其应用到文件。 模板可帮助确保文章中包含所需的元数据、遵循内容标准等。 在公共 GitHub 存储库中，模板作为 Markdown 文件进行管理。

在 VS Code 中应用模板

1. 请确保已安装和启用 Learn 文章模板扩展。
2. 如果没有安装 Learn Markdown 扩展，请单击 F1 打开命令面板，开始键入“template”进行筛选，然后单击 Learn: Template。 如果安装了 Learn Markdown，则可以使用命令面板，也可以单击 Alt+M 以显示 Learn Markdown QuickPick 菜单，然后从列表中选择 Template。
3. 从显示的列表中选择所需的模板。

将 GitHub ID 和/或 Microsoft 别名添加到 VS Code 设置中

Templates 扩展支持三个动态元数据字段：author、ms.author 和 ms.date。 这意味着，如果模板创建者在 Markdown 模板的元数据标头中使用这些字段，则在应用模板时，它们将在你的文件中自动填充，如下所示：

元数据字段	值
author	你的 GitHub 别名（如果在 VS Code 设置文件中指定）。
ms.author	你的 Microsoft 别名（如果在 VS Code 设置文件中指定）。 如果你不是 Microsoft 员工，请不要指定该字段。
ms.date	当前日期支持的格式，MM/DD/YYYY。 如果之后更新文件，则不会自动更新日期 - 必须手动更新。 此字段用于表示“文章新鲜度”。

设置 author 和/或 ms.author

1. 在 VS Code 中，转到“文件”>“首选项”>“设置”，或者选择 Ctrl+,。
2. 选择“用户设置”，更改所有 VS Code 工作区的设置，或选择“工作区设置”，更改当前工作区的相关设置。
3. 在左侧的“默认设置”窗格中，找到“Learn 文章模板扩展配置”，单击所需设置旁边的铅笔图标，然后单击“设置”中的“替换”。
4. “用户设置”窗格将并排打开，底部附带一个新条目。
5. 根据需要，添加 GitHub ID 或 Microsoft 电子邮件别名，然后保存该文件。
6. 可能需要关闭并重启 VS Code 才能使更改生效。
7. 现在，在应用使用动态字段的模板时，你的 GitHub ID 和/或 Microsoft 别名自动填充到元数据标头中。

生成可在 VS Code 中使用的新模板

1. 将模板起草为 Markdown 文件。
2. 将拉取请求提交到 MicrosoftDocs/content-templates 存储库的模板文件夹中。

内容团队会查看你的模板，并在该模板符合风格指南的情况下合并 PR。 合并后，该模板将可供 Learn 文章模板扩展的所有用户使用。

演示多种功能

下面是一个简短的视频，演示了 Learn 创作包的以下功能：

• YAML 文件
  • 支持“Learn: 链接到存储库中的文件”
• Markdown 文件
  • 更新“ms.date”元数据值上下文菜单选项
  • 代码自动完成支持代码隔离语言标识符
  • 无法识别的代码隔离语言标识符警告/自动更正支持
  • 按升序对所选内容进行排序（A 到 Z）
  • 按降序对所选内容进行排序（Z 到 A）

后续步骤

了解 Learn 创作包 Visual Studio Code 扩展中可用的各种功能。

• 开发语言完成
• 图像压缩
• 元数据更新
• 重新设置表格式
• 智能引号替换
• 排序重定向
• 排序所选内容