样式指南

请遵循本指南，确保 GitHub 的文档保持一致，并遵循读者能够理解的清晰模式。

本文内容

注意

这些指南专用于 GitHub 的文档。有关通用样式问题或本指南未覆盖的主题，请参阅 Microsoft Style Guide（微软样式指南）。有关 docs.github.com 上源内容的标记，请参阅 使用 Markdown 和 Liquid 编写 GitHub 文档。如有关于 GitHub 品牌的任何问题，请查看我们的 GitHub 品牌指南。

GitHub 文档的风格方法

  • 我们的风格指南追求简洁。指南应易于在各种情境中应用。
  • 决策并非依据语法规则或风格指南的对错，而是以何种方式对用户最佳。我们保持灵活与开放，同时维持一致性。
  • 为随团队与文档集的扩展而扩展风格指南，并创建高质量、有意义的内容服务用户，我们聚焦于高影响、高价值的场景，而不是尝试全面覆盖每一个风格问题。
  • 一致性和语法正确性很重要，但不如清晰度和含义重要。
  • 在做出风格或结构决策时，我们会考虑内容单元内部的信息流以及信息的上下文。
  • 当帮助文档的特定问题未被风格指南覆盖时，我们会使用这些原则进行思考并作出决定。如果审阅者询问，我们已准备好讨论该决定。

审计日志事件

我们记录每种账户（用户、组织和企业）在审计日志中可能出现的所有事件。

编写审计日志事件的描述时，请使用过去式和被动语态，以适用于所有版本的方式描述所发生的事件。不要以文章上下文已暗示的短语开头，例如 “Triggered by”。

  • 使用： 代码库的可见性已更改。
  • 使用： 已为所有新代码库启用机密扫描。
  • 避免： 组织所有者为组织禁用了双因素身份验证要求。
  • 避免： 当用户更新代码空间可访问的代码库时触发。

警报

警报用于强调文章中具有特殊重要性的信息，并且此类信息需要打断信息流。

请节制使用警报。不要连续出现多个警报，也不要在同一章节中出现超过一个警报。

警报应保持简洁。若信息超过几句话或需要有序/无序列表，请考虑将信息放在章节标题下。

警报类型

我们使用五种警报类型：注释、技巧、重要、警告和注意。

注释

提供用户在特定情境下可能需要考虑的补充信息。任务可以在没有注释信息的情况下完成，但在某些情境下，用户可能会受益于注释。

注释特别适用于传达与所描述过程非核心的括号信息。

  • 可能影响过程结果的注意事项，例如特定的用户设置。
  • 受可用性变更影响的产品和功能，例如处于公开预览或即将下线的功能。

例如，评估来自密钥扫描的警报 使用注释告知用户 GitHub 令牌元数据目前处于公开预览并可能会更改。

注意

GitHub 令牌的元数据目前处于公开预览，可能会更改。

技巧

推荐、最佳实践或产品提示。技巧包含非必需信息，用户可自行决定是否采纳。对新手用户的文章特别有用。

例如，个性化你的个人资料 使用技巧提醒用户在 @提及组织时会有什么表现。

提示

当你 @提及组织时，仅会自动补全你所属的组织。仍可 @提及你不属于的组织（例如前雇主），但组织名称不会自动补全。

重要

强调用户完成目标所需了解的关键信息。

重要提示

Runner Scale Sets 不支持多个标签，只有运行器名称可用作标签。参见 使用 Actions Runner Controller 部署 Runner Scale Sets。

警告

突出用户在开始或继续任务前需了解的潜在风险。

警告警报特别适用于在 GitHub UI 之外进行的过程，例如在命令行或通过 API。

例如，关于 SSH 证书颁发机构 包含命令行说明，并使用警告提醒用户证书签发后不可撤销。

警告

证书签发后无法撤销。请务必使用 -V 标志设置证书的有效期，否则证书将可永久使用。

注意

警告用户存在危险或破坏性操作，需要在执行前格外小心，尤其是涉及安全风险或潜在数据丢失的情况。

注意警报通常仅在描述 GitHub UI 之外的过程（如命令行或 API）时才必要。

警报格式

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

警报通过 Markdown 渲染。

注意

> [!NOTE]
> Keep this in mind.

提示

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

警告

> [!WARNING]
> Be careful.

注意

> [!CAUTION]
> Be extremely careful.

仍然支持使用 Liquid 语法的警报，旧文章中可能出现，但新警报不应使用。

有关警报格式的更多信息，请参阅 使用 Markdown 和 Liquid 编写 GitHub 文档 中的 “警报”。

号召性用语 (CTA)

CTA 是指引用户进行下一步操作的链接或按钮，会将用户发送到不同位置。

CTA 的关键在于帮助用户完成其意图，要么指引其进入下一步，要么引导其前往所需的产品或功能。

在决定何时使用 CTA 时，请思考以下问题：

  • 用户是否有逻辑上或必要的下一步？这可能是他们需要的下一条信息，或能帮助他们完成任务的功能。
  • 是否存在业务需求需要将用户送往该位置？

只有在上述两个问题答案均为肯定时，才应使用 CTA。

CTA 是对用户的明确指示，要求其立即行动，例如 “免费试用 Copilot” 或 “创建你自己的代码库”。文档中的 CTA 仅应指向 GitHub 所拥有的域名。

例如，设置 GitHub Enterprise Cloud 试用 的 CTA 链接到 GitHub.com 上的企业销售页面。

构建 CTA

要构建有效的 CTA URL 并附带正确参数，请在文档仓库的检出目录中使用 CTA 构建脚本。

npm run cta-builder

脚本将通过交互式流程引导你完成以下步骤：

  • 选择适当的 GitHub 产品（ref_product）
    • 当链接未针对特定功能或产品时，默认使用 github
  • 选择操作类型（ref_type）
  • 指定格式样式（ref_style）
  • 可选地选择特定计划（ref_plan）

脚本会提供每个参数的所有可用选项，并在最后生成完整且有效的 CTA URL。使用此工具可确保使用当前获批的 CTA 参数值。

例如，脚本可能生成如下 URL：

https://github.com/account/enterprises/new?ref_product=ghec&ref_type=trial&ref_style=button&ref_plan=enterprise

代码

代码块

保持代码示例每行约 60 个字符，以避免读者在代码块中水平滚动。将解释性文字放在代码块前，而不是在代码块内部使用注释。更多关于代码块语法和格式的信息，请参阅 使用 Markdown 和 Liquid 编写 GitHub 文档。

