风格指南

Note

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

GitHub Docs 风格方法

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

审核日志事件

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

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

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

警报

警报可以强调文章中特别重要的信息，并能为拆分信息流提供合理的理由。

请谨慎使用警报。不要使用连续警报，或是每个部分使用超过一个警报。

警报应简洁。如果信息包含多个句子，或者需要有序列表或无序列表，请考虑改为将信息置于节标题下。

警报类型

我们使用四种类型的警报：备注、提示、警告和注意。

注意

提供用户可能需要考虑的其他上下文。无需备注警报中的信息即可完成任务，但某些上下文中的某些用户可能会从备注中受益。

当括号内传达的信息对正在描述的进程而言并非重要信息时，注意标注尤其有用：

可能影响进程结果的注意事项，例如特定的用户设置。
可用性可能随时更改的产品和功能，例如处于 beta 版本或已弃用状态的产品和功能。

例如，“评估来自机密扫描的警报”使用注释来提醒用户，GitHub 令牌的元数据目前为 beta 版本。

Note

GitHub 令牌的元数据目前为 beta 版本，可能随时更改。

提示

推荐、最佳做法或产品提示。提示中包含用户可自行遵循的非必要信息。在面向新用户的文章中，标注特别有用。

例如，“个性化您的个人资料”使用提示警报来帮助用户了解 @mention 组织时会遇到什么情况。

Tip

当你 @mention 组织时，只有你所属的组织才会自动填写。你也可 @mention 不是其成员的组织（例如前雇主），但该组织名称不会自动填写。

警告

突出显示用户在开始或继续任务之前应注意的潜在风险。

警告警报尤其适用于 GitHub UI 外部发生的进程，例如在命令行中或通过 API 发生的。

例如，“关于 SSH 认证中心”包括命令行的说明，并使用警告警报提醒用户颁发后，无法吊销证书：

Warning

证书签名并颁发后，无法吊销。请确保使用 - V 标志来配置证书的生存期，否则证书可以无限期使用。

注意

警示用户即将执行的操作存在危险或会造成损失，应非常谨慎对待，尤其是存在安全风险或有可能发生数据丢失时。

描述 GitHub UI 以外发生的进程时，一般必须要有注意警报，例如，在命令行中或通过 API。

设置警报格式

我们对文档集中不同类型的警报使用标准格式和颜色。

使用 Markdown 呈现警报。

注意：

> [!NOTE]
> Keep this in mind.

提示：

> [!TIP]
> Here's a suggestion.

警告：

> [!WARNING]
> Be careful.

警告：

> [!CAUTION]
> Be extremely careful.

仍然支持警报使用 Liquid 语法，且较早的文章中可能仍会出现 Liquid 语法，但新的警报中不应再继续使用。

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

Buttons

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

如果一个按钮建议用户退出 GitHub Docs 站点，请按照行为召唤 (CTA) 按钮准则进行操作。如果要在登陆页或文章上包含其他类型的按钮，则必须获得 GitHub Docs 团队的批准。

行为召唤 (CTA) 按钮

CTA 按钮强调一个链接，我们希望或建议用户在阅读文章后或在完成文章所描述任务的过程中导航到该链接。 CCA 应仅将用户带到 GitHub 拥有的域。例如，“使用 GitHub Copilot 在 IDE 中获取代码建议”中的“试用 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?ref_cta=CTA+NAME&ref_loc=LOCATION&ref_page=docs" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"><span>Try PRODUCT NAME</span> {% octicon "link-external" height:16 %}</a>

将占位符替换为 CTA 的相关信息。

DESTINATION/URL：按钮应导航至的 URL。
CTA+NAME：CTA 的名称。例如，GHEC+trial 或 Copilot+Business+Trial。
LOCATION：CTA 的 GitHub Docs 中的位置。例如，Setting+up+a+trial+of+GitHub+Enterprise+Cloud。

代码

代码块

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

在代码块中：

