风格指南

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

本文内容

注意

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

GitHub 文档的风格方法

  • 我们的风格指南旨在简洁明了。指南应该易于应用于各种场景。
  • 我们的决策并非基于语法规则或风格指南的对与错，而是基于对用户而言最佳的选择。我们在保持一致性的同时，灵活且开放变化。
  • 为了随着团队和文档集的增长而扩展风格指南，并创建服务于用户的高质量、有意义的内容，我们将注意力集中在高影响力、高价值的场景上，而不是试图全面涵盖每一个风格问题。
  • 一致性和语法正确性很重要，但不如清晰度和意义重要。
  • 在做出风格或结构决策时，我们会考虑内容单元内的信息流和信息的上下文。
  • 当风格指南未涵盖特定于帮助文档的问题时，我们会根据这些原则仔细考虑，然后做出决定。如果审阅者提出相关问题，我们将准备好讨论该决定。

审计日志事件

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

在撰写审计日志事件的描述时，请使用过去时和被动语态来描述发生的事件，使其适用于所有版本。不要以文章上下文中已隐含的短语开头，例如“由…触发”。

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

警报

警报强调文章中特别重要的信息，并证明中断信息流是合理的。

谨慎使用警报。请勿使用连续的警报，或每个部分使用多个警报。

警报应简洁明了。如果信息包含多个句子，或需要有序或无序列表，请考虑将其放在小标题下。

警报类型

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

注意

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

注意特别适用于传达与所描述的过程无关的补充信息。

  • 可能影响过程结果的注意事项，例如特定用户设置。
  • 可用性可能发生变化的产品和功能，例如公共预览版或即将关闭的产品和功能。

例如，“评估密钥扫描的警报”使用注意来告知用户 GitHub 令牌的元数据目前处于公共预览阶段。

注意

GitHub 令牌的元数据目前处于公共预览阶段，并可能发生更改。

提示

建议、最佳实践或产品提示。提示包含用户可自行决定是否遵循的非必要信息。特别适用于针对新用户的文章。

例如，“个性化您的个人资料”使用提示警报来帮助用户了解 @提及组织时的预期。

提示

当您 @提及组织时，只有您是成员的组织才会自动完成。您仍然可以 @提及您不是成员的组织，例如之前的雇主，但组织名称不会为您自动完成。

警告

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

警告警报尤其适用于在 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 语法仍然受支持，并且可能仍然出现在较旧的文章中，但不应用于新的警报。

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

按钮

落地页和一些文章包含按钮，引导用户跳转到其他文章或 GitHub 网页的相关内容。当用户需要跳转到另一个页面才能完成正在描述的任务时，应该使用按钮。例如，“设置 GitHub Enterprise Cloud 试用版” 就包含一个按钮，引导用户跳转到试用版注册页面，因为这是设置试用版的下一步。 “迁移文档”落地页使用按钮将用户引导到大多数用户需要阅读才能开始迁移的文章。

如果按钮鼓励用户离开 GitHub Docs 网站，请遵循号召性用语 (CTA) 按钮指南。如果您想在落地页或文章中包含其他类型的按钮，必须获得 GitHub Docs 团队的批准。

号召性用语 (CTA) 按钮

CTA 按钮强调我们期望或鼓励用户在阅读文章后或作为完成文章中描述的任务的一部分而跳转到的链接。CTA 只能引导用户跳转到 GitHub 拥有的域名。例如，“试用 GitHub Copilot” CTA 在“在您的 IDE 中获取代码建议，使用 GitHub Copilot”中链接到 GitHub.com 上的GitHub Copilot 设置菜单。

只有在跳转到链接支持用户需求时才包含 CTA 按钮。不要仅用于推广 GitHub 功能或产品而使用 CTA 按钮。在上面的示例中，想要试用 GitHub Copilot 的用户必须跳转到 Copilot 设置菜单，并且在阅读文章后很可能希望这样做。相反，即使某人可能会将 Copilot 用作编写代码的一部分，然后为此创建拉取请求，我们也不会在“创建拉取请求”中添加“试用 GitHub Copilot”CTA，因为 Copilot 与“创建拉取请求”的用户需求无关。大多数用户会在不使用 Copilot 的情况下创建拉取请求。但是访问有关 GitHub Copilot 入门文章的用户如果尚未使用它，则可能对试用 Copilot 感兴趣。因此，我们添加 CTA 按钮来帮助用户到达他们想要去的地方。

使用以下格式设置 CTA 的样式。

<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：GitHub Docs 中 CTA 的位置。例如，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

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

输出

如果显示命令的输出，请在示例中注释掉输出，以便用户可以复制和粘贴命令并在无需修改的情况下执行它。

  • 使用

    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 分钟运行一次。
  • 为每个示例使用不同的时间。

强调

使用粗体强调单词或句子的部分。谨慎使用强调（不超过五个连续的单词），并记住它对于视力正常的用户来说是一种视觉辅助，有助于扫描。

  • 不要加粗已应用其他格式的单词，例如占位符文本的全大写。
  • 为了辅助功能，不要仅使用粗体来表达含义或强调。

例如

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