代码块内部

  • 在第一个代码围栏后指定示例语言。所有受支持语言列表请参阅 代码语言（位于 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

不要在命令前加入 $ 等提示符。避免在命令名称中使用内联链接。

输出

如果展示了命令的输出，请在示例中对输出进行注释，以便读者可以直接复制粘贴命令并运行。

  • 使用

    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 示例（如 actions 与工作流文件）中，请使用两个空格来缩进嵌套列表和块序列中的行。

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

关于可重用组件的缩进，请参阅 data/reusables/README.md。

计划工作流

当一次运行过多工作流时，工作流运行会被延迟。由于许多用户会复制 GitHub 文档中的代码，我们应使用能够引导用户避开高峰时段的示例。

  • 不要使用在整点运行的示例，因为这些是最拥挤的时段。
  • 不要使用频率超过实际需求的示例。例如，不要每五分钟运行一次，而应考虑是否可以改为每 30 分钟运行一次。
  • 为每个示例使用不同的时间。

强调

使用粗体强调词语或句子的一部分。请节制使用（不超过连续五个词），并记住粗体仅是为视力用户提供可扫描的视觉辅助。

  • 不要对已有其他格式（如全大写占位符）的词语使用粗体。
  • 出于可访问性考虑，请勿仅使用粗体来传达意义或强调。

例如

  • 使用： 管理用户账户 不能创建公开内容 或在你的企业外协作。
  • 避免： 在 Title 旁添加描述性标签以标识新密钥。

错误信息

在文章中包含 GitHub 产品或界面中的错误信息文本时，请根据错误出现的界面进行相应格式化。

  • 如果错误出现在 GitHub 的网页界面或图形客户端（如 GitHub Desktop、GitHub Mobile），请将其视作 UI 中的普通文本进行处理。更多信息请参阅 用户界面文字。

  • 如果错误出现在命令行界面、日志输出或 API 响应中，请完整复制文本并使用反引号将其格式化为单间距字体。

即将过期的内容

一般情况下，请勿记录将会过期的内容。访问 GitHub 文档的用户应确信信息准确且是最新的。

如果必须记录已知会过期的内容，可使用内容检查器为该内容打上到期标签并跟踪到期日期。这会将内容标记为过时，并避免在内容本体之外单独跟踪到期日期。请参阅 使用内容检查器 了解如何为即将过期的内容打标签。

脚注

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

如果必须使用脚注，请使用 Markdown 原生脚注（[^1]）。脚注标记将超链接到页面底部的脚注引用，底部会列出并带有返回标记的链接。

请注意，无论使用何种标识符（字母、单词），脚注最终都会渲染为顺序编号。

MonaUrsulaPaulDavy Jones1
最喜爱的业余爱好发布代码戏弄美人鱼2预测体育赛事缠绕航海者
利用力量行善是否是否
| | 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 界面使用说明，这类说明应放在文章正文中。
格式

Screenshot of the Product name + UI element shown. The UI element + state of the element/controls, and its keyboard shortcut XYZ, are outlined in dark orange.

  • 对于 Product name，请使用 GitHub 产品或功能的正式名称，例如 “GitHub Actions” 或 “GitHub repository”，而不是仅仅 “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…” 以避免连串名词。
示例

Screenshot of the GitHub committers by repository table. The horizontal kebab icon and "Download CSV report" button are outlined in dark orange.

Screenshot of file options in a GitHub repository. A button with an arrow indicating a dropdown menu, labeled "Code," is outlined in dark orange.

Screenshot of file options in a GitHub repository. A button with an arrow indicating a dropdown menu, labeled "Code," is outlined in dark orange.

图表的替代文本

在页面文字中解释图表所传达的信息。

使用替代文本表达图像的核心理念，而不要重复网页正文。

示例

Diagram showing a five-step process by which a GitHub Actions runner can be automatically added to named classes of runners and then requested by specific jobs.

例如，请参阅 Actions 文档中对该图的说明。

命令行界面图像的替代文本

不要使用命令行界面的截图来传递命令及其输出。请直接提供用户应使用的命令。更多信息请参阅风格指南的 命令 部分。

在使用命令行界面截图来展示 UI 元素时，请遵循截图的标准替代文本指南。

图像文件名

为图像文件命名时请具描述性：包括名称、动作和 UI 元素。遵循产品语言，使用 kebab case。文件名中不要使用 Liquid 条件表达式。如需替换图像，请使用完全相同的文件名。

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

截图

想了解创建与版本化图像的方式，请参阅 创建与更新截图。

图表

想了解创建图表的方式，请参阅 为 GitHub 文档创建图表。

包容性语言

作为全球最大开发者社区的所在地，GitHub 致力于在我们所做的每件事中促进多样性和包容性。我们的所有文档都面向全球各地、处境各异的受众，保持包容和尊重。在撰写文档时，我们使用包容、反种族主义且可访问的用词。

单个词语可能微小，但它们的聚合能营造社区、归属感和公平。所有词汇与风格选择都应富有同理心，准确指代人物与社区。

使用避免
白名单白名单
黑名单黑名单
默认/主分支主分支

关于包容性语言的资源

Microsoft Style Guide（微软样式指南）提供了关于无偏见沟通、无障碍术语以及面向所有能力的写作资源。

更多学习包容性和可访问性语言与风格的资源

键盘快捷键

展示键盘快捷键时，请遵循 Microsoft Style Guide（微软样式指南），但以下差异除外：

  • 对每个单独的键使用 HTML <kbd> 标签。

    • 使用： <kbd>Command</kbd>+<kbd>B</kbd>
    • 避免： Command+B

  • 对 Apple 修饰键使用全词而非符号。

    • 使用： Command
    • 避免： ⌘

  • 对特殊字符键使用符号而非全词。

    • 使用： ., ,, and →.
    • 避免： Period, Comma, and 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) or Ctrl+B (Windows / Linux)

    • 避免： <kbd>Ctrl</kbd>+<kbd>B</kbd> or <kbd>Command</kbd>+<kbd>B</kbd>，显示为：

      Ctrl+B or 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 查询参数。（这应是极少出现的情况。）

如果上下文已足够明确，您可以仅使用动词 “see” 来引入链接。若上下文不清晰，请使用短语或完整句子引入链接，例如 “更多信息，请参见” 或 “想了解 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 站点发布（免费、Pro 与 Team 版本）可能会链接到同一文章的 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: Something that provides bar.
  • bar: Something provided by foo.

