风格指南_GitHub中文网

备注： 这些准则特定于 GitHub 的文档。有关此处未涵盖的主题的一般风格问题或指导，请参阅 Microsoft 风格指南。有关特定于 docs.github.com 上的源内容的标记，请参阅“在 GitHub Docs 中使用 Markdown 和 Liquid”。有关 GitHub 品牌的任何问题，请参阅“GitHub 品牌指南”。

GitHub Docs 风格方法

我们的风格指南旨在简单明了。相关准则应易于应用于一系列场景。
我们的目的不是帮助客户根据语法规则或风格指南来决定什么是对的或什么是错的，而是要找出什么最适合他们。我们并非一成不变，愿意在保持一致性的前提下进行合理的更改。
为了在团队和文档集发展的过程中扩展风格指南，并创建为用户提供服务的高质量、有意义内容，我们将注意力集中在影响力大的高价值场景上，而不是尝试全面涵盖每个风格问题。
一致性和语法正确性很重要，但不如清晰度和意义那么重要。
在决定风格或结构时，我们会考虑内容单元内的信息流和信息的上下文。
当风格指南未涵盖帮助文档特定的问题时，我们会遵循这些原则进行思考，然后做出决定。如果审阅者询问，我们随时准备好讨论决定。

审核日志事件

我们将记录每种类型帐户的审核日志中可能出现的每个事件：用户、组织和企业。

"安全日志事件"
"组织的审核日志事件"
GitHub Enterprise Cloud 文档中的“企业的审核日志事件”

编写审核日志事件的说明时，使用过去的时态和被动语态，以适用于所有版本的方式描述发生的事件。不要在句子开头使用文章上下文中已暗示的短语，例如“触发条件”。

使用：已更改存储库的可见性。
使用：已为所有新存储库启用机密扫描。
避免使用：组织所有者禁用了组织的双因素身份验证要求。
避免使用：在用户更新 codespace 可以访问的存储库时触发。

标注

标注突出显示客户需要知道的重要信息。我们对文档集中不同类型的标注使用标准格式和颜色。

对于高价值信息，请谨慎使用标注 - 不要在标注中包含一般信息、权限或先决条件。不要在标注中包含超过两个项目符号点。

内容内标注有三种类型：备注、警告和危险通知。

标注格式设置

每个标注都以指示标注类型的文本开头（例如警告： ），以引导读者（无论是目视访问站点还是使用屏幕阅读器访问）并帮助每个用户衡量标注中信息的重要性和必要性。

备注以蓝色 {% note %} 标记呈现。

备注为用户提供有用的信息或提醒，但不需要遵循这些信息。备注可能与每个用户无关或没有必要。
请在备注内容前面加上 **Note:**。

警告和危险通知以红色 {% warning %} 标记呈现。

警告是用户在继续执行任务之前应注意的潜在危险操作。它们通常是非可选步骤。
- 请在危险通知内容前面加上 **Warning:**。
危险通知是用户在执行之前应格外小心的危险操作。它们通常涉及数据丢失或其他破坏性操作的可能性。
- 请在危险通知内容前面加上 **Danger:**。

有关设置标注格式的详细信息，请参阅“在 GitHub Docs 中使用 Markdown 和 Liquid”中的“标注”。

按钮

登陆页面和某些文章中有一些按钮，用于将用户带到其他文章或其他 GitHub 网页上的相关内容。如果用户需要导航到另一个页面以完成所描述的任务时，应使用这些按钮。例如，“设置 GitHub Enterprise Cloud 试用版”有一个按钮，用于将用户带到试用版注册页面，因为这是设置试用版过程中的下一步。 “迁移文档”登陆页面使用一个按钮来将用户带到大多数人开始迁移都需要阅读的一篇文章。

如果一个按钮建议用户退出 GitHub Docs 站点，请按照行为召唤 (CTA) 按钮准则进行操作。如果要在登陆页面或文章中包含其他类型的按钮，请在 docs-strategy 存储库中创建一个问题，分享你的用例，让内容策略团队审批。

行为召唤 (CTA) 按钮

CTA 按钮强调一个链接，我们希望或建议用户在阅读文章后或在完成文章所描述任务的过程中导航到该链接。 CCA 应仅将用户带到 GitHub 拥有的域。例如，“开始使用 GitHub Copilot”中的 CTA 链接到 GitHub.com 上的 GitHub Copilot 设置菜单。

仅当导航到链接支持用户需求时，才包含 CTA 按钮。请勿仅将 CTA 按钮用于营销 GitHub 功能或产品。在上面的示例中，想要试用 GitHub Copilot 的用户必须导航到 Copilot 设置菜单，并且在阅读本文后可能需要这样做。相反，即使用户在编写代码随后创建拉取请求的过程中可能使用 Copilot，但我们不会将“试用 GitHub Copilot”CTA 添加到“创建拉取请求”，因为 Copilot 与“创建拉取请求”的用户需求无关。大多数用户会在不使用 Copilot 的情况下创建拉取请求。但是，访问 Copilot 入门文章的用户可能有兴趣试用 Copilot（如果他们尚未使用）。因此，我们添加了 CTA 按钮，来帮助用户到达所需的位置。

请按照以下格式设置 CCA 的样式。

<a href="https://github.com/DESTINATION/URL" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"><span>Try PRODUCT NAME</span> {% octicon "link-external" height:16 %}</a>

代码

代码块

将代码示例中的行保持在 60 个字符左右，以避免要求读者在代码块中水平滚动。在代码块之前找到说明性文本，而不是在代码块中使用注释。有关代码块的语法和格式的详细信息，请参阅“在 GitHub Docs 中使用 Markdown 和 Liquid”。

在代码块中：