错误消息

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

  • 如果消息出现在 GitHub 的 Web 界面中，或在图形客户端应用程序（如 GitHub Desktop 或 GitHub Mobile）中，请像处理 UI 中的其他文本一样处理该消息。有关更多信息，请参阅用户界面文本。

  • 如果消息出现在命令行界面、日志输出或 API 的响应中，请准确复制文本并使用反引号以等宽字体格式化消息。

内容过期

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

如果必须记录您知道将会过期的内容，您可以使用内容代码检查器来标记和跟踪内容的过期日期。这会将内容标记为已过期，并避免在内容本身之外跟踪过期日期。有关如何格式化内容过期标记的信息，请参阅使用内容代码检查器。

脚注

尽可能避免使用脚注。请考虑是否可以使用警告或以其他方式呈现信息。请参阅一些来自 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 个字符。
  • 以标点符号结尾。除非替代文本描述的是以其他标点符号（例如问号或感叹号）结尾的文本图片，否则通常应为句号。
  • 不要以“图片……”或“图形……”开头。屏幕阅读器会自动朗读这些词。
  • 要以图形的类型开头：“屏幕截图……”或“显示……”的图表。
  • 遵循在文章文本中描述 UI 元素的标准语言。
  • 将多字标题（例如菜单项名称）放在双引号中 ("")。
  • 如果图像的某个区域被视觉突出显示，请描述其方式。这使屏幕阅读器用户能够理解并向视力正常的友人/同事解释从视觉语言角度来看应该寻找什么。

屏幕截图的替代文本

替代文本提供了屏幕截图内容的简短描述，使无法看到它的人受益。

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

显示的产品名称 + UI 元素 的屏幕截图。UI 元素 + 元素/控件的状态及其键盘快捷键 XYZ以深橙色突出显示。

  • 对于产品名称，请使用 GitHub 产品或功能名称，例如“GitHub Actions”或“GitHub 仓库”，而不仅仅是“GitHub”。
  • 像我们在运行副本中那样，使用变量表示单词GitHub：{% data variables.product.prodname_dotcom %}
  • 与书面文档一致地描述 UI 元素。
  • 在需要清晰度时灵活调整词序。
    • 例如，编写“Visual Studio Code 中调试菜单的屏幕截图……”而不是“Visual Studio Code 调试菜单的屏幕截图……”，以避免多个名词连续出现。
示例

按仓库列出的 GitHub 提交者的屏幕截图。水平省略号图标和“下载 CSV 报告”按钮以深橙色突出显示。

GitHub 仓库中文件选项的屏幕截图。带有箭头指示下拉菜单的按钮，标有“代码”，以深橙色突出显示。

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

图表和图形的替代文本

解释页面文本中图表或图形所传达的信息。

使用替代文本表达图像的核心思想，无需重复网页文本。

示例

图表显示了 GitHub Actions 运行器如何自动添加到命名运行器类别中，然后由特定作业请求的五步过程。

例如，请参阅Actions 文档中对此图表的相关解释。

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

不要使用命令行界面的屏幕截图来传达命令及其输出。相反，直接提供用户应使用的命令。有关更多信息，请参阅样式指南的“命令”部分。

当使用命令行界面的屏幕截图来显示用户界面元素时，请遵循屏幕截图的标准替代文本指南。

图像的文件名

命名图像文件时要具有描述性：在文件名中包含名称、操作和 UI 元素。镜像产品语言。使用 kebab-case。不要在文件名中使用 Liquid 条件语句。如果替换图像，请使用确切的文件名。

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

屏幕截图

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

图表

要了解如何创建图表，请参阅“为 GitHub 文档创建图表”。

包容性语言

作为全球最大的开发者社区的所在地，GitHub 致力于在我们所做的一切事情中促进多样性和包容性。我们所有的文档都具有包容性，并且尊重我们的受众，他们来自世界各地，有着各种各样的情况。在撰写文档时，我们使用包容性、反种族主义和易于理解的词语。

单个词语可能很小，但它们可以共同创造社区、归属感和公平。在所有词语和风格的选择中都要具有同理心。在提及个人和社区时要准确。

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

关于包容性语言的资源

Microsoft 样式指南提供关于无偏见沟通、辅助功能术语和为所有能力写作的资源。

学习包容性和辅助功能语言和风格的更多资源

键盘快捷键

对于呈现键盘快捷键，请遵循Microsoft 样式指南，**但以下几点除外**

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

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

  • 对于 Apple 修饰键，使用完整单词而不是符号。

    • 使用：Command
    • 避免：⌘

  • 对于特殊字符的键，使用符号，而不是完整单词。

    • 使用：.、, 和 →。
    • 避免：句点、逗号 和 右箭头。

使用重点

下面是一些关于我们在文档中如何呈现键盘快捷键的使用重点。

  • 基本语法是使用键组合之间的+显示键，没有任何空格。

    • 使用：<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) 或 <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows/Linux)，呈现为

      Command+B (Mac) 或 Ctrl+B (Windows/Linux)

    • 避免：<kbd>Ctrl</kbd>+<kbd>B</kbd> 或 <kbd>Command</kbd>+<kbd>B</kbd>，呈现为

      Ctrl+B 或 Command+B

许可内容

GitHub Docs 采用CC-BY 许可证许可。如果您在文章中重用或修改许可内容，则必须确保许可证兼容且已正确注明。

不要为许可证归属创建可重用内容。我们必须使用项目所使用的确切许可证，因此任何归属都必须在出现的文章中准确编写。