无序列表格式化

  • 如果列表项的顺序不重要，请按字母顺序排列。
  • 如果顺序重要，请按对读者的重要程度排序（例如先列出面向最广受众的项，再列出更专业的受众）。
  • 列表项使用星号 (*)。

在引入列表时，避免使用“以下”“这些”等简短、缺乏特定信息的句子，这类表达难以本地化。请使用描述性句子清晰说明列表主题，并保证列表可随时增删而无需更改引导句。

使用

  • 有关 GitHub 的入门，请参阅以下文章：
  • 短信验证在这些国家/地区受支持：

避免

  • 有多篇文章提供了 GitHub 的入门介绍。请参见以下内容：
  • 短信验证在 50 个国家/地区受支持，具体包括：

权限声明与产品提示

使用权限声明和产品提示来传达完成任务所需的特定角色或产品。

  • 权限声明：执行文章中描述的操作或任务所需的角色。例如：“Enterprise owners”。
  • 产品提示：执行文章中描述的操作或任务所需的产品。例如：“拥有 Copilot Business 订阅的组织与企业账户”。

权限声明和产品提示共同告诉读者谁可以使用文章中描述的功能。

创建易于浏览的产品提示指南

区分权限与产品需求

思考哪些信息应放入权限声明或产品提示。

例如，在为文章 管理组织中的 GitHub Copilot 策略与功能 创建权限声明和产品提示时，权限声明要回答：“哪个角色可以管理组织中 GitHub Copilot 的策略和功能？”而产品提示要回答：“用户需要哪些 Copilot 订阅才能管理组织中的 Copilot 策略和功能？”

关注关键信息，而非解释

权限声明和产品提示只需说明谁能执行任务以及需要哪款产品，无需解释为何需要该角色或产品。

如果同一声明或提示涉及多个角色或产品，请使用无序列表进行格式化。您可以用一句话引入复杂的声明，但始终尽可能使用最少的词语来传达谁可以做什么。

可以使用内联链接提供关于角色或产品的更多信息。链接文本必须与链接目标保持一致，以便读者清楚点击后将前往何处。

占位符

所有占位符文本请使用全大写。如果占位符包含多个单词，请使用连字符（kebab‑case）连接。使用占位符时，请说明用户应将其替换为何物，这有助于读者根据自身需求修改示例，也方便使用辅助技术的用户辨识占位符。

使用

  • 在下面的示例中，将 YOUR-REPOSITORY 替换为您仓库的名称。git init YOUR-REPOSITORY
  • 点击 Add USERNAME. 其中 USERNAME 为您想要添加的用户的用户名。

避免

  • git init your repository
  • git init <your-repository>
  • 点击 Add username.

步骤说明

程序化步骤向读者提供完成任务的顺序步骤。始终使用编号列表来编写程序化步骤。请在步骤前提供完成任务所需的全部前置条件或概念信息，而不是把这些信息嵌入某一步骤中。

每一步必须包含一个动作。您也可以标明该步骤是否可选，解释该步骤的原因或结果，并在指导用户执行动作前说明该动作所在的位置。

在每一步内部信息的呈现顺序应保持一致。

  1. 如果该步骤为可选，请首先标明。
  2. 为提升清晰度或强调破坏性/易混淆操作的严重性，可解释该步骤的原因或结果。
  3. 描述用户将在何处找到该操作。
  4. 动作本身。

使用示例： 可选地，为了 REASON，在 LOCATION，执行 ACTION。

示例

  • 点击 Payment information。
  • 在组织名称下，点击 Settings。
  • 为确认更改，点击 Remove credit card。
  • 可选地，若想查看套餐详情，点击 Show details。
  • 在 “GitHub Sponsors” 下，已赞助的开源贡献者右侧，点击您已赞助的金额旁边，然后点击 Change tier。

产品名称

请使用完整的产品名称。除非直接复制 UI 文案或 API 响应等原始内容，否则不要缩写或简写产品名称。产品名称不应使用所有格形式。

使用产品名称变量来渲染产品名称——不要在纯文本中直接写产品名称。这有助于在全站范围内更轻松地完成产品名称的变更，并避免拼写错误。有关产品名称变量的更多信息，请参见本文档中的 “Reusables and variables” 章节以及 data 目录（位于 github/docs 仓库中）。

产品名称始终使用单数形式。

  • 使用示例： GitHub Actions 帮助您自动化软件开发工作流。
  • 避免示例： GitHub Actions 帮助您自动化软件开发工作流。

请注意区分产品名称与产品功能。产品功能始终使用小写。

产品功能
GitHub Actionsan action
GitHub Codespacesa codespace
GitHub 包a package
GitHub Pagesa GitHub Pages site

不要对常用功能（如 pull request、topic 或 issue）进行首字母大写。

产品特定约定

本节介绍特定于 GitHub 产品的额外约定。

GitHub Actions

官方行动的可复用代码块

使用官方行动的代码示例必须使用对应的可复用代码块。这有助于在需要将动作版本从 v1 升级到 v2 时，更轻松地在如 GitHub Enterprise Server 等产品中进行管理，因为后者可能在后续版本中才提供相同的动作版本。

官方行动的可复用文件位于 /data/reusables/actions/，文件名形如 action-<action_name>.md

例如，要在示例中使用 actions/checkout 动作，请使用相应的可复用文件。

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

对于 GitHub Docs 来说，官方行动指所有以 actions/、github/ 或 octo-org/ 为前缀的动作。例如，以下即为官方行动：

steps:
  - uses: actions/checkout@v5

第三方行动的免责声明

使用第三方行动的代码示例必须在代码块中加入以下免责声明。

# 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

更多信息请参见 Using SHAs。

Codespaces

在提及产品 Codespaces 时，始终使用 “GitHub”，除非满足以下情况：

  • 在 shortTitle front‑matter 中。
  • 在文章内部的副标题中，如果 “Codespaces” 已在文章的其他位置出现过。

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

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

始终使用 “dev container”（或在需要说明时使用更长的 “development container”），而非 “devcontainer”（单词形式），除非在文件/路径名中。单词形式可能被视作品牌名称，我们应避免使用，并且应与 Visual Studio Code 文档 中的两词形式保持一致。