在第一个代码围栏之后指定示例的语言。有关所有受支持语言的列表，请参阅 github/docs 存储库中的“代码语言”。
不要使用 HTML 为代码块设置样式或标记。
为用户在全大写中以自己的值进行替换的任何占位符设置样式。
- 使用：git checkout -b BRANCH-NAME****
- 避免： git checkout -b <branch-name>
仅当在同一个块中显示命令的输出时，才在命令本身之前使用 $。
- 如果显示命令和命令的输出，请将代码块设置为不可复制。
如果代码示例包含应呈现的 { 或 }，请将该节放在 {% raw %} {% endraw %} 中以禁用该节的 Liquid 处理。
- 使用：
```
GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
```
- 避免：
```
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
如果代码示例包含应分析的内容，则请将该节放在 <pre> </pre> 标记中以分析而不是转义节中的内容。

命令

使用内联代码块引用短命令名称。

使用： 若要检查正在运行的群集的状态，请使用 ghe-cluster-status 命令。

将命令块用于更长或更复杂的命令。

使用： 通过连接到任何群集节点的管理 shell 并运行以下命令，根据计划的窗口启用维护模式：
```
ghe-cluster-maintenance -s
```

避免在命令名称中使用内联链接。

示例

当代码示例引用较大的文件时，显示文件的相关节，以便用户了解如何在上下文中编辑自己的代码。

使用：

on:
  schedule:
    - cron:  "40 19 * * *"

避免：

schedule:
  - cron:  "40 19 * * *"

文件名和目录名

使用反引号设置对文件名和目录名的引用的格式，使其以固定宽度字体显示。如果文件类型通常遵循特定的大写约定（如 README 文件的所有大写字母），请使用既定约定。

使用： 在 README.md 文件中，添加有关存储库的信息。
使用： 在 .github/workflows/ 目录中，创建 example-workflow.yml 文件。
避免： 在 .github/workflows/ 目录中，创建 example-workflow.yml 文件。
避免： 删除 example.js 文件。

缩进

在 YAML 示例中（如操作和工作流文件），使用两个空格来缩进嵌套列表和块序列中的行。

使用：

    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python }}

若要缩进可重用代码，请参阅 data/reusables/README.md。

计划工作流

当一次运行的工作流过多时，工作流运行会延迟。由于许多用户从 GitHub Docs 复制代码，因此我们应该使用示例来引导用户避开拥堵时间。

请勿使用整点运行的示例。（Actions 团队报告说，整点时间，尤其是 UTC 午夜，不成比例地过载。）
请勿使用运行频率超过必要的示例。例如，请勿每 5 分钟运行一次，而是考虑每 30 分钟运行一次示例是否有意义。
请对每个示例使用不同的时间。

强调

请使用斜体来强调单词或句子的一部分。对于用户必须注意的术语或上下文，请谨慎使用强调，以成功完成他们正在处理的任务。请勿使用斜体来强调应用了其他格式的单词，例如占位符文本的所有大写字母或 UI 元素的粗体。

使用： 与 personal access tokens (classic)（经典版）相比， fine-grained personal access token 具有多项安全优势。
使用： 对于容器以外的包类型，请单击包版本右侧的删除。
避免： 在_标题_ 旁边，为新密钥添加描述性标签。

脚注

尽可能避免使用脚注。请改为考虑是否可以使用标注或以其他方式呈现信息。请参阅 NICE.org.uk 中的一些脚注替代方法示例。

如果必须使用脚注，请使用 Markdown 原生脚注 ([^1])。脚注标记将超链接到脚注引用，该引用将在页面底部列出，并带有指向该标记的反向链接。

请注意，无论使用的标识符（字母、单词）如何，脚注都将呈现为序列号。

	Mona	乌苏拉	Paul	戴维·琼斯¹
最喜欢的消遣	发送代码	欺骗美人鱼²	预测运动	纠缠海员
使用权力行善	是	否	是	否

| | Mona | Ursula | Paul | Davy Jones[^1] |
|---|---|---|---|---|
|Favorite pastime| Shipping code | Tricking mermaids[^2] | Predicting sports | Haunting seafarers |
|Uses powers for good| Yes | No | Yes | No |
[^1]: Not to be confused with Davy Jones of The Monkees
[^2]: Also humans

标头

标题必须充分描述其下的内容。遵循用于编写标题的相同准则。章节标题使用句首大写形式。页面上的每个页眉都必须是唯一的。

将 H2 用于标头，将 H3 用于子标题。如果文章有标题，则标题必须以 H2 级别标题开头，并且不能跳过标题级别。标题和子标题之间必须有内容，例如简介。引用标题时，请用引号将标题名称引起来。

使用： 在“用户许可证”下，查看许可证总数。

有关详细信息，请参阅“GitHub Docs 文章的内容”。

映像

我们在整个文档中使用静态图像（包括屏幕截图、示意图和图表）来补充文本信息。

请勿在文档中使用动画 GIF。

替换文本

每个图像都必须包含替换文本，提供视觉信息的文本等效项。

表达图像的核心思想或含义，而不是从字面上描述它。
请使用 40-150 个字符。
请以标点符号结尾。通常应该是一个句点，除非替换文本描述以其他标点（如问号或感叹号）结尾的文本图像。
请勿以“图像...”或“图形...”开头。屏幕阅读器会自动读出替换文本。
请以图形_类型_开始：“屏幕截图显示了...”或“示意图显示了...”
请遵循用于在文章文本中描述 UI 元素的标准语言。
将多字标题（如菜单项的名称）放在双引号（“”）中。在多字标题后使用标点符号时，请将其放在引号外，确保引号中的字符串与上下文中显示的标题完全匹配。
如果图像的某个区域在视觉上突出显示，请描述如何突出显示。这使屏幕阅读器用户能够从视觉语言的角度理解并向视力正常的朋友/同事描述要寻找的内容。

屏幕截图的替换文本

替换文本提供屏幕截图内容的简短说明，使看不到该内容的用户受益。

替换文本只需要包含图像最相关的元素，不用包含每个细节。
替换文本不用于提供有关使用 GitHub 界面的说明。这些应包含在随附的文章文本中。

格式

显示的 Product name + UI element 的屏幕截图。 UI element + state of the element/controls 及其 keyboard shortcut XYZ 都以深橙色框出。

对于 Product name，请使用 GitHub 产品或功能名称，例如“GitHub Actions”或“GitHub 存储库”，而不仅仅只使用“GitHub”。
像在运行复制时一样，对 GitHub 一词使用变量：{% data variables.product.prodname_dotcom %}
与书面文档一致地描述 UI 元素。
为了清楚起见，请灵活调整字序。
- 例如，写出“Visual Studio Code 中调试菜单的屏幕截图...”而不是“Visual Studio Code 调试菜单的屏幕截图...”，以避免一行中出现多个名词。

示例

按存储库表显示 GitHub 提交者的屏幕截图。水平烤肉串图标和“下载 CSV 报表”按钮以深橙色框出。

屏幕截图显示了 GitHub 存储库中的文件选项。标有“代码”且带有箭头（表示下拉菜单）的按钮以深橙色标出。

示意图和图表的替换文本

在页面上的文本中解释示意图或图表中传达的信息。

请使用替换文本来表达图像的核心思想，请勿复制网页文本。

示例

示意图显示了一个包含五个步骤的过程，通过该过程，GitHub Actions 运行器可以自动添加到命名的运行器类，然后由特定作业请求。

有关示例，请参阅在 Actions 文档中附上此关系图的说明。

命令行接口图像的替换文本

请勿使用命令行接口的屏幕截图来传达命令及其输出。而是直接提供用户应使用的命令。有关详细信息，请参阅风格指南的“命令”部分。

使用命令行接口的屏幕截图显示用户界面元素时，请遵循屏幕截图的标准替换文本准则。

图像的文件名

命名图像文件时要具有描述性：在文件名中包含名称、操作和 UI 元素。体现产品语言。使用烤肉串大小写。请勿在文件名中使用 Liquid 条件。如果替换图像，请使用确切的文件名。

使用：data-pack-purchase-button.png
避免： purchase_button.png
避免： purchase-button.png

屏幕截图

若要了解如何创建映像并进行版本控制，请参阅“创建和更新屏幕截图”。

图表

要了解如何创建关系图，请参阅“为 GitHub Docs 创建关系图”。

包容性语言

作为世界上最大的开发人员社区，GitHub 致力于在我们工作的各个方面促进多样性和包容性。我们所有的文档都包容和尊重受众，这些受众来自五湖四海，情况各不相同。编写文档时，我们使用包容、反种族主义和易于理解的单词。

单个单词可能很小，但它们可以共同创造社区、归属感和公平。在选用所有单词和风格时要善解人意。在提及人员和社区时要准确。

使用	避免
允许列表	白名单
拒绝列表	黑名单
默认/main 分支	master 分支

有关包容性语言的资源

Microsoft 风格指南提供了有关无偏差通信、辅助功能术语和适合所有能力写作的资源：

用于了解包容性和无障碍语言和风格的更多资源：

键盘快捷方式

若要呈现键盘快捷方式，请遵循 Microsoft 风格指南，但以下差异除外：

对每个单独的键使用 HTML <kbd> 标记。
- 使用： <kbd>Command</kbd>+<kbd>B</kbd>
- 避免： Command+B
对 Apple 修饰键使用全字而不是符号。
- 使用： Command
- 避免： ⌘
对特殊字符键使用符号，而不是全字。
- 使用： .、, 和 →。
- 避免： Period、Comma 和 Right arrow。

用法要点

以下是我们在文档中如何呈现键盘快捷方式的一些用法要点：

基本语法是在键组合之间使用 + 来显示键，不包含任何空格。
- 使用： <kbd>Command</kbd>+<kbd>B</kbd>，呈现为 Command+B。
- 避免： <kbd>Command</kbd> + <kbd>B</kbd> 或 <kbd>Command + B</kbd>，呈现为 Command + B 或 Command + B。
始终将常规引用和键盘快捷方式的字母键大写。
- 使用： Command+B
- 避免： Command+b。
对每个操作系统使用正确的修饰键。

备注： Windows 和 Linux 上已缩写为 Ctrl，而在 Mac 上则完整拼写为 Control。
- 对于 Windows 和 Linux：
  - 使用： Ctrl、Alt。
  - 避免： Control
- 对于 Mac：
  - 使用： Command、Option、Control。
  - 避免： Cmd、⌘、Opt、⌥、Ctrl、⌃
请勿混淆键组合和键序列。
- Command+B 指示用户应在按下 Command 键的同时按下 B 键。
- G I 指示用户应先按 G 键，再按 I 键。
描述多个操作系统的键盘快捷方式时，请将操作系统附加到快捷方式后面的括号中。首先描述 Mac 快捷方式，然后再描述 Windows/Linux。
- 使用： <kbd>Command</kbd>+<kbd>B</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows/Linux)，呈现为：
  
  Command+B (Mac) 或 Ctrl+B (Windows/Linux)
- 避免： <kbd>Ctrl</kbd>+<kbd>B</kbd> or <kbd>Command</kbd>+<kbd>B</kbd>，呈现为：
  
  Ctrl+B 或 Command+B

许可内容

GitHub Docs 根据 CC-BY 许可证进行许可。如果重复使用或修改文章中的许可内容，则必须确保许可证兼容且正确归属。

请勿为许可证归属创建可重复使用内容。我们必须使用许可项目所依据的确切许可证，因此必须准确地为它们出现在的文章编写任何归属。

如果不确定重复使用任何内容的合法性，请联系法律部门。如果添加的内容包含下面未列出的许可证，则必须先获得法律评审，然后才能发布内容。

归属 MIT 许可的内容

如果我们重复使用或修改 MIT 许可证下的内容，则必须在内容出现的位置注明 MIT 许可证。

在文章末尾包含 MIT 许可的内容

创建题为 Legal notice 的标题
归属内容来源以及内容依据 MIT 许可证进行许可。包含指向项目的链接
将要归属的项目的 MIT 许可证的全文粘贴到代码块中

MIT 许可证归属示例

此文本只是一个示例。请始终使用你要归属的项目的许可证文本。

## Legal notice

Portions have been adapted from [PROJECT](/LINK/TO/PROJECT) under the MIT license:

```
MIT License