如果您不确定重用任何内容的合法性，请联系法律部门。如果您要添加未在下面列出的许可证的内容，则必须在发布内容之前获得法律审查。

归属 MIT 许可内容

如果我们重用或修改 MIT 许可下的内容，我们必须在内容出现的地方注明 MIT 许可证。

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

  • 创建一个标题为法律声明的标题
  • 注明内容的来源以及它是在 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作为链接文本。详情请参见内容标记参考。

  • 对于指向其他页面的链接：参见“[AUTOTITLE](/PATH/TO/PAGE)”。
  • 对于指向其他页面中各个部分的链接：更多信息，请参见“[AUTOTITLE](/PATH/TO/PAGE#SECTION-LINK)”。

不要使用内联链接，即句子中的单词被超链接，没有任何其他词语表明句子包含链接。这很难翻译和阅读。

不要在超链接中包含引号。

  • 正确用法：OAuth2 令牌可以为非网站的应用程序以编程方式获取。更多信息，请参见“[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)”和“[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)”。
  • 错误用法：阅读[有关 OAuth2 的更多信息](/apps/building-integrations/setting-up-and-registering-oauth-apps/)。请注意，OAuth2 令牌可以[以编程方式获取](/[email protected]/rest/reference/oauth-authorizations/#create-a-new-authorization)，用于非网站的应用程序。

有时，您需要从 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 管理的网站）的链接，请键入完整的页面标题和目标网站。不要将链接放在引号中。

  • 正确用法：参见 XYZ 文档中的[PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE)。
  • 错误用法：参见[PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE)。
  • 错误用法：参见[其他网站](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 的东西。
  • bar：foo 提供的东西。

无序列表格式

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

在介绍列表时，避免使用“以下”或“这些”等难以在没有上下文的情况下本地化的简短、非具体的句子。相反，请创建一个描述性句子，清楚地传达列表的主题，同时允许列表按比例缩放或更改，而无需更新描述。

使用

  • 要了解 GitHub 简介，请参阅以下文章
  • 以下国家/地区支持短信身份验证

避免

  • 有几篇文章提供了 GitHub 简介。请参阅以下内容
  • 50 个国家/地区支持短信身份验证。其中包括

权限声明和产品说明

使用权限声明和产品说明来传达需要特定角色或产品才能完成的任务。

  • 权限声明：执行文章中描述的操作或任务所需的权限。例如：“企业所有者”。
  • 产品说明：执行文章中描述的操作或任务所需的产品。例如：“订阅了 Copilot Business 的组织和企业帐户”。

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

创建可扫描的产品说明的指南

定义权限与产品需求

考虑哪些信息属于权限声明或产品说明。

例如，在为文章“在您的组织中管理 Copilot 的策略”创建权限说明和产品说明时，权限说明将回答“在组织中，什么角色可以管理 GitHub Copilot 的策略和功能？”，而产品说明将回答“用户需要什么 Copilot 订阅才能管理组织的 Copilot 策略和功能？”

重点关注关键信息，而非解释

权限说明和产品说明需要说明谁可以执行任务以及需要什么产品。它们不需要解释为什么需要某个角色或产品。

如果多个角色或产品适用于某个权限说明或产品说明，请使用无序列表对其进行格式化。您可以用一句话介绍复杂的权限说明和产品说明，但始终应尽量使用最少的字数来传达文章主题中“谁可以做什么”的信息。

您可以使用内联链接提供有关角色或产品的更多信息。链接文本必须与链接目标匹配，以便清楚地知道点击链接后将跳转到哪里。

占位符

所有占位符文本均应使用大写字母样式。如果占位符包含多个单词，请使用连字符连接这些单词（短横线命名法）。如果您使用占位符，请解释用户可以用什么内容替换它。这有助于用户修改示例以适应自身需求，并有助于使用辅助技术的用户识别占位符。

使用

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

避免

  • git init your repository
  • git init <your-repository>
  • 点击**添加 username**。

步骤说明

步骤说明为读者提供了一组按顺序执行的步骤，以便完成一项任务。始终使用编号列表来列出步骤。在步骤说明之前，请向读者提供完成任务所需的所有前提条件或概念信息，而不是将其包含在特定步骤中。

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

在每个步骤中使用一致的顺序来呈现信息。

  1. 如果步骤是可选的，请首先说明这一点。
  2. 如果需要清晰地说明，或者为了强调破坏性操作或令人困惑的操作的严重性，请解释步骤的原因或结果。
  3. 描述用户将在其中找到操作的位置。
  4. 操作。

**用法：** 可选地，为了 REASON，在 LOCATION 中，执行 ACTION。

示例

  • 点击**支付信息**。
  • 在您的组织名称下，点击**设置**。
  • 要确认您的更改，请点击**移除信用卡**。
  • 可选地，要查看您计划的详细信息，请点击**显示详情**。
  • 在“GitHub Sponsors”下，在受资助的开源贡献者的右侧，点击您受资助金额旁边的，然后点击**更改层级**。

产品名称

使用完整的产品名称。除非直接复制产品中的内容（例如，UI 文本或 API 响应），否则不要缩写或缩短产品名称。产品名称永远不用所有格。

使用产品名称变量来呈现产品名称，不要使用纯文本编写产品名称。这使得在整个站点上更容易实现产品名称更改，并避免在产品名称中出现错别字。有关产品名称变量的更多信息，请参阅本文档中的“可重用组件和变量”以及 github/docs 存储库的 data 目录。

产品名称始终为单数。

  • **用法：** GitHub Actions 可帮助您自动化软件开发工作流程。
  • **避免：** GitHub Actions 可帮助您自动化软件开发工作流程。

注意区分产品名称和产品功能。产品功能始终为小写。

产品功能
GitHub Actions一个 action
GitHub Codespaces一个 codespace
GitHub Packages一个 package
GitHub Pages一个 GitHub Pages 站点

不要将常用功能（如拉取请求、主题或问题）大写。

特定于产品的约定

本节介绍特定于 GitHub 产品的其他约定。

GitHub Actions

第一方 action 的可重用组件

使用第一方 action 的代码示例必须使用该 action 的相应可重用组件。这使得 action 版本更新（例如，从 v1 到 v2）更容易为像 GitHub Enterprise Server 这样的产品进行管理，这些产品可能直到未来的 GitHub Enterprise Server 版本发布后才提供相同的 action 版本。

Actions 可重用组件位于 /data/reusables/actions/ 中，文件名类似于 action-<action_name>.md

例如，要在示例中使用 actions/checkout action，请使用其可重用组件

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

对于 GitHub Docs 的目的，第一方 action 是任何具有 actions/、github/ 或 octo-org/ 前缀的 action。例如，这是一个第一方 action

steps:
  - uses: actions/checkout@v4

第三方 action 的免责声明

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

# 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 %} 可重用组件。

对于 GitHub Docs 的目的，第三方 action 是任何不具有 actions/、github/ 或 octo-org/ 前缀的 action。例如，这是一个第一方 action

steps:
  - uses: actions/checkout@main

这是一个第三方 action 的示例

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

示例

将版本号固定到 SHA

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

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

对于 GitHub Docs 的目的，第三方 action 是任何不具有以下前缀之一的 action：actions/、github/ 和 octo-org/。例如，这是一个第一方 action

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

更多信息，请参阅“使用 SHA”

Codespaces

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

  • 在 shortTitle 前置信息中。
  • 在文章中的小标题中，如果在小标题之前文章的任何地方都已使用过“Codespaces”。

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

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

始终使用“开发容器”（或者，如果需要澄清，则使用其较长的形式“开发容器”），而不是“devcontainer”（一个单词），但文件/路径名称除外。单字形式可能会被认为是一个品牌，我们想要避免这种情况，而且我们也希望与Visual Studio Code 文档中使用的双字形式保持一致。

使用“开发容器配置文件”来指代.devcontainer目录中的所有文件（以及如果使用的是.devcontainer目录中的devcontainer.json而不是.devcontainer.json）。不要将其称为“开发容器文件”或“devcontainer 文件”，以免将其理解为指devcontainer.json文件。“开发容器配置文件”指的是所有可用于配置开发容器的文件，包括Dockerfile和docker-compose.yml文件。在专门指代devcontainer.json文件时，不要使用“开发容器配置文件”（单数）。而是使用其名称来指代此文件。

GitHub 高级安全 (GHAS)

在提及 GitHub 高级安全计费时，请使用术语licenses和active committers。

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

个人访问令牌

GitHub 有两种类型的个人访问令牌

  • 细粒度个人访问令牌：提供对存储库访问和权限的细粒度控制
  • 个人访问令牌（经典版）：使用范围并授予对令牌所有者可以访问的所有存储库的访问权限

您应该使用变量来指代这些类型的令牌，以及一般的个人访问令牌

  • 使用{% data variables.product.pat_generic %}或{% data variables.product.pat_generic_caps %}来指代一般的个人访问令牌。如果短语应使用标题大小写（“个人访问令牌”）以匹配 UI 文本，则使用{% data variables.product.pat_generic_title_case %}。
  • 使用{% 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 %}来指代个人访问令牌（经典版）。

有关 GitHub 个人访问令牌的更多信息，请参阅“管理您的个人访问令牌”。

标点符号

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

发行说明

GitHub Docs 上的一组发行说明会告知读者有关针对 GitHub Enterprise Server (GHES) 等产品的版本化发行版所做的面向管理员或用户的更改。发行说明显示在发行说明中。

一份好的发行说明应包含几句话，按顺序解答读者对更改提出的问题。更多信息，请参见发行说明内容类型。

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

  • 新功能：全新的行为或功能
  • 安全修复：修复存在安全隐患的缺陷或意外行为
  • 错误修复：修复缺陷或意外行为
  • 更改：对过去行为的显著更改
  • 已知问题：GitHub 已识别但无法或尚未优先处理的问题
  • 即将停用：正在退役的过程中，不应再依赖于未来的工作
  • 已停用：产品或功能生命周期结束
  • 勘误：对不准确的发行说明或文档的更正

您还可以查看有关更新发行说明的指南，内容在“添加或更新发行说明”和“删除发行说明”中。

新功能

新功能的发行说明总结了全新的行为。通常，新功能的说明仅作为新功能发行版的一部分。

撰写新功能的发行说明

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

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

目标用户 (1) 可以通过 需求描述 (2) 使用 功能使用方法描述 (3) 。更多信息，请参见“文章标题” (4)。

  • 在功能标题下的部分中对每个功能进行分类。
  • 使用现在时态撰写。
  • 为了减少重复和不必要的词语，“现在”通常是隐含的。
  • 为了阐明参与者和影响，尽可能避免使用被动语态。

新功能发行说明示例

  • 站点管理员可以通过配置登录尝试的速率限制以及超过速率限制后的锁定持续时间来提高管理控制台的安全性。更多信息，请参见“配置速率限制”。

  • 企业所有者可以控制用户可以在何处创建仓库分叉。分叉可以限制为预设的组织组合、与父仓库相同的组织、用户帐户或任何位置。更多信息，请参见“在您的企业中实施仓库管理策略”。

  • 用户可以使用 geoJSON、topoJSON 和 STL 图表创建文件，并在 Web 界面中呈现这些图表。更多信息，请参见“使用非代码文件”。

安全修复

安全修复的发行说明总结了降低或防止利用产品中与安全相关的漏洞的更改。通常，安全修复的说明仅作为补丁发行版的一部分。

撰写安全修复的发行说明

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

  1. 如果可用，已修复漏洞的NVD 漏洞严重性等级是多少？
  2. 攻击者通过利用此漏洞可以实现什么攻击？
  3. 可以利用什么类型的漏洞？
  4. 如果可用，漏洞的CVE 标识符是什么（待定或有效）？
  5. 是否有人通过GitHub 漏洞赏金计划报告了此漏洞？

严重性 (1)：攻击者可以通过 影响描述 (2) 利用 漏洞利用描述 (3) 。GitHub 已为此漏洞申请 CVE ID CVE-####-##### (4)，该漏洞是通过GitHub 漏洞赏金计划 (5) 报告的。

安全修复发行说明示例

  • 中等：攻击者可以通过向 Markdown REST API 发出并行请求来导致实例上的无限资源耗尽。为了缓解此问题，GitHub 已更新CommonMarker。GitHub 已为此漏洞申请 CVE ID CVE-2022-39209。

  • 中等：攻击者可以在实例的 Web UI 中嵌入危险链接，因为拉取请求预览链接没有正确清理 URL。此漏洞是通过GitHub 漏洞赏金计划报告的。

基础镜像和包更新

我们还在“安全修复”部分中包含基础镜像和依赖包更新，因为这些更新通常会解决安全问题。我们将所有这些更新整合到以下说明中。

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

错误修复

错误修复的发行说明描述了对不希望的或其他意外行为的更正。通常，错误修复的说明仅作为补丁发行版的一部分。

撰写错误修复的发行说明

错误修复的发行说明应解答以下问题。

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

目标用户 (1) 行为描述 (2)。

  • 由于错误现已修复，请使用过去时态撰写。
  • 诸如“修复了一个错误……”或“修复了一个问题……”之类的语言是隐含的且不必要的。
  • 为了减少重复和不必要的词语，“现在”通常是隐含的。
  • 为了阐明参与者和影响，尽可能避免使用被动语态。
  • 如果发行说明包含错误消息，请根据“错误消息”中的指导格式化消息。

错误修复发行说明示例

  • 用户导入启用了推送保护的仓库后，该仓库不会立即显示在安全概述的“安全覆盖率”视图中。

  • 在启用了 GitHub Actions 的实例上，如果在作业最初排队时相应的运行器组不可用，即使在作业进入队列后相应的运行器组可用，GitHub Actions 的工作流作业也不会启动。

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

更改

更改的发行说明描述了对现有行为的显著但次要的更改。更改的说明应解答以下问题。

撰写更改的发行说明

更改的发行说明应解答以下问题。

  1. 此行为是否影响了我，我的角色或访问权限？
  2. 如果此更改解决了或避免了一个问题，那么这个问题是什么？
  3. 新的行为是什么？
  4. 如果相关，更改之前的行为是什么？

目标用户 (1) / 更改解决的问题描述 (2) 新行为描述 (3) 旧行为描述 (4)。

  • 由于此更改适用于相关版本，请使用现在时态撰写更改的说明。
  • 为了减少重复和不必要的词语，“现在”通常是隐含的。
  • 为了阐明参与者和影响，尽可能避免使用被动语态。
  • 通常，目标用户是隐含的。
  • 如果有用，请包含指向 GitHub Docs 的相关链接。

更改发行说明示例

  • 在启用了 GitHub 高级安全许可证的实例上，编写自定义秘密扫描模式的用户可以提供必须或不必匹配的表达式，最多 2,000 个字符。此限制比之前的 1,000 个字符有所增加。

  • 对于需要查看或修改 SAML 映射的管理员，ghe-saml-mapping-csv -d 的输出的默认路径为/data/user/tmp，而不是/tmp。更多信息，请参见“命令行实用工具”。

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

已知问题

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

撰写已知问题的发行说明

已知问题的发行说明应解答以下问题。

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

目标用户 (1) 问题描述 (2) 行为详情 (3) 后续步骤 (4)。

  • 为了阐明参与者和影响，尽可能避免使用被动语态。
  • 为了减少重复和不必要的词语，“现在”通常是隐含的。
  • 如果发行说明包含错误消息，请根据“错误消息”中的指导格式化消息。
  • 如果有用，请包含指向 GitHub Docs 的相关链接。
  • 已知问题也是 GitHub Docs 上的一种内容类型。更多信息，请参见故障排除内容类型。如果有用，请在文档中编写或链接到更深入且与上下文相关的更详细内容。

已知问题发行说明示例

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

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

即将停用

即将停用的功能的发行说明总结了 GitHub 计划删除的行为或功能。这些功能仍可用于生产环境，并附带相关的支持 SLA 和技术支持义务。但是，它们正在退役过程中，不应再依赖于未来的工作。即将停用是一个过渡阶段，在此阶段，建议用户停止使用该功能并为其停用做好准备。

撰写即将停用的功能的发行说明

即将下线功能的发版说明应解答以下问题。

  1. 此现有功能是否与我的角色或访问权限相关？
  2. 即将下线的功能是什么？
  3. 如适用，下线功能的替代方案是什么？
  4. 如适用，在哪里可以了解更多信息？

目标用户 (1) 即将下线的功能描述 (2) 替代功能 (3) 更多信息，请参阅“文章标题” (4)。

  • 说明使用现在时态，即将发生的变更使用将来时态。如适用，请指定下线功能将上线的版本。
  • 为了减少重复和不必要的词语，“现在”通常是隐含的。
  • 为了阐明参与者和影响，尽可能避免使用被动语态。
  • 在功能标题下的部分中对每个功能进行分类。

即将下线功能的发版说明示例

  • 即将下线：为确保实例安全，GitHub Enterprise Server 3.8 及更高版本将禁用用于连接到管理 shell 的 SSH 连接的不安全算法。

  • 提交注释（用户直接添加到提交中的、不在拉取请求中的注释）将不再显示在拉取请求时间轴中。用户无法回复或解决这些注释。时间轴事件 REST API 和 GraphQL API 的 PullRequest 对象也不再返回提交注释。

已下线

已下线的产品或功能不再提供给新客户，也不再进行市场推广、支持或记录。在此阶段，产品实际上已停产，不会提供任何新的开发或修复。已下线产品的唯一支持可能来自现有承诺，例如 GitHub Enterprise Server 以前发布的版本所需的那些承诺。下线标志着产品或功能生命周期的正式结束，不会再进行任何更新、错误修复或用户支持，这标志着向更新的工具或服务的完全过渡。

已下线功能的发版说明编写

已下线功能的发版说明应解答以下问题。

  1. 此功能是否与我的角色或访问权限相关？
  2. 已下线的功能是什么？
  3. 如适用，已下线功能的替代方案是什么？
  4. 如适用，在哪里可以了解更多信息？

目标用户 (1) 已下线的功能描述 (2) 替代功能 (3) 更多信息，请参阅“文章标题” (4)。

  • 说明使用现在时态。
  • 为了减少重复和不必要的词语，“现在”通常是隐含的。
  • 为了阐明参与者和影响，尽可能避免使用被动语态。
  • 在功能标题下的部分中对每个功能进行分类。

已下线功能的发版说明示例

  • 已下线：GitHub Enterprise Server 3.11 及更高版本不再支持 GitHub Actions 的必需工作流程。请改用仓库规则集。更多信息，请参阅“规则集的可用规则”。

勘误

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

勘误编写

勘误应解答以下问题。

  1. 如适用，GitHub Docs 中的发版说明或内容的哪个部分受到影响？
  2. 不准确的信息是否与我的角色或访问权限相关？
  3. 发版说明或文档中描述了哪些不准确的信息？
  4. 勘误何时发布？

内容 (1) 错误地指出 目标用户 (2) 可以 不准确信息的摘要 (3)。[更新：发布时间 4]

勘误示例

  • “功能”错误地指出 GitHub 安全咨询数据库的用户可以看到 Elixir、Erlang 的 Hex 包管理器等的咨询。此功能在 GitHub Enterprise Server 3.7 中不可用，将在未来的版本中提供。[更新：2023-06-01]

添加或更新发版说明

为了向读者表明您已添加或更改了说明，或指示勘误的发布时间，请以“[更新：YYYY-MM-DD]”的格式附加日期戳。

删除发版说明

为了表明我们已删除发版说明，请添加“勘误”部分，详细说明您删除了哪个说明以及（如果相关）该删除的说明实际属于哪个版本。请参阅勘误编写。

可重用内容和变量

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

分段目录

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

如果仅使用H3或H4标题对内容进行分组，并且所有信息都可能与读者相关，则不要添加分段目录。例如，在关于身份和访问管理中，人们应该阅读并考虑每个部分与其企业的关系。我们没有在本文中包含分段目录，因为人们应该通读每个部分，而不是在它们之间进行挑选。添加分段目录还会迫使用屏幕阅读器或其他自适应技术的使用者在找到所需内容之前，先通过更多标题进行选项卡和滚动。

将分段目录格式化为列表。按其在文章中出现的顺序包含所有子部分，并使用完整的标题引用它们。

必须用一个句子或段落介绍分段目录，以帮助人们了解内容的组织方式并选择与他们最相关的部分。不要将分段目录直接放在标题下方。

分段目录示例

## 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中。由于表格难以阅读和维护，因此在创建表格之前，请确保表格中的数据最好以表格形式表示，而不是其他形式，例如列表。表格中的每一行都必须以管道符|开头和结尾。

仅用于呈现表格信息

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

避免描述表格数据

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

例如，在使用自托管运行器进行自动缩放中，比较两个受支持的自动缩放解决方案之间功能的表格以句子每个解决方案都有一些可能需要考虑的具体细节。开头。文章没有描述任何要比较的不同功能，因为表格已清楚地传达了这些信息。

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

为行和列标题使用正确的标记

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

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

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

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

为每个单元格包含一个值

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

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

对于带有行标题的表格，第一个单元格（单元格“A1”）应描述行标题，以帮助人们理解整个表格。但是，如果这样做会使表格不太清晰或添加冗余信息，则可以将此单元格留空。例如，在文章构建和测试 PowerShell中，第一个单元格可以标记为“模块”，但由于每个行标题都已包含“模块”一词，因此此标题会重复不会增加对理解整个表格的描述性价值的信息。

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

对于使用符号的表格

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

如果表格数据并非真正二元（例如，每个值不是“是”就是“否”），则可能需要文本值来补充或替代符号。例如，在页面“关于 GitHub 支持”上，某些功能标注为“可购买”。

谨慎使用脚注

参见“脚注”。

表格内容对齐要一致

表格中的所有列都应左对齐，但仅包含 Octicon 的列应居中对齐。如果列同时包含文本和 Octicon，则使用居中对齐。

表格内容默认左对齐。使用 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 个字符之间。
  • 简短标题使用动词的基本形式，而不是动名词。
    • 使用：“配置通知”，而不是“正在配置通知”。
  • 类别、地图主题和文章的简短标题可以省略产品和功能名称，如果产品或功能与之相关是明确的。
  • 简短标题不引入完整标题中没有的新词。
  • 简短标题应与类似内容的简短标题保持一致。
    • 使用：“组织和团队”和“企业帐户”
    • 避免：“组织和团队”和“管理企业帐户”

撰写简短标题可能具有挑战性。为了帮助将简短标题控制在字符数限制内，请考虑上下文中的简短标题。如果可能，删除任何重复的词语以及属于内容所属的地图主题或类别中的任何产品或功能名称。

网站政策内容

网站政策内容中不要使用可重用组件或变量。网站政策文章是法律文件，必须具有可供人工阅读的源代码。

网站政策内容在其他方面使用与 GitHub Docs 其他部分相同的样式和内容模型。

用户界面元素

粗体

使用粗体描述可交互的用户界面元素。

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

分支名称

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

  • main
  • USERNAME.github.io

按钮

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

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

复选框

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

  • 使用：选择为所有新仓库启用。
  • 避免：选中“为所有新仓库启用”复选框。

动态文本

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

  • 使用：单击将 USERNAME 添加到 REPONAME。

列表和列表项

列表和可点击列表项格式为粗体。要描述与列表交互（例如下拉菜单或展开的用户界面元素），无论列表名称是单词还是 Octicon，都写“选择”。要描述选择列表项，请写“单击”。

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

位置

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

  • 在…下方或上方
  • 在…旁边
  • 左上角、右上角、左下角、右下角
  • 页面顶部、页面底部、页面右侧、页面左侧

面板

尽可能避免提及面板。改为描述某人需要做什么。

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

如果需要引用面板来描述 UI 的更改或解释如何与 UI 交互，请将面板名称格式化为用户界面文本。只有在添加了清晰度或面板在 UI 中没有名称的情况下，才包含“面板”一词。

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

单选按钮

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

仓库名称

使用反引号以等宽字体设置仓库名称的样式。当人们需要导航到仓库时，请提供指向仓库的链接。

  • 使用：有关更多信息，请参见github/docs仓库。

响应式元素

我们仅在响应式 UI 元素造成歧义或混淆时才记录其响应式状态。如果由于响应式 UI 元素而导致任务不明确，请描述某人必须执行的交互以实现任务的目标。不要仅仅描述 UI 元素的视觉状态。

  • 使用：单击安全。如果“安全”不可见，请单击⋮以展开仓库菜单。

用户界面文本

引用用户界面中的文本时，请准确复制文本。使用引号括起无法交互的 UI 文本。

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

更多资源

Microsoft 风格指南

视频

您可以添加视频来加强基于文本的信息，但视频绝不能替代书面内容。视频对于某些用户来说是无法访问的，而且也很难通过搜索找到。

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

语气和语调

使用清晰、简单的语言，让广大读者都能理解。写作要真实、富有同理心和自信。

为您的读者写作：一些行话和技术术语是必要的，但不要假设每个读者都具有相同的技术水平。

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

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

要了解有关撰写易于理解的内容的更多信息，请参见“Microsoft 的品牌声音：最重要的是，简单而人性化”和“Microsoft 风格和语调的十大技巧”。

词语选择和术语

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

缩写

拼写出单词，除非是指产品本身明确缩写的单词。

  • 使用：仓库
  • 避免：Repo
  • 使用：管理员，拥有管理员权限的人员
  • 避免：管理员们

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

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

账户

产品名称和账户

为避免歧义和混淆，请勿在任何产品中使用产品名称作为形容词来描述账户。请改用更清晰的措辞，避免混淆账户和产品。在讨论账户时，仅在需要区分不同产品时才提及产品名称。有关 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 Enterprise Cloud 企业，在描述企业拥有的组织成员时，请使用“个人账户”。

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

描述不含企业托管用户的 GitHub Enterprise Cloud 的文档通常位于“管理您的组织的 SAML 单点登录”类别中。

其他服务的个人账户

在描述个人在 GitHub 之外的服务的账户（例如集成或身份验证提供商）时，请使用“用户账户”。

缩写

在文章中第一次使用缩写时应拼写出来，标题或页眉除外。

应用

在一般内容中使用“应用”或“应用程序”。

  • 使用：在 GitHub Marketplace 上发布和列出您的应用

在提及 OAuth 应用时使用“应用”，因为这些不是产品。

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

在提及 GitHub 应用时使用“应用”，因为这是一个产品。

  • 使用：注册 GitHub 应用

GitHub 应用和 OAuth 应用由两部分组成：应用注册和使应用运行的代码。

  • 要仅指 GitHub UI 中的 GitHub 应用设置/配置，请使用诸如“注册”和“GitHub 应用注册”之类的术语。

    • 使用：注册 GitHub 应用
    • 使用：更新 GitHub 应用注册
    • 避免：创建 GitHub 应用
    • 避免：修改 GitHub 应用

  • 要仅指应用的代码，请使用诸如“应用代码”或“您的应用的代码”之类的术语。

    • 使用：您的应用代码
    • 使用：您的 GitHub 应用代码
    • 使用：您的应用的代码
    • 避免：您的 GitHub 应用
    • 避免：您的 OAuth 应用

  • 要整体提及整个应用（注册 + 代码），请将其称为 GitHub 应用或 OAuth 应用。

GitHub 应用可以安装在组织和用户账户上。要指应用的安装，请使用“GitHub 应用安装”，而不是“GitHub 应用”。

货币

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

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

  • 使用：美元。
  • 避免：美元，$USD 美元。

货币代码使用大写。

  • 使用：USD。

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

  • 使用：对于货币的单次引用，使用10 美元。

如果文章中包含对同一货币的多次引用，请确保第一次引用使用货币名称，前面不加$符号，并在货币名称后面加上括号中的货币代码。

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

  • 使用：第一次引用使用10 美元 (USD)，随后的引用使用$0.25 USD。
  • 避免：$10 美元 (USD)，USD$0.25。

如果第一次引用涉及美分或非美元金额，请在第一次引用后立即用括号大写使用的货币的国家或地区名称。随后的货币引用按照上述指南处理。

  • 使用：第一次引用使用99 美分 (美元)，随后的引用使用99 美分。
  • 避免：$0.99 (美元)，$0.99 USD 美分，USD$0.99 美分。

权限

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

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

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

个人的访问权限通常是指该人在特定上下文中的所有能力，而不管这些能力来自哪些角色或个体权限。

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

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

在指定执行操作所需的访问权限时，仅参考与操作相同级别的角色。例如，您需要对仓库的管理员访问权限（这是仓库级别的角色）才能配置受保护的分支。您可以通过成为组织所有者（组织级别的角色）来获得对仓库的管理员访问权限，但仓库级别的角色才是真正决定您执行操作能力的角色，因此这是唯一应该提到的角色。

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

有关权限语句措辞的更多信息，请参阅内容模型中的“GitHub 文档文章的内容”。

介词

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

产品名称

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

使用或避免的术语

使用避免
人员用户，客户
终端Shell（命令行界面）
用户名登录
登录登录
注册注册
推荐限制软限制
邮箱邮箱
前置 matter（YAML 头部信息）前置 matter（YAML 头部信息）
在 GitHub 上在远程仓库上
按下（按键）点击，轻触
输入（在用户界面中）按下 Enter 键（在用户界面中）
按下 Enter 键（在命令行中）输入（在命令行中）

措辞

含糊不清的动词

当需要执行一项任务，或一个选项比另一个选项更优时，避免使用含糊不清的情态助动词，例如“可能”、“或许”、“应该”、“应当”、“可以”、“将会”和“能”。这些动词可以解释为命令或建议。应使用明确指示动作是必需还是可选的动词。如果某事是一个选项或建议，只要明确该操作是可选的，就可以使用这些动词。

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

隐含复数

避免使用隐含复数，这类词语由于可以解释为单数或复数而具有含糊不清的含义。例如，“文件检索”可以指检索单个文件或多个文件。

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

名词化

避免使用名词化，即由动词或形容词构成的名词。名词化会使句子更长、更难理解，也更难翻译。

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

名词堆砌

避免名词堆砌（一系列名词），这可能导致翻译错误，因为翻译可能无法分辨哪个词修饰另一个词。可以使用介词改写名词串。如果必须使用名词堆砌，请确保背景信息和上下文清晰，以便读者和译者能够理解被修饰的内容。

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

含糊不清的名词和代词

如果代词似乎指代多个先行词，请改写句子以使先行词清晰，或者用名词代替代词以消除歧义。

  • 使用：将最终提交推送到您的分支并合并您的拉取请求后，您可以删除您的分支。
  • 避免：将最终提交推送到您的分支并合并您的拉取请求后，您可以删除它。

脚注

  1. 不要与猴王乐队的戴维·琼斯混淆 ↩

  2. 还有人类 ↩