使用 “development container configuration files” 来指代 .devcontainer 目录下的所有文件（以及若使用 .devcontainer.json 而非 devcontainer.json 时的该文件）。请勿称其为 “development container files” 或 “devcontainer files”，以免被误认为指 devcontainer.json 文件。“development container configuration files” 包括可用于配置 dev container 的所有文件，如 Dockerfile 与 compose.yaml。在仅指 devcontainer.json 文件时，请使用其完整文件名，而非统一的 “the development container configuration file”。

GitHub Advanced Security（GHAS）产品

提及 GitHub Advanced Security、GitHub Code Security 或 GitHub Secret Protection 计费时，请使用术语 licenses 与 active committers。

我们过去使用 “seats” 来描述企业中可使用 GitHub Advanced Security、GitHub Code Security 或 GitHub Secret Protection 的账户数量。由于 “seats” 易导致混淆，我们已于 2022 年秋季将其从 GitHub.com 中移除，GHES 3.7 及以后版本也不再使用。

个人访问令牌

GitHub 拥有两类个人访问令牌

  • 细粒度个人访问令牌：对仓库访问和权限提供颗粒度更细的控制
  • 传统个人访问令牌（classic）：使用作用域并授予对令牌所有者可访问的所有仓库的访问权限

请使用变量来指代这些令牌类型，以及指代个人访问令牌的通用称呼。

  • 使用 {% data variables.product.pat_generic %} 或 {% data variables.product.pat_generic_caps %} 来指代通用个人访问令牌。若需标题大小写（如 UI 文本）请使用 {% data variables.product.pat_generic_title_case %}（“Personal Access Token”）。
  • 使用 {% data variables.product.pat_v2 %} 或 {% data variables.product.pat_v2_caps %} 来指代细粒度个人访问令牌。
  • 使用 {% data variables.product.pat_v1 %}、{% data variables.product.pat_v1_plural %}、{% data variables.product.pat_v1_caps %} 或 {% data variables.product.pat_v1_caps_plural %} 来指代传统个人访问令牌（classic）。

欲了解 GitHub 个人访问令牌的更多信息，请参见 Managing your personal access tokens。

标点符号

遵循标准美式英语标点规则。更多指导请参见 Microsoft Style Guide 中的 “Punctuation”。

发行说明

GitHub Docs 中的发行说明向读者说明针对如 GitHub Enterprise Server（GHES）等版本化产品的管理员或用户层面的更改。发行说明位于 Release notes 页面。

优秀的发行说明仅用几句话按顺序回答读者对更改的疑问。更多信息请参见 Release note content type。

每条发行说明描述以下其中一种更改。

  • Features：全新行为或功能
  • Security fixes：具有安全影响的缺陷或异常行为的修复
  • Bug fixes：缺陷或异常行为的修复
  • Changes：对既有行为的显著变更
  • Known issues：GitHub 已识别但尚未优先处理的问题
  • Closing down：正在退役的功能或产品，未来不再受支持
  • Retired：产品或功能生命周期结束
  • Errata：对不准确的发行说明或文档的更正

您还可以在 Adding or updating a release note 与 Removing a release note 中查看更新发行说明的指南。

功能

功能的发行说明概述全新行为。通常，功能发行说明仅出现在功能发布版本中。

编写功能发行说明

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

  1. 此新功能是否适用于我的角色或权限？
  2. 该功能满足了什么需求？
  3. 该功能是什么？
  4. 如适用，我可以在哪里了解更多关于此功能的信息？

AUDIENCE（1）可以 DESCRIPTION OF NEED（2）通过 DESCRIPTION OF FEATURE'S USE（3）。更多信息请参见 ARTICLE TITLE（4）。

  • 请在对应的功能标题下为每个功能归类。
  • 使用现在时撰写。
  • 为减少重复和冗余词汇，“now” 通常是隐含的。
  • 为明确行为主体和影响，尽量避免使用被动语态。

功能发行说明示例

  • 站点管理员可通过配置登录尝试的速率限制以及超出速率限制后的锁定时长，提升 Management Console 的安全性。更多信息请参见 Configuring rate limits。

  • Enterprise owners 可控制用户 Fork 仓库的范围。Fork 可限制为预设的组织组合、与父仓库相同的组织、用户账户或全部。更多信息请参见 Enforcing repository management policies in your enterprise。

  • 用户可创建包含 geoJSON、topoJSON 与 STL 图表的文件，并在网页界面中渲染这些图表。更多信息请参见 Working with non-code files。

安全修复

安全修复的发行说明概述可缓解或防止产品中安全相关问题被利用的更改。通常，安全修复仅出现在补丁发布版本中。

编写安全修复发行说明

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

  1. 若有提供，针对该漏洞的 NVD 漏洞严重性等级 是多少？
  2. 攻击者利用该漏洞可能实现何种攻击？
  3. 该漏洞属于哪种可被利用的类型？
  4. 若有提供，漏洞的 CVE 编号 是什么（已发布或待发布）？
  5. 是否有人通过 GitHub Bug Bounty 项目 报告了该漏洞？

SEVERITY（1）：攻击者可能通过 DESCRIPTION OF EXPLOIT（3）对 DESCRIPTION OF IMPACT（2）造成影响。GitHub 已为此漏洞申请 CVE 编号 CVE-####-#####（4），该漏洞通过 GitHub Bug Bounty 项目（5）报告。

安全修复发行说明示例

  • MEDIUM: 攻击者可通过对 Markdown REST API 发起并行请求导致实例资源耗尽。为缓解此问题，GitHub 已更新 CommonMarker。GitHub 已为该漏洞申请 CVE 编号 CVE-2022-39209。

  • MEDIUM: 攻击者可在实例的 Web UI 中嵌入危险链接，因为 Pull Request 预览链接未正确清理 URL。该漏洞通过 GitHub Bug Bounty 项目 报告。

基础镜像与软件包更新

我们也将在 “Security fixes” 部分列出基础镜像与依赖包的更新，因为这些更新往往涉及安全问题。以下说明将所有此类更新汇总。

已将软件包更新至最新的安全版本。

缺陷修复

缺陷修复的发行说明描述对不期望或异常行为的更正。通常，缺陷修复仅出现在补丁发布版本中。

编写缺陷修复发行说明

缺陷修复的发行说明应回答以下问题。

  1. 该行为是否会影响到我的角色或权限？
  2. 在修复前，读者会遇到什么行为？