Copyright YEAR COPYRIGHT-HOLDER

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```

换行符

对于纯文本，请使用换行符分隔源中的段落（两个连续的换行符），而不是在源中创建视觉空间。避免使用不必要的换行符，尤其是在列表中。

链接

请使用标准格式一致地引入链接，该格式清楚地指示我们要链接的位置。

对于指向另一个 GitHub Docs 页面的任何链接，请使用特殊关键字 AUTOTITLE。有关详细信息，请参阅内容标记参考。

用法示例：

对于指向其他页面的链接：For more information, see "[AUTOTITLE](/PATH/TO/PAGE)."
对于指向其他页面中各部分的链接：For more information, see "[AUTOTITLE](/PATH/TO/PAGE#SECTION-LINK)."
对于指向选择了工具的页面的链接：For more information, see the TOOLNAME documentation in "[AUTOTITLE](/PATH/TO/PAGE?tool=TOOLNAME)."

同页不同部分链接不适用于 AUTOTITLE。请改为键入完整标题文本：For more information, see "[HEADER-TITLE](#SECTION-LINK)."

有关指向外部文档的链接，请键入完整的文章名称：For more information, see [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE) in the XYZ documentation.

请勿在超链接中包含引号。

使用链接的一些最佳做法：

链接应该有意义，并且为用户旅程提供高价值，因此请谨慎链接。
请将有用但不必要的链接移动到文章的延伸阅读部分。
请勿在同一篇文章或同一 H2 标题下多次重复同一链接。
除非需要链接到 REST 文档的特定日历版本（这种情况很少见），否则请勿在 REST 链接中包含 apiVersion 查询参数。

为了便于访问和可读，请避免使用内联或句子中间链接。

使用： OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)" and "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)."
避免： Read [more about OAuth2.](/apps/building-integrations/setting-up-and-registering-oauth-apps/) Note that OAuth2 tokens can be [acquired programmatically](/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites.

有关链接和辅助功能的详细信息，请参阅可读性准则项目中的“链接”。

版本之间的链接

有时，需要从一个版本的 GitHub Docs 链接到另一个版本。如果要链接到_同一_页的其他版本，应使用 currentArticle 属性。

例如，“管理组织的 GitHub Pages 站点发布”的免费、专业和团队版本可能链接到同一文章的 GitHub Enterprise Cloud 版本，如下所示：

You can choose to allow or disallow the publication of GitHub Pages sites.

Organizations that use {% data variables.product.prodname_ghe_cloud %} can choose to allow publicly published sites, privately published sites, both, or neither. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/{{ currentArticle }}).

若要链接到其他版本的其他文章，请使用以下格式：

For more information, see "[ARTICLE TITLE](/)" in the VERSION documentation.

若要链接到其他版本的同一文章，请使用以下格式：

For more information, see [the VERSION documentation](/VERSION/{{ currentArticle }}).

要链接到特定版本，必须在路径中包含该版本（例如 /enterprise-cloud@latest/{{ currentArticle }}）。

指向文章特定部分的链接

链接到文章的特定部分时，我们希望确保链接的描述性足够强，以便用户在点击链接后知道他们在正确的位置。

若要链接到同一文章中的特定标题，请使用以下格式：

For more information, see "[HEADER TITLE](#HEADER-TITLE)."

若要链接到其他文章中的特定标题，请使用以下格式：

For more information, see "[AUTOTITLE](PATH-TO-ARTICLE#HEADER-TITLE)."

若要链接到其他文章中的特定标题，请使用以下格式：

For more information, see "[HEADER-TITLE-1](PATH-TO-ARTICLE#SECTION-LINK-1)" and "[HEADER-TITLE-2](PATH-TO-ARTICLE#SECTION-LINK-2)" in "ARTICLE-TITLE."

指向特定工具的链接

链接到选择了特定工具的内容时，我们希望确保用户知道他们将查看与特定工具相关的内容，即使他们未在文章中查看工具切换器选项卡。

For more information, see the TOOLNAME documentation in "[ARTICLE TITLE](/PATH/TO/ARTICLE?tool=TOOLNAME)."

指向学习路径的链接

若要链接到学习路径，请使用以下格式。

For more information, follow the "[LEARNING PATH TITLE](/)" learning path.

指向外部资源的链接

链接到外部站点时，请为链接上下文选择最有用的资源 - 可以链接到整个站点（如果是一般引用），也可以链接到特定页面（如果这样做更有帮助）。

当我们提及外部产品时，无需链接到外部产品的网站。

列表

将列表每一行中的第一个字母大写。仅当行包含完整句子时，才在列表中的行尾使用句点。

编写由主要文本和辅助文本组成的项列表（例如 term 及其定义）时，请使用冒号分隔符。辅助文本应大写，就像它是行的开头一样。例如：

foo：提供条形图的内容。
bar：foo 提供的内容。

设置无序列表的格式：

如果列表中项的顺序不重要，请按字母顺序排列列表项。
如果顺序很重要，则按对读者的重要性对列表进行排序（例如从最广泛的受众和适用性到更专业的受众）。

引入列表时，请避免使用包含“以下”或“这些”等在没有上下文的情况下难以本地化的术语的非特定短句。相反，请创建描述性句子，该句子可以清楚地传达列表的主题，并且允许列表缩放或更改，而无需更新说明。

使用：****

有关 GitHub 的简介，请参阅以下文章：
下列国家/地区支持 SMS 身份验证：

避免：

有几篇文章介绍了 GitHub。参阅以下内容：
有 50 个国家/地区支持 SMS 身份验证。其中包括：

占位符

设置全大写中任何占位符文本的样式。如果占位符是多个单词，则请将单词与短划线（-）连接。如果使用占位符，则请说明用户可能将其替换为的内容。这有助于用户修改示例以满足其需求，并帮助使用辅助技术的用户识别占位符。

使用：****

在以下示例中，将 YOUR-REPOSITORY 替换为存储库的名称。 git init YOUR-REPOSITORY
单击“添加 USERNAME”****。其中 USERNAME 是要添加的用户的用户名。

避免：

git init your repository
git init <your-repository>
单击“添加_用户名_”****。

过程步骤

过程为读者提供了完成任务需要遵循的一组顺序步骤。应始终对过程使用编号列表。请在过程之前为读者提供完成任务所需的全部先决条件或概念信息，而不是将其包含在特定步骤中。

每个步骤都必须包含一个操作。还可以选择包括步骤是否可选，解释步骤的原因或结果，并通过描述操作的位置然后引导完成操作来指导读者。

使用一致的顺序在每个步骤中显示信息。

如果步骤是可选的，请先指出。
当需要澄清或强调破坏性或混淆操作的严重性时，请解释步骤的原因或结果。
描述用户将在其中找到操作的位置。
操作。

使用： （可选）若要 REASON，请在 LOCATION 中，执行 ACTION。

示例：

单击付款信息。
在组织名称下，单击设置。
若要确认更改，请单击删除信用卡。
（可选）若要查看计划的详细信息，请单击显示详细信息。
在“GitHub Sponsors”下，在受赞助开源贡献者的右侧，单击赞助金额旁边的 [向下箭头图标]，然后单击更改层。

产品名称

使用完整产品名称。请勿缩写或缩短产品名称，除非直接复制产品中的内容（例如 UI 副本或 API 响应）。

请使用产品名称变量来呈现产品名称，请勿以纯文本形式编写产品名称。这样一来，便可更轻松地在整个站点实现产品名称更改，并避免产品名称中出现打字错误。有关产品名称变量的详细信息，请参阅本文档中的“可重用代码和变量”以及 github/docs 存储库的数据目录。

产品名称始终为单数。

使用： GitHub Actions 可帮助你自动完成软件开发工作流。
避免： GitHub Actions 们可帮助你自动完成软件开发工作流。

请注意区分产品名称和产品元素。

产品	元素
GitHub Actions	操作
GitHub Codespaces	codespace
GitHub Packages	包
GitHub Pages	GitHub Pages 站点

产品特定的约定

本部分介绍 GitHub 产品特定的其他约定。

GitHub Actions

第一方操作的可重用代码

使用第一方操作的代码示例必须为该操作使用相应的可重用代码。这使得 GitHub Enterprise Server 等产品的操作版本更新（例如从 v1 到 v2）更易于管理，这些产品在将来的 GitHub Enterprise Server 版本发布之前可能没有相同的操作版本可用。

操作可重用代码位于 /data/reusables/actions/ 中，其文件名类似于 action-<action_name>.md

例如，若要在示例中使用 actions/checkout 操作，请使用其其可重用代码：

steps:
  - name: Checkout
    uses: actions/checkout@v4

对于 GitHub Docs 而言，第一方操作是具有 actions/、github/ 或 octo-org/ 前缀的任何操作。例如，以下是第一方操作：

steps:
  - uses: actions/checkout@main

第三方操作的免责声明

使用第三方操作的代码示例必须包含以下免责声明作为代码块的一部分：

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

若要插入此免责声明，请使用 {% data reusables.actions.actions-not-certified-by-github-comment %}{% endnote %} 可重用代码。如果代码块缩进，则必须将 indented_data_reference 与可重用代码一起使用。例如：

{% raw %}{% indented_data_reference reusables.actions.actions-not-certified-by-github-comment spaces=4 %}

对于 GitHub Docs 而言，第三方操作是不具有 actions/、github/ 或 octo-org/ 前缀的任何操作。例如，以下是第一方操作：

steps:
  - uses: actions/checkout@main

以下是第三方操作的示例：

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

示例：

请参阅“发布到包注册表”中的代码块

将版本号固定到 SHA

使用第三方操作的代码示例必须始终固定到完整长度的提交 SHA，而不是版本号或分支：

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

对于 GitHub Docs 而言，第三方操作是不具有以下任一前缀的任何操作：actions/、github/ 或 octo-org/。例如，以下是第一方操作：

steps:
  - uses: actions/javascript-action@main

有关详细信息，请参阅“使用 SHA”

Codespaces

引用产品 Codespaces 时，请始终包含“GitHub”，但以下情况除外：

在 shortTitle 前言中。
在文章内的子标题中（如果“Codespaces”已在文章中的子标题之前的任何位置使用）。

变量：{% data variables.product.prodname_github_codespaces %}（“GitHub Codespace”）和 {% data variables.product.prodname_codespaces %}（“Codespace”）。

引用使用此技术创建的远程工作环境实例时，请将引用为“codespace”（小写 c）。例如，“删除 codespace”或“列出 codespace”。

请始终使用“开发容器”（或者为了清除起见，使用其更长形式“用于开发的容器”），而不使用“devcontainer”（一个词），除了在文件/路径名中。单个词形式可能被视为品牌，我们希望避免这种情况，我们还希望与 Visual Studio Code 文档中使用的两个词形式保持一致。

使用“开发容器配置文件”来引用 .devcontainer 目录中的所有文件（如果使用，则加上 .devcontainer.json），而不是 .devcontainer 目录中的 devcontainer.json。请勿将这些文件称为“开发容器文件”或“devcontainer 文件”，以免将其视为引用 devcontainer.json 文件。 “开发容器配置文件”是指可用于配置开发容器的所有文件，包括 Dockerfile 和 docker-compose.yml 文件。专门引用 devcontainer.json 文件时，请勿使用“开发容器配置文件”（单数）。而是按名称引用此文件。

GitHub Advanced Security (GHAS)

引用 GitHub Advanced Security 计费时，请使用术语 licenses 和 active committers。

我们使用术语 seats 来描述企业中可以使用 GitHub Advanced Security 的帐户数。人们可能会对术语 seats 感到困惑，因此我们在 2022 年秋季从 GitHub.com 中删除了该术语，并且 GHES/GHAE 3.7 及更高版本的版本不再使用它。

Personal access tokens

GitHub 有两种类型的 personal access tokens：

Fine-grained personal access token：提供对存储库访问和权限的精细控制
Personal access token (classic)：使用范围并授予对令牌所有者可以访问的所有存储库的访问权限

通常，应使用变量来引用这些类型的令牌，以及 personal access tokens：

通常使用 {% data variables.product.pat_generic %} 或 {% data variables.product.pat_generic_caps %} 来引用 personal access token。如果词组应采用标题大小写（“Personal Access Token”）以匹配 UI 文本，请使用 {% data variables.product.pat_generic_title_case %}。
使用 {% data variables.product.pat_v2 %} 或 {% data variables.product.pat_v2_caps %} 来引用 fine-grained personal access token。
使用 {% data variables.product.pat_v1 %}、{% data variables.product.pat_v1_plural %}、{% data variables.product.pat_v1_caps %} 或 {% data variables.product.pat_v1_caps_plural %} 来引用 personal access token (classic)。

有关 GitHub 的 personal access tokens 的详细信息，请参阅“管理个人访问令牌”。

标点

在引号中引用 UI 元素时，请将任何后续标点符号放在引号之外，确保引号中的标签与 UI 完全匹配。

使用： 在“用户许可证”下，查看许可证总数。

否则，请遵循标准美式英语标点规则。有关更多指导，请参阅 Microsoft 风格指南中的“标点符号”。

发行说明

GitHub Docs 的一组发行说明告诉读者有关产品（如 GitHub Enterprise Server (GHES)）的版本控制版本面向管理员或用户的更改。发行说明显示在发行说明中。

好的发行说明是几句话，按顺序回答读者关于更改的问题。有关详细信息，请参阅“发行说明内容类型”。

一组中的每个发行说明都描述了以下更改之一。

功能：全新的行为或功能
安全修复：修复具有安全隐患的缺陷或意外行为
Bug 修复：修复缺陷或意外行为
更改：对过去行为的显著更改
已知问题：GitHub 已识别但无法或尚未确定优先级的问题
弃用：删除功能或行为
勘误：更正不准确的发行说明或文档

还可以在添加或更新发行说明中查看更新发行说明的指南。

功能

功能发行说明概括全新行为。通常，功能说明只是功能版本的一部分。

编写功能的发行说明

功能发行说明回答以下问题。

该新功能是否适用于我的角色或访问权限？
该功能满足哪些需求？
该功能是什么？
如果适用，可在何处阅读有关该功能的详细信息？

受众 (1) 可以通过_功能使用描述_ (3) 来_需求描述_ (2)。有关详细信息，请参阅“文章标题”(4)。

在功能标题下的部分中对每个功能进行分类。
用现在时编写。
为了减少重复和不必要的单词，通常暗示“现在”。
为了澄清参与者和影响，请尽可能避免被动语言。

功能发行说明示例

为了提高管理控制台的安全性，站点管理员可以配置登录尝试的速率限制，以及超过速率限制后的锁定持续时间。有关详细信息，请参阅“配置速率限制”。
企业所有者可以控制用户可对存储库进行分支的位置。分叉可以限制为预设的组织组合、与父存储库相同的组织、用户帐户或任意位置。有关详细信息，请参阅“在企业中实施存储库管理策略”。
用户可以使用 geoJSON、topoJSON 和 STL 图表创建文件，并在 Web 界面中呈现图表。有关详细信息，请参阅“使用非代码文件”。

安全修补程序

安全修复发行说明概括可缓解或阻止产品中安全相关问题被利用的更改。通常，安全修复说明只是补丁发行的一部分。

编写安全修复发行说明

安全修复发行说明回答以下问题。

如果可用，已修复漏洞的 NVD 漏洞严重等级是多少？
攻击者通过利用漏洞可以完成什么攻击？
哪种类型的漏洞可被利用？
如果可用，漏洞的 CVE 标识符（挂起或活动）是什么？
用户是否通过 GitHub Bug 悬赏计划报告了漏洞？

严重性 (1)：攻击者可以通过_攻击描述_ (3) 来_影响描述_ (2)。 GitHub 已针对此漏洞请求 CVE-####-##### (4)，该漏洞已通过 GitHub Bug 悬赏计划 (5)。

安全修复发行说明示例

中等： 攻击者可能向 Markdown REST API 发出并行请求，导致实例上的无限资源耗尽。为了缓解此问题，GitHub 更新了 CommonMarker。 GitHub 已针对此漏洞请求 CVE ID CVE-2022-39209。
中等： 攻击者可能在实例的 Web UI 中嵌入危险链接，因为拉取请求预览链接未正确清理 URL。该漏洞通过 GitHub Bug 悬赏计划报告。

基础映像和包更新

我们还在“安全修复”部分包括了基础映像和相关包更新，因为这些更新通常会解决安全问题。我们将在以下笔记中合并所有这些更新。

包已更新到最新的安全版本。

Bug 修复

Bug 修复发行说明描述了对不需要或其他意外行为的更正。通常，Bug 修复说明只是补丁发行的一部分。

编写 Bug 修复发行说明

Bug 修复发行说明回答以下问题。

该行为是否会影响我的角色或访问权限？
在修复之前读者会遇到什么行为？

受众 (1) 行为描述 (2)。

由于 Bug 现已修复，因此请以过去时编写。
“修复了 bug...”或“修复了问题...”之类的语言是隐含的且不必要。
为了减少重复和不必要的单词，通常暗示“现在”。
为了澄清参与者和影响，请尽可能避免被动语言。

Bug 修复发行说明示例

用户导入启用了推送保护的存储库后，该存储库不会立即显示在安全概述的“安全覆盖范围”视图中。
在启用了 GitHub Actions 的实例上，如果匹配的运行器组在作业最初排队时不可用，那么即使匹配的运行器组在作业进入队列后可用，也无法启动 GitHub Actions 的工作流作业。
站点管理员在任何实例节点上通过 SSH 运行的命令未记录在 /var/log/ssh-console-audit.log 中。

更改

更改发行说明描述对现有行为的显著但较小的更改。更改说明回答以下问题。

编写更改发行说明

更改发行说明回答以下问题。

该行为是否会影响我的角色或访问权限？
如果更改解决或避免某个问题，该问题是什么？
新行为是什么？
如果相关，更改之前的行为是什么？

受众 (1) / 更改解决的问题描述 (2) 新行为描述 (3) 旧行为描述 (4)。

由于更改适用于相关版本，因此请以现在时编写更改说明。
为了减少重复和不必要的单词，通常暗示“现在”。
为了澄清参与者和影响，请尽可能避免被动语言。
通常，受众是隐含的。
如果有用，请包含指向 GitHub Docs 的相关链接。

更改发行说明示例

在具有 GitHub Advanced Security 许可证的实例上，创作机密扫描自定义模式的用户可以提供必须匹配或不能匹配的最多具有 2,000 个字符的表达式。在此之前，限制为 1,000 个字符。
对于需要查看或修改 SAML 映射的管理员，ghe-saml-mapping-csv -d 输出的默认路径是 /data/user/tmp 而不是 /tmp。有关详细信息，请参阅“命令行实用工具”。
为避免在具有多个节点的实例上成功执行 Git 操作时出现间歇性问题，GitHub Enterprise Server 会在尝试 SQL 查询之前检查 MySQL 容器的状态。超时持续时间也已缩短。

已知问题

已知问题发行说明描述了 GitHub 已识别但无法或尚未确定优先级的问题。

编写已知问题发行说明

已知问题发行说明回答以下问题。

该行为是否会影响我的角色或访问权限？
如果更改解决或避免某个问题，该问题是什么？
显示哪些错误消息或其他可识别的 UI 元素？
我需要采取行动吗？如果需要，我该怎么做？

受众 (1) 问题描述 (2) 行为详情 (3) 后续步骤 (4)。

为了澄清参与者和影响，请尽可能避免被动语言。
为了减少重复和不必要的单词，通常暗示“现在”。
如果有用，请包含指向 GitHub Docs 的相关链接。
已知问题也是 GitHub Docs 上的一个内容类型。有关详细信息，请参阅“故障排除内容类型”。如果有用，请编写文档中的更深入内容和上下文相关内容，并且链接到这些内容。

已知问题发行说明示例

用户为存储库启用选项以允许具有读取访问权限的用户创建讨论后，该功能不启用。
管理员开始配置运行后，Notebook 和 Viewscreen 服务的验证阶段可能会发生 No such object error。可以忽略此错误，因为服务仍应正确启动。

弃用功能

弃用发行说明概括 GitHub 已删除或计划删除的行为或功能。通常，弃用说明只是功能发行的一部分。

编写弃用发行说明

弃用发行说明回答以下问题。

此现有功能是否适用于我的角色或访问权限？
弃用什么功能？
如果适用，什么替换了已弃用的功能？
如果适用，可在何处阅读详细信息？

受众 (1) 已弃用功能的描述 (2) 替换功能 (3) 有关详细信息，请参阅“文章标题”(4)。

说明为现在时，即将进行的更改为将来时。如果适用，请指定将发生弃用的未来发行。
为了减少重复和不必要的单词，通常暗示“现在”。
为了澄清参与者和影响，请尽可能避免被动语言。
在功能标题下的部分中对每个功能进行分类。

弃用发行说明示例

即将弃用： 在 GitHub Enterprise Server 3.8 及更高版本中，为确保实例安全，将禁用与管理 shell 的 SSH 连接的不安全算法。
提交注释（用户直接添加到拉取请求外部的注释）不再显示在拉取请求时间线中。用户无法回复或解决这些评论。时间线事件 REST API 和 GraphQL API 的 PullRequest 对象也不再返回提交注释。

错误

勘误表更正了之前在某个版本的发行说明或文档中发布的不准确信息。

编写勘误表

勘误表回答以下问题。

如果适用，GitHub Docs 发行说明或内容的哪一部分受到影响？
不正确的信息是否适用于我的角色或访问权限？
发行说明或文档描述的哪些内容不正确？
勘误表是什么时候发布的？

内容 (1) 错误地指示_受众_ (2) 可以_不准确信息概括_ (3)。 [更新日期：发布日期 4]

根据添加或更新发行说明中的指南设置发布日期的格式。

勘误表示例

“功能”错误地指示 GitHub Advisory Database 的用户可以看到 Elixir（Erlang 的十六进制包管理器）等的建议。此功能在 GitHub Enterprise Server 3.7 中不可用，并将在将来的版本中提供。 [更新日期：2023-06-01]

添加或更新发行说明

若要向读者发出你已添加或更改说明的信号，或者要指示勘误表的发布日期，请追加格式为“[更新日期：YYYY-MM-DD]”的日期戳。

可重用代码和变量

对单个名词（例如产品名称）或完整的句子或段落使用可重用的字符串。句子片段和短语不应包含在可重用的字符串中，因为它们可能会导致内容本地化时出现问题。有关详细信息，请参阅 github/docs 存储库中的数据目录、“创建可重用内容”，以及本文档的“产品名称”部分。

分区 TOC

如果文章的某一部分使用 H3 或 H4 标题进一步划分内容，并且只有部分内容与读者相关，则可以使用分区目录 (TOC) 来帮助读者识别并导航到与其最相关的信息。例如，在“流式处理企业审核日志”中，用户可能只会为一个提供程序设置审核日志流，因此他们可以通过“设置审核日志流”中的分区 TOC 选择其提供程序并导航到相关内容，而无需阅读整个部分。

如果 H3 或 H4 标题仅用于对内容进行分组，并且所有信息都可能与读者相关，则不要添加分区 TOC。例如，在“About identity and access management”中，用户应该阅读并考虑与其企业相关的每个部分。本文中不包括分区 TOC，因为用户应该通读每个部分，而不是在它们之间进行挑选。添加分区 TOC 还会强制使用屏幕阅读器或其他自适应技术的用户在找到所需内容之前按 Tab 键并滚动浏览更多标题。

将分区 TOC 格式设置为列表。按照它们在文章中出现的顺序包括所有小节，并使用完整的标题引用它们。

必须使用句子或段落引入分区 TOC，以帮助用户理解内容的组织方式并选择与他们最相关的部分。不要在标题正下方包含分区 TOC。

分区 TOC 示例

## Setting up the application

Set up your application according to your operating system.

- [Setting up for macOS](#setting-up-for-macOS)
- [Setting up for Windows](#setting-up-for-windows)
- [Setting up for Linux](#setting-up-for-linux)

### Setting up for macOS

TEXT

### Setting up for Windows

The application is supported for all versions of Windows, but the set up steps differ.

- [Windows 98](#windows-98)
- [Windows Vista](#windows-vista)
- [Windows 11](#windows-11)

#### Windows 98

TEXT

#### Windows Vista

TEXT

#### Windows 11

TEXT

### Setting up for Linux

TEXT

表

使用 Markdown 将表添加到 GitHub Docs。由于表可能难以读取和维护，因而在创建表之前，请确保表中的数据最好以表的形式表示，而不是采用其他格式（如列表）。表中的每一行都必须以竖线符号 | 开头和结尾。

仅将表用于显示表格信息

表最适合显示表格数据，例如需要比较的信息或具有多个属性的值。不要将表用于简单列表 - 请参阅本文档的“列表”部分。

应避免描述表数据

表的数据及其重要性应在前面的任何内容、列标题和行标题（如果需要）中明确。应避免对表中的数据进行不必要的描述。如果表中的数据不清楚，又没有冗长的描述，请考虑表是否需要行标题，或者是否以不同的方式更好地传达信息。

例如，在“使用自托管运行器自动缩放”中，引入了一个比较两个受支持自动缩放解决方案各项功能的表，其中包含句子 Each solution has certain specifics that may be important to consider.。本文不介绍所比较的任何不同功能，因为该表清楚地传达了该信息。

使用： “根据 GHES 版本，每个存储库适用不同的大小限制”。
避免： “表的第一行显示 GitHub Enterprise Cloud 的信息。第二行显示 GitHub Enterprise Server 的信息。”
避免： “下表显示导出的迁移数据类型。”

对行标题和列标题使用适当的标记

第一列描述表中数据值（但不是数据本身）的表需要使用行标题进行标记。这对于辅助技术理解单元格之间的关系非常重要。

例如，在下表中，为了理解表中的“是”和“否”值，需要同时知道列标题（角色）和行标题（权限）。

组织权限	所有者	成员	审核员	帐单管理员	安全管理员
创建存储库	是	是	是	否	是
查看和编辑帐单信息	是	No	No	是	否
邀请人员加入组织	是	No	No	No	否

若要为 Markdown 表添加行标题，请将表包装在 Liquid 标记 {% rowheaders %} {% endrowheaders %} 中。有关使用行标题的详细信息，请参阅“在 GitHub Docs 中使用 Markdown 和 Liquid”。

包含每个单元格的值

表中的每个单元格都必须包含一个值。如果表有行标题，则第一个单元格（单元格 A1）可以为空。

如果没有数据，请使用“无”或“不适用”。请勿使用“NA”或“N/A”。

使用清晰、一致的符号和标签

对于使用符号的表：

填充所有单元格。例如，在权限表中，不要只标记需要权限的内容的单元格。
请使用图标或 SVG。请勿使用表情符号。有关 octicons 的详细信息，请参阅“[AUTOTITLE]/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#octicons)”。
对肯定值（“是”、“必需”、“支持”）使用勾号，对否定值（“否”、“可选”、“不支持”）使用叉号。
请使用 aria-label 来描述符号的含义，而不是其视觉特征。例如，“必需”，而不是“勾号图标”。

如果表数据不是真正的二进制数据（例如，每个值都是“是”或“否”），则除了符号之外，可能还需要文本值，或者用来代替符号。例如，在“关于 GitHub 支持”页面上，某些功能被标记为“可供购买”。

请谨慎使用脚注

请参阅“脚注”。

一致地对齐表内容

表中的所有列都应左对齐，但仅包含图标的列除外，这些列应居中对齐。如果列同时包含文本和图标，请使用居中对齐方式。

默认情况下，表内容左对齐。请使用 Markdown 表格式（冒号 : 位于标题行中短划线的右侧或左侧）来指定每列的对齐方式。有关详细信息，请阅读“使用表格组织信息”。

以下示例显示了“dependabot.yml 文件的配置选项”中表的一部分。

选项	必需	安全更新	版本更新	说明
`package-ecosystem`				要使用的包管理器
`directory`				包清单位置
`schedule.interval`				检查更新的频率

表是使用以下对齐语法生成的。

| Option              | Required | Security Updates | Version Updates | Description                    |
|---------------------|:--------:|:----------------:|:---------------:|--------------------------------|
| `package-ecosystem` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Package manager to use         |
| `directory`         |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Location of package manifests  |
| `schedule.interval` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| How often to check for updates |

标题

请在文章标题两边使用引号，无论文章是托管在 GitHub Docs 上还是其他地方。请勿在外部站点的名称两边加上引号。

有关进一步指导，请参阅 Microsoft 风格指南中的“设置标题格式”。

短标题

我们使用短标题来填充边栏导航。由于短标题显示在边栏导航中，因此它们可以使用上下文来传达意义，要比全名略为不精确。短标题的目标是帮助用户找到其查找的内容，而无需使用过长的边栏导航项。短标题为用户提供对文章的上下文理解，并符合以下标准。

短标题长度为 2-3 个单词。
- 对于类别，短标题必须少于 27 个字符。
- 对于映射主题，短标题必须少于 30 个字符。
- 对于文章，短标题必须少于 31 个字符，理想情况下为 20 至 25 个字符。
短标题会使用谓词的基本形式，而不是动名词。
- 使用：“配置通知”而不是“配置通知”。
类别、映射主题和文章的简短标题可以省略产品和功能名称（如果与其相关的产品或功能已明确）。
- 使用：“配置通知”作为“为 Dependabot 警报配置通知”的短标题，因为文章位于 "Dependabot alerts" 映射主题中。
不要在短标题中引入完整标题中没有的新单词。
相似内容的短标题应平行
- 使用：“组织和团队”和“企业帐户”
- 避免使用：“组织和团队”和“管理企业帐户”

编写短标题可能具有挑战性。要帮助在字符计数的限制范围内获取短标题，请考虑上下文中的短标题。如果可能，请移除任何重复字词以及内容所属的映射主题或类别中的任何产品或功能名称。

用户界面元素

粗体

使用粗体描述可以与之交互的 UI 元素。

在左侧边栏中，单击“计费”。
查看拉取请求的对话选项卡底部的合并框。
在标题旁边，为新密钥添加描述性标签。

分支名称

对分支名称使用代码格式。

main
USERNAME.github.io

按钮

将按钮名称的格式设置为粗体，并尽可能省略“按钮”一词。若要描述使用按钮，请编写“单击”，而不是按或按下。

使用： 单击拉取请求。
避免： 按“拉取请求”按钮。

复选框

将复选框名称的格式设置为粗体，并省略“复选框”一词。若要描述选中或清除复选框，请使用“选中”或“取消选中”。

使用： 选中对所有新存储库启用。
避免： 选中“对所有新存储库启用”复选框。

动态文本

使用大写字母指示用户界面中发生更改的文本，或者用户需要在命令或代码片段中提供的文本。

使用： 单击将用户名添加到存储库名称。

列表和列表项

将列表和可单击列表项的格式设置为粗体。若要描述与列表（例如展开的下拉菜单或 UI 元素）交互，无论列表名称是单词还是图标，都请编写“选择”。若要描述选择列表项，请编写“单击”。

使用： 选择备份电子邮件地址下拉菜单，然后单击仅允许主电子邮件。
避免： 单击备份电子邮件地址”下拉菜单，然后单击仅允许主电子邮件。

位置

使用标准术语描述用户界面元素的位置。

下面或上面
紧靠
左上角、右上角、左下角、右下角
页面顶部、页面底部、页面右侧、页面左侧

面板

如果可能，请避免引用面板。而是描述用户需要执行的操作。

使用： 单击存储库的查看图表和图形，然后从下拉菜单中选择要查看的时间段。
避免： 单击查看图表和图形以打开所选存储库的面板，然后从下拉菜单中选择要查看的时间段。

如果需要引用面板来描述 UI 的更改或说明如何与 UI 交互，请将面板名称的格式设置为用户界面文本。仅当单词面板更清晰或面板在 UI 中没有名称时，才包含该面板。

使用： 在“安全覆盖范围”面板中，选择启用或禁用。
使用： 在面板中，选择启用或禁用。

单选按钮

将单选按钮标签的格式设置为粗体，并省略“单选按钮”一词或任何其他描述符。若要描述使用单选按钮，请编写“选择”。

存储库名称。

使用标准格式引用存储库。在有用时链接到存储库。

使用： 在 [account-name/repository-name](URL) 存储库中

用户界面文本

引用用户界面中的文本时，请准确重现文本。使用引号将无法与之交互的 UI 文本引起来。

使用： 在“IP 允许列表”下，单击编辑。

视频

你可以添加视频来强化基于文本的信息，但视频绝不应替换书面内容。某些用户无法访问视频，也很难通过搜索找到视频。

GitHub Docs 网站上的视频必须制作精良，对残障人士的障碍更少，并符合我们的视频内容模型。有关详细信息，请参阅“关于在 GitHub Docs 中使用视频”。

语音和声调

使用清晰、简单且适合广泛读者的语言。对自己的写作内容要真实、善解人意和有把握。

站在受众的角度写作：一些行话和技术术语是必要的，但不要依赖于每个读者都有相同技术专业知识水平的假设。

尽可能使用主动语态。需要强调操作的对象时，可使用被动语态。

我们是一个全球开发人员社区。避免出现特定于特定国家或地区的短语、成语和俚语。

若要了解有关编写平易近人的内容的详细信息，请参阅“Microsoft 的品牌调性：最重要的是，简单和人性化”以及“Microsoft 风格和语音的十大技巧”。

单词选择和术语

有关一般指南和 GitHub 特定的术语，请参阅我们的“术语表”。有关更详细的指南，请参阅 Microsoft 风格指南中的“A-Z 单词列表”。

缩写形式

拼写单词，除非引用产品本身中明确缩短的单词。

使用： 存储库
避免： 仓库
使用： 管理员，具有管理权限的人员
避免： 管理

请勿使用 GitHub 用户界面中未使用的符号或图标。

使用： 单击文件，然后单击编辑。
避免： 单击文件 > 编辑。

帐户

产品名称和帐户

为避免歧义和混淆，请勿使用产品名称作为形容词来描述我们任何产品中的帐户。相反，请澄清帐户类型并选择更清晰的措辞，以避免将帐户和产品混为一谈。在谈论帐户时，仅在需要时引用产品名称以消除产品之间的歧义。有关 GitHub 产品中可用帐户类型的详细信息，请参阅“GitHub 帐户类型”。

使用： 你在 GitHub Enterprise Cloud 上的组织
避免： 你的 GitHub Enterprise Cloud 帐户
避免： 你的 GitHub Enterprise Server
使用： 通过将贡献计数发送到你的 GitHub.com 配置文件，可在 GitHub Enterprise Server 上突出显示你的作品。

GitHub 上的个人帐户

我们指的是个人以各种方式登录的帐户，具体取决于上下文。

除非内容与管理企业产品有关，否则请将个人在 GitHub 上的帐户描述为“个人帐户”。这样可以与 UI 保持一致，并防止读者因看到两个含义相同的术语而感到困惑。

使用： 管理个人帐户的预定提醒
避免： 管理用户帐户的预定提醒

企业产品的帐户

使用 GitHub 的企业产品，管理员可以管理企业帐户。企业帐户可以拥有多个组织，个人的用户帐户可以是组织的成员。有关详细信息，请参阅每个产品的“企业中的角色”一文。

GitHub Enterprise Cloud
GitHub Enterprise Server
GitHub AE

如果读者管理企业帐户，而你描述的是他们管理的人员帐户，请使用“用户帐户”。这适用于以下产品。

带 Enterprise Managed Users 的 GitHub Enterprise Cloud
- 使用： 使用 Enterprise Managed Users，你可以为企业成员创建和管理用户帐户。
- ：使用 Enterprise Managed Users，你可以为企业成员创建和管理个人帐户。
GitHub Enterprise Server
- 使用： 如果需要暂时接管用户帐户...
- 使用： 如果需要暂时接管个人帐户...
GitHub AE
- 使用： 授权用户可以从任何 IP 地址访问你的企业。
- 避免： 授权个人帐户可以从任何 IP 地址访问你的企业。

以下文档应引用“用户帐户”。

“企业管理员文档”产品
企业特定的计费文档，如“关于企业的计费”
面向管理受众的其他产品中的内容，例如“代码安全”产品中的“确保帐户安全的最佳做法”或“入门”产品中的“设置 GitHub Enterprise Cloud 试用版”
企业特定的 API 内容，例如“GitHub Enterprise 管理”REST API 参考文档

对于不使用 Enterprise Managed Users 的 GitHub Enterprise Cloud 上的企业，在描述企业拥有的组织成员时，请使用“个人帐户”。

使用： 如果配置了 SAML SSO，组织成员将继续在 GitHub.com 上登录到其个人帐户。
避免： 如果配置了 SAML SSO，组织成员将继续在 GitHub.com 上登录到其用户帐户。

描述不带 Enterprise Managed Users 的 GitHub Enterprise Cloud 的文档通常属于“管理组织的 SAML 单点登录”类别。

其他服务的人员帐户

当你描述 GitHub 以外的服务（例如集成或身份验证提供程序）的人员帐户时，请使用“用户帐户”。

首字母缩写词

在文章中首次使用首字母缩略词时，请拼出首字母缩略词，标题中除外。

“应用”

在常规内容中使用“应用”或“应用程序”。

使用： 在 GitHub Marketplace 中发布和列出你的应用

引用 OAuth apps 时，请使用“应用”，因为这些不是产品。

使用： 注册 OAuth app
避免： 注册 OAuth 应用

引用 GitHub Apps 时，请使用“应用”，因为这是一个产品。

使用： 注册 GitHub App

GitHub Apps 和 OAuth apps 由两个部分组成：应用注册和使应用执行某些操作的代码。

若要仅引用 GitHub UI 中的 GitHub App 设置/配置，请使用“注册”和“GitHub App 注册”等术语。
- 使用： 注册 GitHub App
- 使用： 更新 GitHub App 注册
- 避免： 创建 GitHub App
- 避免： 修改 GitHub App
若要仅引用应用的代码，请使用“应用的代码”或“应用代码”等术语。
- 使用： 应用的代码
- 使用： GitHub App 的代码
- 使用： 应用代码
- 避免： GitHub App
- 避免： OAuth app
若要统一引用整个应用（注册 + 代码），请将其引用为 GitHub App 或 OAuth app。

GitHub Apps 可以安装在组织和用户帐户上。若要引用应用的安装，请使用“GitHub App 安装”，而不是“GitHub App”。

货币

在引用美元、分、货币金额或使用 $ 符号时，请确保已定义使用的货币，即使金额为零。尽可能使用 ISO 标准货币名称和 ISO 标准货币代码。

对货币名称使用小写，但对国家或地区的引用大写。

使用： 美元。
避免： 。

对货币代码使用大写。

使用： USD。

如果文章中只有一个引用，请使用货币名称，金额前不带 $ 符号。

使用： 10 US dollars 用于单一货币引用。

如果项目包含对同一货币的多个引用，请确保第一个引用使用的货币名称在金额前不带 $ 符号，并在货币名称后面的括号中包含货币代码。

对于文章或适当情况下对货币的后续引用（例如，当需要考虑空间或者在表格或列表中显示多个金额时），请在金额前加上 $ 符号，并在金额后使用 ISO 标准货币代码。

使用： 10 US dollars (USD) 用于第一个引用，$0.25 USD 用于后续引用。
避免： $10 US dollars (USD)、USD$0.25。

如果第一个引用涉及 cents 或非美元金额，请将第一个引用后面的括号中对所用货币的国家或地区的引用大写。后续货币引用遵循上述准则进行处理。

使用： 99 cents (US currency) 用于第一个引用，99 cents 用于后续引用。
避免： $0.99 (US currency)、$0.99 USD cents、USD$0.99 cents。

权限

权限是执行特定操作的能力。例如，删除问题的能力是一种权限。

角色是可分配给用户的一组权限。角色存在于不同的级别。

帐户（例如，组织所有者、企业帐号的帐单管理员）
资源（例如，存储库的“写入”，安全公告的“管理员”）
团队（例如，“团队维护者”）

一个人的访问权限通常是指该人在特定环境中拥有的所有能力，无论这些能力来自哪个角色或个人权限。

仅当两者之间的区别很重要时才使用权限或角色。否则，请使用访问权限。

使用： To create a custom repository role, you choose an inherited role and then add individual permissions.
使用： Managing a team's access to your organization's repository
使用： If your team membership gives you a different level of access than your role as organization owner...
使用： People with write access can...
避免： People with the write role can...
避免： People with write permissions can...
避免： People with write privileges can...

指定执行操作所需的访问权限时，请仅引用与操作级别相同的角色。例如，需要对存储库具有管理员访问权限（存储库级别角色）才能配置受保护的分支。可以通过成为组织所有者（组织级别角色）来获取对存储库的管理员访问权限，但存储库级别角色实际上控制你执行操作的能力，因此，它是应提及的唯一角色。

使用： People with write access to a repository can do X to the repository.
避免： Organization owners and people with write access can do X to the repository.

有关权限声明的措辞选择的详细信息，请参阅内容模型中的“GitHub Docs 文章的内容”。

介词

避免用介词结束句子，除非重写的句子听起来很奇怪或太正式。

产品名称

请参阅本指南的“产品名称”部分。

使用或避免的术语

使用	避免
个人	用户、客户
terminal	shell
username	登录
登录	登入、登陆
注册	报名
推荐的限制	软性限制
电子邮件	电子邮件
前言	前言，前言
在 GitHub 上	在远程存储库上
按（键）	击打、敲击
键入（在用户界面中）	输入（在用户界面中）
输入（在命令行中）	键入（在命令行中）