使用 GitHub Codespaces 做出贡献

GitHub 有一个名为 Codespaces 的功能，您可以使用它来编写 PowerShell 文档，而无需在本地安装或配置任何软件。当您使用代码空间时，您将获得团队用于编写和编辑的相同创作工具。

您可以在浏览器中使用代码空间，在通过 Internet 托管的 VS Code 中做出贡献。如果您本地安装了 VS Code，您也可以连接到那里的代码空间。

可用工具

当您使用代码空间来编写 PowerShell 文档时，您的编辑器已经为您提供了以下工具：

• Markdownlint 用于检查 Markdown 语法。
• cSpell 用于检查拼写。
• 淡水河谷检查你的散文。
• 用于插入特定于平台的语法、预览您的贡献等的学习创作包。
• Reflow Markdown 扩展可根据需要包装 Markdown，使阅读和编辑更加轻松。
• 表格式化程序扩展使您的表格更具可读性，而无需手动对齐列。
• 用于转换标题和散文大小写的更改大小写扩展。
• 用于查看历史文件更改的 GitLens 扩展。
• 用于交互创作 PowerShell 示例的 PowerShell 扩展。
• Visual Studio Code 的 Gremlins 跟踪器用于查找 Markdown 中的有问题的字符。

成本

GitHub Codespaces 每月可免费使用最多 120 个核心小时。根据我们在本文中推荐的配置，这意味着每月最多可免费使用 60 小时。每月使用量是在所有存储库中计算的，而不仅仅是文档。

有关定价的更多信息，请参阅关于 GitHub Codespaces 的计费。

有用的提示

如果您习惯使用容器和 Docker，则可以通过使用为 PowerShell 文档存储库定义的 devcontainer 获得与在 VS Code 中使用 GitHub Codespaces 相同的体验。使用开发容器没有任何成本。有关更多信息，请参阅开发容器教程。

创建您的 GitHub 代码空间

要创建 GitHub Codespace 来贡献 PowerShell 文档，请按照以下步骤操作：

1. 在浏览器中打开 https://github.com/codespaces。
2. 选择页面右上角的“新建代码空间”按钮。
3. 在“创建新代码空间”页面中，选择“选择存储库”按钮，然后键入要贡献的存储库的名称，例如 MicrosoftDocs/PowerShell-Docs。
4. 将所有其他设置保留为默认值。
5. 选择“创建代码空间”按钮。

执行这些步骤后，GitHub 会为该存储库创建一个新的代码空间并为您进行设置。当代码空间准备就绪时，页面将刷新并显示代码空间的 Web 编辑器 UI。 UI 基于 VS Code，工作方式相同。

打开您的 GitHub 代码空间

要在浏览器中打开 GitHub Codespace，请按照以下步骤操作：

1. 在浏览器中打开 https://github.com/codespaces。
2. 该页面列出了您的代码空间。找到为您想要贡献的存储库创建的代码空间并选择它。

选择代码空间后，GitHub 将在同一窗口中打开它。从这里开始，您就可以做出贡献了。

要在 VS Code 中打开 GitHub Codespace，请按照在 Visual Studio Code 中使用 GitHub Codespace 中的步骤操作。

在 GitHub Codespace 中创作

在浏览器或 VS Code 中打开 GitHub Codespace 后，对文档的贡献将遵循相同的流程。

本文的其余部分介绍了您在编写或编辑贡献时可以在 GitHub Codespace 中执行的一系列任务。

提取参考链接

当您想要将内联链接（例如 [some text](destination.md)）转换为参考链接（例如 [some text][01]）时，请选择该链接编辑器中的目的地。然后您可以：

1. 右键单击链接目标并在上下文菜单中选择“重构...”。
2. 按Ctrl+Shift+R。

任一操作都会引发重构上下文菜单。在上下文菜单中选择“提取到链接定义”。这会将链接中的 (destination.md) 替换为 [def]。您可以通过键入名称来重命名定义。

对于 PowerShell 文档，我们使用两位数字参考链接定义，例如 [01] 或 [31]。仅在有关主题和概念文档中使用参考链接定义。不要在 cmdlet 参考文档中使用参考链接定义。

修复散文风格违规问题

当您在代码空间中查看文章时，Vale 会在您首次打开文章以及每次保存文章时自动检查该文章。如果 Vale 发现任何样式违规，它会在文档中用彩色曲线突出显示它们。

将鼠标悬停在违规行为上可查看有关它的更多信息。

在悬停信息中选择规则名称以打开解释该规则的网页。选择规则的文件名（以 .yml 结尾）以打开规则并查看其实施情况。

如果规则支持快速修复，您可以在违规的悬停信息中选择“快速修复...”，然后从上下文菜单中选择建议的修复之一来应用它。当光标位于突出显示的问题上时，您还可以按 Ctrl+. 以应用快速修复（如果规则支持）。

如果规则不支持快速修复，请阅读规则的消息并修复它（如果可以）。如果您不确定如何修复它，编辑可以在审核您的 PR 时提出建议。