AUDIENCE（1）DESCRIPTION OF BEHAVIOR（2）。

  • 由于缺陷已修复，请使用过去式撰写。
  • 诸如 “fixed a bug…” 或 “fixed an issue…” 等表述已隐含且不必出现。
  • 为减少重复和冗余词汇，“now” 通常是隐含的。
  • 为明确行为主体和影响，尽量避免使用被动语态。
  • 若发行说明中包含错误信息，请按 Error messages 中的指引进行格式化。

缺陷修复发行说明示例

  • 在用户导入启用了推送保护的仓库后，仓库未立即出现在安全概览的 “Security Coverage” 视图中。

  • 在启用了 GitHub Actions 的实例上，如果在作业首次排队时匹配的运行器组不可用，即使随后匹配的运行器组可用，GitHub Actions 工作流作业也不会启动。

  • 站点管理员通过 SSH 在任意实例节点上执行的命令未记录到 /var/log/ssh-console-audit.log 中。

变更

变更的发行说明描述对既有行为的显著但不大的修改。变更的发行说明回答以下问题。

编写变更发行说明

变更的发行说明应回答以下问题。

  1. 该行为是否会影响到我的角色或权限？
  2. 如果此变更解决或规避了某个问题，该问题是什么？
  3. 新的行为是什么？
  4. 如相关，此变更前的行为是什么？

AUDIENCE（1）/ DESCRIPTION OF PROBLEM CHANGE SOLVES（2）DESCRIPTION OF NEW BEHAVIOR（3）DESCRIPTION OF OLD BEHAVIOR（4）。

  • 由于该变更适用于当前发布版本，请使用现在时撰写。
  • 为减少重复和冗余词汇，“now” 通常是隐含的。
  • 为明确行为主体和影响，尽量避免使用被动语态。
  • 通常，受众是隐含的。
  • 如有帮助，请在文中加入指向 GitHub Docs 的相关链接。

变更发行说明示例

  • 在拥有 GitHub Advanced Security 或 GitHub Secret Protection 许可证的实例上，用户在为 secret scanning 编写自定义模式时，可以提供必须匹配或必须不匹配的表达式，长度最多可达 2,000 个字符。此限制比之前的 1,000 个字符有所提升。

  • 对于需要审查或修改 SAML 映射的管理员，ghe-saml-mapping-csv -d 的默认输出路径已从 /tmp 改为 /data/user/tmp。更多信息请参阅 命令行工具。

  • 为避免在具有多个节点的实例上 Git 操作成功出现间歇性问题，GitHub Enterprise Server 在尝试执行 SQL 查询前会检查 MySQL 容器的状态。超时时间也已缩短。

已知问题

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

编写已知问题的发行说明

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

  1. 此行为是否影响我，取决于我的角色或访问权限？
  2. 出现了哪些错误信息或其他可识别的 UI 元素？
  3. 我是否需要采取行动？如果需要，我该怎么做？

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

  • 为明确行为主体和影响，尽量避免使用被动语态。
  • 为减少重复和冗余词汇，“now” 通常是隐含的。
  • 若发行说明中包含错误信息，请按 Error messages 中的指引进行格式化。
  • 如有帮助，请在文中加入指向 GitHub Docs 的相关链接。
  • 已知问题也是 GitHub Docs 上的一种内容类型。更多信息请参阅 故障排查内容类型。如有必要，可在文档中编写或链接更深入且与上下文相关的内容。

已知问题发行说明示例

  • 在用户为仓库启用允许具有读取访问权限的用户创建讨论的选项后，该功能并未生效。

  • 管理员启动配置运行后，在 Notebook 和 Viewscreen 服务的验证阶段可能会出现 No such object error。此错误可忽略，因为服务仍应正常启动。

关闭

针对即将关闭的功能的发行说明概述了 GitHub 计划移除的行为或特性。这些功能仍可在生产环境中使用，并享有相应的支持 SLA 和技术支持义务。但它们正处于退役过程，不应再用于未来的工作。关闭是一种过渡阶段，建议用户停止使用该功能并为其退役做好准备。

编写即将关闭功能的发行说明

针对即将关闭的功能的发行说明会回答以下问题。

  1. 此现有功能是否适用于我，取决于我的角色或访问权限？
  2. 即将关闭的功能是什么？
  3. 如适用，什么取代了即将关闭的功能？
  4. 如适用，我可以在哪里了解更多信息？

受众 (1) 即将关闭功能的描述 (2) 替代功能 (3) 更多信息请参阅 文章标题 (4)。

  • 注释使用现在时，针对即将发生的更改使用将来时。如适用，请注明退役将发生的具体发行版本。
  • 为减少重复和冗余词汇，“now” 通常是隐含的。
  • 为明确行为主体和影响，尽量避免使用被动语态。
  • 请在对应的功能标题下为每个功能归类。

即将关闭功能的发行说明示例

  • 关闭： 在 GitHub Enterprise Server 3.8 及更高版本中，为确保实例安全，SSH 连接到管理 shell 时将禁用不安全的算法。

  • 提交评论（用户在不通过拉取请求的情况下直接在提交上添加的评论）不再显示在拉取请求时间线中。用户也无法回复或解决这些评论。Timeline events REST API 以及 GraphQL API 的 PullRequest 对象同样不再返回提交评论。

已退役

已退役的产品或功能不再面向新客户提供、进行营销、提供支持或编写文档。在此阶段，该产品实际上已停止，且不再进行新开发或修复。对已退役产品的唯一支持可能来自已有的承诺，例如对先前发布的 GitHub Enterprise Server 版本的要求。退役标志着产品或功能生命周期的正式结束，不再有更新、错误修复或用户支持，意味着完全转向更新的工具或服务。

编写已退役功能的发行说明

已退役功能的发行说明会回答以下问题。

  1. 此功能是否适用于我，取决于我的角色或访问权限？
  2. 已退役的功能是什么？
  3. 如适用，什么取代了已退役的功能？
  4. 如适用，我可以在哪里了解更多信息？

受众 (1) 已退役功能描述 (2) 替代功能 (3) 更多信息请参阅 文章标题 (4)

  • 注释使用现在时。
  • 为减少重复和冗余词汇，“now” 通常是隐含的。
  • 为明确行为主体和影响，尽量避免使用被动语态。
  • 请在对应的功能标题下为每个功能归类。

已退役功能的发行说明示例

  • 已退役： 在 GitHub Enterprise Server 3.11 及更高版本中，GitHub 不再支持对 GitHub Actions 的必需工作流。请改用仓库规则集。更多信息请参阅 规则集可用规则。