在第一个代码围栏之后指定示例的语言。有关所有受支持语言的列表，请参阅 github/docs 存储库中的代码语言。
不要使用 HTML 为代码块设置样式或标记。
为用户在全大写中以自己的值进行替换的任何占位符设置样式。
- 使用：git checkout -b BRANCH-NAME****
- 避免： git checkout -b <branch-name>
不要在命令本身前面使用 $ 等命令提示符。这些提示符会使读者难以复制和粘贴命令。
- 如果显示命令和命令的输出，请在示例中以注释标示出输出内容。
- 使用：****
```
command
# output
```
- 避免：
```
$ command
output
```
如果代码示例包含应呈现的 { 或 }，请将该节放在 {% 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
```

不要包含诸如 $ 等命令提示符。避免在命令名称中使用内联链接。

Outputs

如果显示命令的输出，请在示例中以注释标示出输出内容，以便用户可以复制和粘贴命令，无需修改即可执行该命令。

使用：****
```
git lfs install
# Git LFS initialized.
```

避免：

$ git lfs install
> Git LFS initialized.

示例

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

使用：

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@v5
        with:
          python-version: ${{ matrix.python }}

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

计划工作流

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

不要使用在整点时刻运行的示例，因为这是最拥挤的时间。
请勿使用运行频率超过必要的示例。例如，可以考虑示例命令是否可以每 30 分钟运行一次，而不是每五分钟运行一次。
请对每个示例使用不同的时间。

强调

请使用粗体来强调句中的单词或部分。请谨慎使用强调（不超过 5 个连续单词），并且应记住这是一种视觉辅助工具，方便注意到的用户快速扫描。

请勿将应用了其他格式的单词加粗，例如全部大写的占位符文本。
对于辅助功能，请勿将加粗作为传达含义或强调的唯一方法。

例如：

用途： 托管用户帐户无法创建公共内容或在企业外部进行协作。
避免： 在_标题_ 旁边，为新密钥添加描述性标签。

错误消息

在文章中包含来自 GitHub 产品或界面的错误消息文本时，请根据消息出现的界面设置文本格式。

如果消息出现在 GitHub 的 Web 界面中，或出现在图形客户端应用（如 GitHub Desktop 或 GitHub Mobile）中，请像处理 UI 中的其他文本一样处理该消息。有关详细信息，请参阅用户界面文本。
如果消息出现在命令行界面、日志输出或 API 响应中，请准确重现文本，并使用反引号使用等宽字体设置消息的格式。

即将过期的内容

一般情况下，不记录将过期的内容。访问 GitHub Docs 的任何人都应确信信息准确且最新。

如果必须记录知道将过期的内容，则可以使用内容 linter 标记和跟踪内容的期满日。这会将内容标记为过时，并避免在内容本身之外跟踪期满日。有关如何设置即将过期内容标记格式的信息，请参阅“使用内容 Linter”。

脚注

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

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

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

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

| | 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 和 H4 级别章节标题进一步将内容组织到相关组中，但不能跳过章节标题级别。章节标题和子章节标题之间必须有内容，例如简介。

使用：****

## HEADER (H2)

TEXT

### SUBHEADER (H3)

TEXT

#### SUBHEADER (H4)

TEXT

避免：
```
## HEADER (H2)

#### SUBHEADER (H4)
```

页面上同一级别的每个标题必须是唯一的。

使用：****

## Examples  (H2)

TEXT

### Prompts for writing code (H3)

TEXT

### Prompts for writing tests (H3)

TEXT

使用：****

## Prompts for writing code (H2)

TEXT

### Example (H3)

TEXT

## Prompts for writing tests (H2)

TEXT

### Example (H3)

TEXT

避免：

## Example prompts (H2)

TEXT

### Example (H3)

TEXT

### Example (H3)

TEXT

映像

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

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

替换文本

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

表达图像的核心思想或含义，而不是从字面上描述它。
请使用 40-150 个字符。
请以标点符号结尾。通常应该是一个句点，除非替换文本描述以其他标点（如问号或感叹号）结尾的文本图像。
不要以“Image……”或“Graphic……”开头。屏幕阅读器会自动读出替换文本。
请以图形的类型__ 开始：“Screenshot of……”或“Diagram that shows……”
请遵循用于在文章文本中描述 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 元素。
为了清楚起见，请灵活调整字序。
- 例如，使用“Screenshot of the Debug menu in Visual Studio Code……”，而不是“Screenshot of the Visual Studio Code Debug menu……”，以避免一行出现多个名词。

示例

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

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

示意图和图表的替换文本

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

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

示例

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

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

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

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

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

图像的文件名

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

使用：data-pack-purchase-button.png
避免： purchase_button.png
避免： purchase-button-for-admins.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。

如果不需要链接，请将其删除。
如果链接与文章的主要主题相关，并让某人能够继续学习，但不需要完成该任务，请考虑将链接移动到文章末尾作为补充阅读材料。
如果链接将某人带到过程中的下一步，请在文章末尾的后续步骤部分包含该链接。
如果链接提供的信息对于完成任务或对步骤进行故障排除至关重要，请在文章的正文中包含该链接。

链接必须一致、可供尽可能多的人访问、可转换且清晰。人员需要知道链接指向何处，以及链接与其想要实现的目标之间的关系。

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

链接应该有意义，并且为用户旅程提供高价值。谨慎使用链接。
请勿在同一篇文章下多次重复同一链接。
在指向同一篇文章中的某个部分的链接后，考虑添加“本文的前面/后面部分”。
除非需要链接到 REST 文档的特定日历版本（这种情况很少见），否则请勿在 REST 链接中包含 apiVersion 查询参数。

设置链接格式

如果上下文明确了链接的用途，则可以仅使用动词“参阅”来引入链接。如果上下文未明确指明，请使用短语或句子来介绍该链接，例如“有关更多信息，请参阅”或“要了解有关 X 的更多信息，请参阅 Y”。

使用文档文章或外部网页的标题作为链接文本。对于指向 GitHub Docs 网站上另一篇文章的任何链接，请对链接文本使用特殊关键字 AUTOTITLE。有关详细信息，请参阅内容标记参考。

请不要对链接应用任何样式或用引号将其括起来。

对于指向其他页面的链接：See [AUTOTITLE](/PATH/TO/PAGE).
对于指向其他页面中各部分的链接：For more information, see [AUTOTITLE](/PATH/TO/PAGE#SECTION-LINK).

请勿使用内联链接，其中句子中的字词带有超链接，没有任何其他字词来表明该句子包含链接。这可能很难转换和阅读。

请不要在超链接中包含标点符号。

使用： 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), later in this article.

同页不同部分链接不适用于 AUTOTITLE。必需键入完整标题文本。

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

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.

指向外部资源的链接

链接到外部站点时，为链接上下文选择最有用的资源。如果它是常规引用，可链接到整个网站，也可以链接到特定页面，这样将更有用。

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

键入完整的页标题和目的地址，获取外部页面（任何不由 GitHub 托管的网站）的链接。请勿将链接置于引号中。

使用：See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE) in the XYZ documentation.****
避免： See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE).
避免： See [the OTHER WEBSITE](https://some-docs.com/PATH/TO/PAGE).

添加定位点来保留链接

如果知道文章的特定章节有链接，则可以给相应章节添加定位点来保留链接。例如，假设某个外部资源链接到文章的特定章节，则可以添加一个定位点，从而确保即使章节标题发生更改，链接也会指向正确的章节。

此格式用于链接定位点。定位点名称应为要保留的章节名称。使用 HTML 注释来说明添加定位点的原因。

<!-- Anchor to maintain the current example link. -->
<a name="SECTION-TITLE-THAT-MIGHT-CHANGE"></a>

列表

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

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

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

设置无序列表的格式：

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

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

使用：****

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

避免：

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

权限语句和产品标注

使用权限语句和产品标注来传达需要特定角色或产品才能完成的任务。

权限语句：采取措施或执行本文中所述的任务所需的角色。示例：“企业所有者”。
产品标注：采取措施或执行本文中所述的任务所需的一个或多个产品。示例：“订阅了 Copilot Business 的组织和企业帐户。”

权限语句和产品标注相结合，告诉读者谁可以使用文章中所述的功能。

创建可扫描产品标注的指南

定义权限与产品要求

考虑权限语句或产品标注中的信息。

例如，为“管理组织中的 Copilot 策略”一文创建权限和产品标注时，权限语句将回答“在组织中，什么角色可以管理 GitHub Copilot 的策略和功能？” 产品标注将回答“用户需要哪些 Copilot 订阅来管理组织的 Copilot 策略和功能？”

关注关键信息，而不是说明

权限语句和产品标注需要传达谁可以执行任务以及需要什么产品。他们不需要解释为什么需要角色或者产品。

如果多个角色或产品应用于一个权限语句或产品标注，请使用无序列表对其进行格式化。可以用一句话介绍复杂的权限语句和产品标注，但始终尽量少用一些必要的字词来传达谁执行操作以及文章内容。

使用内联链接

可以使用内联链接提供有关角色或产品的更多信息。链接的文本必须与链接的目的地相匹配，以便清楚地了解链接定向至的位置。

占位符

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

使用：****

在以下示例中，将 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@v4

第三方操作的免责声明

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

# 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 %} 可重用代码。

对于 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”（一个词），除了在文件/路径名中。单个词的形式可能被视为品牌名称，我们希望避免这种情况，同时也希望与 the 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 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 的详细信息，请参阅“管理个人访问令牌”。

标点

请遵循标准美式英语标点规则。有关更多指导，请参阅 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) 有关详细信息，请参阅 ARTICLE TITLE (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。例如，在“关于身份和访问管理”中，用户应该阅读并考虑与其企业相关的每个部分。本文中不包括分区 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	否

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

包含每个单元格的值

表中的每个单元格都必须包含一个值。

对于没有数据的单元格，请使用“无”或“不适用”。请勿使用“NA”或“N/A”。

对于有行标题的表，第一个单元格（单元格“A1”）应用于描述行标题，以帮助了解整个表。但是，如果这样做会降低表的明确性或增加多余信息，则可以将此单元格留空。例如，在“构建和测试 PowerShell”一文中，第一个单元格可以标注为“Modules”，但由于每一行的标题都已包含“module”一词，因此此标题的信息将是重复的，不会增加有助理解整个表的描述价值。

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

对于使用符号的表：

填充所有单元格。例如，在权限表中，不要只标记需要权限的内容的单元格。
请使用图标或 SVG。请勿使用表情符号。有关图标的详细信息，请参阅“在 GitHub Docs 中使用 Markdown 和 Liquid”。
对肯定值（“是”、“必需”、“支持”）使用勾号，对否定值（“否”、“可选”、“不支持”）使用叉号。
请使用 aria-label 来描述符号的含义，而不是其视觉特征。例如，“必需”，而不是“勾号图标”。

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

请谨慎使用脚注

请参阅脚注。

一致地对齐表内容

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

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

以下示例显示了“Dependabot options reference”中的表的一部分。

选项	必需	安全更新	版本更新	说明
`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 |

Titles

标题使用句首大写形式。

短标题

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

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

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

网站政策内容

请勿在网站政策内容中使用可重用内容或变量。网站政策文章是法律文档，必须使用人类可读来源。

或者，网站政策内容可以使用与 GitHub Docs 的其余部分相同的样式和内容模型。

用户界面元素

粗体

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

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

分支名称

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

main
USERNAME.github.io

按钮

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

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

复选框

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

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

动态文本

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

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

列表和列表项

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

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

位置

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

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

面板

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

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

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

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

单选按钮

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

存储库名称。

使用反引号在固定宽度字体中设置存储库名称的样式。当预期用户导航到存储库时，请提供存储库的链接。

使用： 有关详细信息，请参阅 github/docs 存储库。

响应式元素

我们仅在 UI 元素产生歧义或混乱时记录它们的响应状态。如果由于响应式 UI 元素而导致任务不清楚，请描述某人为实现任务目标必须进行的交互。不要只描述 UI 元素的视觉状态。

用法： 单击“安全性”。如果“安全性”不可见，请单击 ⋮ 展开存储库菜单。

用户界面文本

引用用户界面中的文本时，请准确重现文本。使用引号将无法与之交互的 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

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

带 Enterprise Managed Users 的 GitHub Enterprise Cloud
- 使用：**** 借助Enterprise Managed Users，可以创建和管理企业成员的用户帐户。
- 避免：**** 借助Enterprise Managed Users，可以创建和管理企业成员的个人帐户。
GitHub Enterprise Server
- 使用：**** 如果需要暂时接管用户帐户……
- 避免：**** 如果需要暂时接管个人帐户……

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

“企业管理员文档”产品
企业特定的计费文档，如“关于企业的计费”
面向管理受众的其他产品中的内容，例如“代码安全”产品中的“确保帐户安全的最佳做法”或“入门”产品中的“设置 GitHub Enterprise Cloud 试用版”
企业特定的 API 内容，例如“适用于 GitHub Enterprise 管理的 REST API 终结点”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。

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

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

权限

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

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

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

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

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

使用：**** 要创建自定义存储库角色，请选择继承的角色，然后添加单个权限。
使用：**** 管理团队对组织存储库的访问权限
使用：**** 如果团队成员身份提供的访问权限级别与组织所有者角色所拥有的权限不同……
使用：**** 具有写权限的人员可以……
避免： 具有写权限的人员可以...
避免：**** 具有写入角色的人员可以……
避免：**** 具有写入权限的人员可以……
避免：**** 具有写入特权的人员可以……

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

使用：**** 具有存储库写权限的人员可以对存储库执行 X 操作。
避免：**** 组织所有者和具有写问权限的人员可以对存储库执行 X 操作。

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

介词

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

产品名称

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

使用或避免的术语

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