修复语法问题

当您在代码空间中查看文章时，Markdownlint 会在您打开文章并在您键入时自动检查该文章。如果 Markdownlint 发现任何语法问题，它会在文档中用彩色曲线突出显示它们。

将鼠标悬停在违规行为上可查看有关它的更多信息。

在悬停信息中选择规则的 ID 以打开解释该规则的网页。

如果规则支持快速修复，您可以在违规的悬停信息中选择“快速修复...”，然后从上下文菜单中选择建议的修复之一来应用它。当光标位于突出显示的问题上时，您还可以按 Ctrl+. 以应用快速修复（如果规则支持）。

如果规则不支持快速修复，请阅读规则的消息并修复它（如果可以）。如果您不确定如何修复它，编辑可以在审核您的 PR 时提出建议。

您还可以对文章中的所有语法违规应用修复。为此，请打开命令选项板并输入修复文档中所有支持的 markdownlint 违规。当您键入时，命令选项板会过滤可用的命令。选择“修复文档中所有支持的 markdownlint 违规行为”命令。当您这样做时，Markdownlint 会更新文档以解决它可以快速修复的任何违规行为。

设置表格格式

要格式化 Markdown 表格，请将光标放在 Markdown 中的表格中或表格上。打开命令面板并搜索Table: Format Current命令。当您选择该命令时，它会更新表格的 Markdown，以对齐和填充表格以提高可读性。

它转换如下定义的表：

| foo | bar | baz |
|:--:|:--|-:|
| a | b | c |

进入这个：

|  foo  | bar  | baz  |
| :---: | :--- | ---: |
|   a   | b    |    c |

插入提醒

该文档使用警报来使信息更容易被读者注意到。

要插入警报，您可以打开命令面板并搜索学习：警报命令。当您选择该命令时，它会打开一个上下文菜单。选择您要添加的警报类型。当您执行此操作时，该命令会在文档中的光标处插入警报的 Markdown。

使用句子大小写作为标题

要转换标题的大小写，请突出显示标题的文本（前导 # 符号除外，这些符号设置标题级别）。突出显示文本后，打开命令面板并搜索更改大小写句子 命令。当您选择该命令时，它会转换突出显示文本的大小写。

您还可以对文档中的任何文本使用大小写命令。

打开命令面板

您可以使用 VS Code 的命令面板来运行许多有用的命令。

要在用户界面中打开命令面板，请选择顶部菜单栏中的“查看”。然后在上下文菜单中选择“命令面板...”。

要使用键盘打开命令面板，请按适用于您的操作系统的组合键：

• Windows 和 Linux：Ctrl+Shift+P
• macOS：Cmd+Shift+P

预览您的贡献

要预览您的贡献，请打开命令面板并搜索 Markdown: Open Preview 命令。当您选择该命令时，VS Code 将打开活动文档的预览。预览的风格与 Learn 平台相匹配。

笔记

站点相关链接和交叉引用链接在预览中不起作用。

重排您的内容

要限制文档中段落的行长度，请将光标放在该段落上。然后打开命令面板并搜索 Reflow Markdown 命令。当您选择该命令时，它会将当前段落的行长度更新为配置的长度。对于我们的存储库，该长度为 99 个字符。

将此命令用于块引用时，请确保要重排的块引用中的段落被空行包围。否则，该命令会将每个段落重新排列在一起。

警告

编辑主题时请勿使用此命令。这些文档中的行不得超过 80 个字符。目前，存储库无法按文件夹或文件名配置不同的行长度，因此重排不适用于主题文档。

检查文档中的所有问题

要查看文档中的所有语法和样式规则违规情况，请打开问题视图。

要在 UI 中打开问题视图，请选择顶部菜单栏中的“查看”。然后在上下文菜单中选择“问题”。

要使用键盘打开问题视图，请按操作系统的组合键：

• Windows 和 Linux：Ctrl+Shift+M
• macOS：Cmd+Shift+M

问题视图显示打开文档的所有错误、警告和建议。选择一个问题以在文档中滚动到该问题。

您可以按类型或文本匹配来过滤问题。

更新 ms.date 元数据

要更新文章的 ms.date 元数据，请打开命令面板并搜索学习：更新“ms.date”元数据值 命令。当您选择该命令时，它将元数据更新为当前日期。

其他资源

本文中描述的任务和命令并未涵盖您可以使用 VS Code 或已安装的扩展执行的所有操作。

有关使用 VS Code 的更多信息，请参阅以下文章：

• Visual Studio 代码提示和技巧
• 基础编辑
• 在 VS Code 中使用 Git 源代码管理
• Markdown 和 Visual Studio 代码

有关已安装扩展的更多信息，请参阅其文档：

• 改变大小写
• GitLens
• Visual Studio Code 的 Gremlins 跟踪器
• 学习创作包
• 降价林特
• 回流降价
• 表格格式化程序