勘误

勘误用于更正先前在发行说明或文档中发布的不准确信息。

编写勘误

勘误会回答以下问题。

  1. 如适用，发行说明或 GitHub Docs 中的哪个章节受到了影响？
  2. 不准确信息是否影响到我，取决于我的角色或访问权限？
  3. 发行说明或文档中哪些描述是不正确的？
  4. 勘误发布时间是什么时候？

内容 (1) 错误地表明 受众 (2) 可以 不准确信息摘要 (3)。 [更新：发布时间 4]

  • 请根据《添加或更新发行说明》中的指南格式化发布时间。

勘误示例

  • 功能 错误地显示 GitHub Advisory Database 的用户可以查看 Elixir、Erlang 的 Hex 包管理器等的 advisory。此功能在 GitHub Enterprise Server 3.7 中不可用，且将在未来的发行版中提供。 [更新于 2023-06-01]

添加或更新发行说明

为了向读者表明您已添加或更改了说明，或标示勘误的发布时间，请在末尾添加格式为“[Updated: YYYY-MM-DD]”的时间戳。

删除发行说明

若要表明我们已删除某条发行说明，请添加一个 “勘误” 部分，说明您删除了哪条说明以及（若相关）该说明对应的版本。参见 编写勘误。

发行版本引用

在引用从特定发行版开始的版本范围时，请使用 “或更高”。

  • 使用： “release 0.41.0 or later”
  • 避免： “release 0.41.0 or above”
  • 避免： “release 0.41.0 or greater”

可复用内容和变量

对单个名词（例如产品名称）或完整句子、段落使用可复用字符串。句子片段和短语不应放在可复用字符串中，以免本地化时出现问题。更多信息请参阅 data 目录 位于 github/docs 仓库中的内容、创建可复用内容，以及本文档的 产品名称 部分。

分段目录

如果文章的某一部分使用 H3 或 H4 标题进一步划分内容，而其中仅有部分内容与读者相关，您可以使用分段目录（TOC）帮助读者识别并导航到最相关的信息。例如，在 为企业流式传输审计日志 中，用户可能只会为某一提供商设置审计日志流式传输，因此 “设置审计日志流式传输” 部分的分段 TOC 允许用户选择其提供商并直接导航至相应内容，而无需阅读整段。

如果 H3 或 H4 标题仅用于对内容进行分组且所有信息都可能与读者相关，请不要添加分段 TOC。例如，在 身份与访问管理基础 中，用户应阅读并考虑每个章节与其企业的关联性。因此本文未加入分段 TOC，因为应逐章节阅读，而非挑选。此外，分段 TOC 会迫使使用屏幕阅读器或其他辅助技术的用户在寻找所需信息前遍历更多标题。

将分段 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 的信息。”
  • 避免： “下表显示导出的迁移数据类型。”

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

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

例如，在以下表格中，要理解表格中的 “Yes” 与 “No” 值，需要同时了解列标题（role）和行标题（permission）。

组织权限 所有者 成员 版主 账单管理员 安全管理员
创建仓库 是 是 是 否 是
查看和编辑账单信息 是 否 否 是 否
邀请人员加入组织 是 否 否 否 否

要为 Markdown 表格添加行标题，请将表格包裹在 Liquid 标签 {% rowheaders %} {% endrowheaders %} 中。有关使用行标题的更多信息，请参阅 在 GitHub Docs 中使用 Markdown 和 Liquid。

为每个单元格提供数值

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

对于没有数据的单元格，请使用 “None” 或 “Not applicable”。不要使用 “NA” 或 “N/A”。

对于带有行标题的表格，首个单元格（A1）应描述行标题，以帮助用户了解整个表格。然而，如果这样做会降低表格的清晰度或导致信息冗余，则可以留空。例如，在 构建和测试 PowerShell 文章中，首个单元格本可标记为 “Modules”，但由于每个行标题已包含 “module” 一词，添加此标题会重复且无增值。

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

针对使用符号的表格

  • 为所有单元格填充值。例如，在权限表中，不要仅标记需要权限的单元格。
  • 使用 octicon 或 SVG。不要使用表情符号。有关 octicon 的更多信息，请参阅 在 GitHub Docs 中使用 Markdown 和 Liquid。
  • 使用 对勾 表示肯定值（“Yes”、“Required”、“Supported”），使用 叉号 表示否定值（“No”、“Optional”、“Unsupported”）。
  • 使用 aria-label 描述符号的含义，而不是其视觉特征。例如，使用 “Required”，而不是 “Check mark icon”。

如果表格数据并非真正的二元（例如每个值不是仅 “Yes” 或 “No”），则可能需要使用文本值来补充或替代符号。例如，在页面 关于 GitHub 支持 中，一些功能标记为 “Available to purchase”。

谨慎使用脚注

参见 脚注。

保持表格内容对齐一致

表格中的所有列应左对齐，除仅包含 octicon 的列应居中对齐。如果列既包含文本又包含 octicon，则使用居中对齐。

表格内容默认左对齐。使用 Markdown 表格格式，在标题行的破折号两侧放置冒号（:）来指定每列的对齐方式。详见 在表格中组织信息。

以下示例展示了 Dependabot 选项参考 中表格的一部分。

选项 是否必填 安全更新 版本更新 描述
package-ecosystem 要使用的包管理器
目录 包清单的位置
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 |

标题

标题使用句子式大小写。

短标题

我们使用短标题来填充侧边栏导航。由于短标题出现在侧边栏导航中，可使用上下文传达含义，且可略微不如完整标题精确。短标题的目标是帮助用户找到所需内容，同时避免侧边栏导航项过长。短标题为文章提供上下文理解，并遵循以下标准。

  • 短标题为 2–3 个词。
    • 分类的短标题必须少于 27 个字符。
    • 映射主题的短标题必须少于 30 个字符。
    • 文章的短标题必须少于 31 个字符，理想长度在 20–25 个字符之间。
  • 短标题使用动词原形而非动名词。
    • 使用： “Configure notifications” 而不是 “Configuring notifications”。
  • 对于分类、映射主题和文章的短标题，如果能够明确其关联的产品或功能，可省略产品和功能名称。
  • 短标题不能引入完整标题中不存在的新词。
  • 相似内容的短标题应保持平行结构。
    • 使用： “Organizations and teams” 与 “Enterprise accounts”
    • 避免： “Organizations and teams” 与 “Managing enterprise accounts”

编写短标题可能具有挑战性。为使短标题符合字符限制，请考虑其在上下文中的使用。尽可能去除重复词汇以及与所在映射主题或分类已明确的产品或功能名称。

站点政策内容

站点政策内容中不要使用可复用内容或变量。站点政策文章是法律文档，必须具有人类可读的源文本。

站点政策内容在其它方面遵循与 GitHub Docs 其余部分相同的风格和内容模型。

用户界面元素

加粗

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

  • 在左侧边栏，单击 Billing。
  • 在拉取请求的 Conversation 选项卡底部的合并框中查看。
  • 在 Title 旁边，为新密钥添加描述性标签。

分支名称

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

  • main
  • USERNAME.github.io

按钮

将按钮名称加粗，并在可能的情况下省略 “button”。描述使用按钮时，使用 “click”，而非 push 或 press。

  • 使用： 单击 Pull request。
  • 避免： 按下 Pull request 按钮。

复选框

将复选框名称加粗，并省略 “checkbox”。描述选择或取消复选框时，使用 “select” 或 “deselect”。

  • 使用： 选择 Enable for all new repositories。
  • 避免： 勾选 “Enable for all new repositories” 复选框。

动态文本

使用大写字母表示用户界面中会变化的文本或用户在命令或代码片段中需要提供的内容。

  • 使用： 单击 Add USERNAME to REPONAME。

列表和列表项

将列表和可点击的列表项加粗。描述与列表交互（如下拉菜单或展开的 UI 元素）时，无论列表名称是文字还是 octicon，都使用 “select”。描述选择列表项时，使用 “click”。

  • 使用： 选择 Backup email addresses 下拉菜单并单击 Only allow primary email。
  • 避免： 单击 “Backup email addresses” 下拉菜单并单击 Only allow primary email。

位置

根据 WCAG 指南，我们应通过名称描述元素，而非仅凭外观或位置。Microsoft Style Guide 为方向性短语提供具体指导，强调在文档中的使用。

面板

如有可能，避免提及面板。相反，描述需要执行的操作。

  • 使用： 单击 View charts and graphs 以查看仓库，然后在下拉菜单中选择要查看的时间段。
  • 避免： 单击 View charts and graphs 打开所选仓库的面板，然后在下拉菜单中选择要查看的时间段。

如果必须提及面板以描述 UI 更改或解释如何与 UI 交互，请将面板名称格式化为 用户界面文本。仅在面板名称增加清晰度或面板在 UI 中没有名称时，才在名称中加入 “panel”。

  • 使用： 在 “Security coverage” 面板中，选择 Enable 或 Disable。
  • 使用： 在面板中，选择 Enable 或 Disable。

单选按钮

将单选按钮标签加粗，并省略 “radio button” 或其他描述词。描述使用单选按钮时，使用 “select”。

仓库名称

使用等宽字体并用反引号标记仓库名称。提供指向仓库的链接，以便用户导航。

  • 使用： 查看 github/docs 仓库以获取更多信息。

响应式元素

仅在响应式 UI 元素导致歧义或困惑时记录其状态。如果任务因响应式 UI 元素而不明确，请描述用户必须执行的交互来完成任务，而不是仅描述 UI 元素的视觉状态。

  • 使用： 单击 Security。如果未看到 Security，请单击 ⋮ 展开仓库菜单。

用户界面文本

在引用用户界面中的文本时，须完全复现该文本。对不可交互的 UI 文本使用引号。逗号置于引号外。

  • 使用： 在 “IP allow list” 下，单击 Edit。

更多资源

Microsoft Style Guide

视频

可以添加视频以强化基于文本的信息，但视频绝不能取代文字内容。视频对部分用户不可访问，也难以通过搜索发现。

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

语气与风格

使用清晰、简洁、易于各类读者理解的语言。写作时保持真实、富有同理心并自信。

写作时面向受众：某些行话和技术术语是必要的，但不要假设每位读者拥有相同的技术水平。

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

我们是全球开发者社区。避免使用特定地区或国家的惯用语、成语和俚语。

想了解更多关于写作亲切内容，请参阅“Microsoft 的品牌声音：首要原则，简洁且人性化”以及“Microsoft 风格与语调的十大技巧”。

用词选择与术语

有关通用指南和 GitHub 专有术语，请参阅我们的 术语表。更详尽的指导请参阅 Microsoft 风格指南中的 “A-Z 词汇表”。

缩写

除非产品本身明确使用缩写，否则应完整拼写单词。

  • 使用： Repository
  • 避免： Repo
  • 使用： 管理员，拥有管理员权限的人员
  • 避免： Admins

不要使用 GitHub 用户界面未使用的符号或 octicon。

  • 使用： 单击 File，然后单击 Edit。
  • 避免： 单击 File > Edit。

账户

产品名称和账户

为避免歧义和混淆，请勿在描述任何产品的账户时使用产品名称作形容词。应明确账户类型并使用更清晰的表述，避免将账户与产品混为一谈。谈及账户时，仅在需要在产品之间进行区分时才引用产品名称。更多关于 GitHub 产品中可用账户类型的信息，请参阅 GitHub 账户类型。

  • 使用： GitHub Enterprise Cloud 上的组织
  • 避免： 您的 GitHub Enterprise Cloud 账户
  • 避免： 您的 GitHub Enterprise Server 组织
  • 使用： 您可以通过将贡献计数发送到您的 GitHub.com 个人资料，来突出在 GitHub Enterprise Server 上的工作。

个人在 GitHub 上的账户

我们会根据上下文以不同方式称呼个人登录的账户。

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

  • 使用： 管理个人账户的计划提醒
  • 避免： 管理用户账户的计划提醒

企业产品的账户

在 GitHub 的企业产品中，管理员管理企业账户。企业账户可以拥有多个组织，个人用户账户可以成为这些组织的成员。更多信息请参阅每个产品的 “企业角色” 文章。

如果读者管理企业账户，并且您在描述他们管理的人员账户，请使用 “用户账户”。适用于以下产品。

  • 使用 Enterprise Managed Users 的 GitHub Enterprise Cloud
    • 使用： 使用 Enterprise Managed Users，您可以为企业成员创建并管理用户账户。
    • 避免： 使用 Enterprise Managed Users，您可以为企业成员创建并管理个人账户。
  • GitHub 企业服务器
    • 使用： 如果您需要临时接管用户账户…
    • 避免： 如果您需要临时接管个人账户…

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

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

  • 使用： 如果您配置 SAML SSO，您组织的成员将继续使用他们在 GitHub.com 上的个人账户登录。
  • 避免： 如果您配置 SAML SSO，您组织的成员将继续使用他们在 GitHub.com 上的用户账户登录。

未使用 Enterprise Managed Users 的 GitHub Enterprise Cloud 文档通常位于 管理组织的 SAML 单点登录 类别。

其他服务的用户账户

当描述除 GitHub 之外的服务（如集成或身份提供商）的用户账户时，请使用 “用户账户”。

缩略词

在文章首次出现缩略词时请写出全称，标题或标题除外。

应用程序

在一般内容中使用 “app” 或 “application”。

  • 使用： 在 GitHub Marketplace 中发布并列出您的 app

在指代 OAuth 应用时使用 “app”，因为它们不是产品。

  • 使用： 注册 OAuth app
  • 避免： 注册 OAuth App

在指代 GitHub Apps 时使用 “App”，因为它是产品。

  • 使用： 注册 GitHub App

GitHub Apps 和 OAuth apps 包含两个部分：应用注册，以及实现应用功能的代码。

  • 若仅指 GitHub UI 中的 GitHub App 设置/配置，请使用 “register” 与 “GitHub App registration”。

    • 使用： 注册 GitHub App
    • 使用： 更新 GitHub App 注册信息
    • 避免： 创建 GitHub App
    • 避免： 修改 GitHub App

  • 若仅指应用的代码，请使用 “your app’s code” 或 “code for your app”。

    • 使用： code for your app
    • 使用： code for your GitHub App
    • 使用： your app's code
    • 避免： Your GitHub App
    • 避免： Your OAuth app

  • 若指整体应用（注册 + 代码），请称其为 GitHub App 或 OAuth app。

GitHub Apps 可安装在组织和用户账户上。若指代应用的安装实例，请使用 “GitHub App installation” 而非 “GitHub App”。

货币

在提及美元、分、货币金额或使用 $ 符号时，即使金额为零，也应明确货币单位。请使用 ISO 标准的货币名称，并尽可能使用 ISO 标准的货币代码。

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

  • 使用： US dollar.
  • 避免： US Dollar, $USD dollar.

货币代码使用大写。

  • 使用： 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。

权限

“权限”是执行特定操作的能力。例如，删除议题的能力是一项权限。

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

  • 账户（例如，组织所有者、企业账户的账单管理员）
  • 资源（例如，对仓库的写入、对安全建议的管理员）
  • 团队（例如，团队维护者）

个人的访问权限通常指其在特定上下文中拥有的所有能力，且不论这些能力来源于哪些角色或单独的权限。

只有在两者区别关键时才使用权限或角色。否则，请使用访问权限。

  • 使用： 创建自定义仓库角色时，先选择一个继承的角色，然后添加各项权限。
  • 使用： 管理团队对组织仓库的访问权限
  • 使用： 如果您的团队成员身份赋予的访问级别与您作为组织所有者的角色不同…
  • 使用： 具有写入访问权限的人员可以…
  • 避免： 具有写入访问权限的人员可以…
  • 避免： 具有写入角色的人员可以…
  • 避免： 具有写入权限的人员可以…
  • 避免： 具有写入特权的人员可以…

在指定执行某项操作所需的访问权限时，只应提及与该操作同级别的角色。例如，要配置受保护的分支，需要仓库级别的管理员访问权限，即仓库级角色。虽然通过成为组织所有者（组织级角色）可以获得仓库的管理员访问权限，但实际决定您能否执行该操作的是仓库级角色，因此只应提及该角色。

  • 使用： 对仓库拥有写入访问权限的人员可以对该仓库执行 X。
  • 避免： 组织所有者和具有写入访问权限的人员可以对该仓库执行 X。

有关权限声明用词的更多信息，请参阅内容模型中的GitHub 文档文章的内容。

介词

避免句子以介词结尾，除非改写后的句子听起来别扭或过于正式。

产品名称

请参阅本指南的“产品名称”章节。

建议使用或避免的术语

使用避免
人员用户，客户
终端shell
用户名login
登录登录，登录
注册注册
推荐限制软限制
电子邮件电子邮件
frontmatterfront matter，front-matter
在 GitHub 上在远程仓库上
按（键）敲击，轻触
在用户界面中输入在用户界面中按下回车
在命令行中输入在命令行中键入

用词

含糊动词

当任务是必需的，或某个选项优于另一个时，避免使用含糊的情态助动词，如 “may”“might”“ought”“should”“could”“would”“can”。这些动词可能被解读为命令或建议。应使用能够明确表明动作是必需还是可选的动词。如果是可选或建议的情况，也可以使用这些动词，但必须明确其为可选。

  • 使用： 您可以自行决定使用哪些键盘快捷键。
  • 使用： 使用 git clone 命令克隆仓库。
  • 避免： 您可以使用 git clone 命令克隆仓库。
  • 避免： 您本可以删除该分支。

不可见的复数

避免使用不可见的复数形式，这类词语意义模糊，可能被解释为单数或复数。例如，“file retrieval”可能指检索单个文件或多个文件。

  • 使用： 文件检索完成后，选择保存位置。
  • 避免： 文件检索后，选择保存位置。

名词化

避免使用名词化形式，即由动词或形容词派生的名词。名词化会使句子更冗长、难以理解和翻译。

  • 使用： 工作流结束后，软件包将可见。
  • 避免： 工作流达到其结束时，软件包将可见。

名词串

避免使用堆叠修饰词（名词串），因为翻译时可能无法判断哪个词修饰哪个词，从而导致错误翻译。可使用介词重新表述名词串。如果必须使用堆叠修饰词，请确保背景信息和上下文明确，使读者和译者能够理解被修饰的对象。

  • 使用： 公共仓库的默认来源设置
  • 避免： 公共仓库默认来源设置

模糊的名词和代词

如果代词似乎指代多个先行词，请重新表述句子以明确先行词，或用名词代替代词以消除歧义。

  • 使用： 在您对分支进行最终提交并合并拉取请求后，您可以删除该分支。
  • 避免： 在您对分支进行最终提交并合并拉取请求后，您可以删除它。

脚注

  1. 不要与《The Monkees》中的 Davy Jones 混淆 ↩

  2. 还有人类 ↩

© . This site is unofficial and not affiliated with GitHub, Inc.