风格指南

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

本文内容

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

GitHub Docs 的风格方法

  • 我们的风格指南旨在简化。指南应该易于应用于各种场景。
  • 我们的决策并非基于语法规则或风格指南中的对错，而是基于什么对用户最有利。我们灵活且乐于改变，同时保持一致性。
  • 为了随着团队和文档集的增长而扩展风格指南，并创建高质量、有意义的内容来服务用户，我们专注于高影响力、高价值的场景，而不是试图全面涵盖所有风格问题。
  • 一致性和语法正确性很重要，但不如清晰度和意义重要。
  • 在做出风格或结构决策时，我们会考虑内容单元内信息的流动以及信息的上下文。
  • 当风格指南未涵盖帮助文档的特定问题时，我们会运用这些原则进行思考，然后做出决定。如果审阅者对此提出疑问，我们已准备好讨论该决定。

审计日志事件

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

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

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

突出显示

突出显示强调文章中特别重要的信息，并证明中断信息流是合理的。

谨慎使用突出显示。不要使用连续的突出显示，或每个部分使用多个突出显示。

突出显示应简洁。如果信息超过几句话，或需要有序或无序列表，请考虑将信息放在标题下。

突出显示类型

有四种类型的突出显示：提示、注意、警告和注意。

提示

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

例如，"个性化您的个人资料" 使用提示突出显示来帮助用户了解在@提及组织时会发生什么。

提示

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

注意

提供用户可能需要考虑的额外背景信息。任务可以在没有注意提示的情况下完成，但某些情况下的一些用户可能会从注意提示中受益。

注意特别适用于传达与所描述流程无关的括号信息。

  • 可能影响流程结果的警告，例如特定用户设置。
  • 可用性可能发生变化的产品和功能，例如处于测试阶段或即将弃用的产品和功能。

例如，“管理来自秘密扫描的警报”使用注意提示告知用户 GitHub 令牌的元数据目前处于测试阶段。

注意

GitHub 令牌的元数据目前处于公开测试阶段，可能会发生变化。

警告

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

警告提示特别适用于在 GitHub UI 之外发生的流程，例如在命令行或通过 API 中发生的流程。

例如，“关于 SSH 证书颁发机构”包含命令行的说明，并使用警告提示提醒用户证书一旦签发，就无法撤销。

警告

证书签发后，无法撤销。请确保使用 -V 标志为证书配置有效期，否则证书可以无限期使用。

注意

提醒用户注意危险或破坏性操作，在执行这些操作之前需要格外小心，尤其是在存在安全风险或数据丢失的可能性时。

注意提示通常只在描述在 GitHub UI 之外发生的流程时才需要，例如在命令行或通过 API 中发生的流程。

格式化标注

我们在整个文档集中使用标准格式和颜色来区分不同类型的标注。

标注使用 Markdown 渲染。

提示

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

注意

> [!NOTE]
> Keep this in mind.

警告

> [!WARNING]
> Be careful.

注意

> [!CAUTION]
> Be extremely careful.

标注的 Liquid 语法仍然受支持，并且可能仍然出现在较旧的文章中，但不要用于新的标注。

有关格式化标注的更多信息，请参阅 "GitHub 文档中使用 Markdown 和 Liquid" 中的“标注”。

按钮

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

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

号召性用语 (CTA) 按钮

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

仅当导航到链接支持用户需求时才包含 CTA 按钮。不要仅用于营销 GitHub 功能或产品而使用 CTA 按钮。在上面的示例中，想要尝试 GitHub Copilot 的用户必须导航到 Copilot 设置菜单，并且很可能希望在阅读完文章后导航到该菜单。相反，即使用户可能会将 Copilot 用作编写代码的一部分，然后为此代码创建拉取请求，我们也不会在 "创建拉取请求" 中添加“试用 GitHub Copilot”CTA，因为 Copilot 与“创建拉取请求”的用户需求无关。大多数用户会在不使用 Copilot 的情况下创建拉取请求。但是，访问有关 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 文档复制代码，因此我们应该使用引导用户远离拥挤时间的示例。

  • 不要使用在整点运行的示例，因为这些时间是最拥挤的。
  • 不要使用比必要更频繁运行的示例。例如，与其每五分钟运行一次，不如考虑示例是否可以每 30 分钟运行一次。
  • 每个示例使用不同的时间。

强调

使用斜体强调单词或句子的一部分。谨慎使用强调，用于用户必须了解才能成功完成其正在执行的任务的术语或上下文。不要使用斜体强调已应用其他格式的单词，例如占位符文本的全大写或 UI 元素的粗体。

  • 使用： 细粒度个人访问令牌比个人访问令牌（经典）具有多个安全优势。
  • 使用： 对于除容器以外的软件包类型，在软件包版本右侧点击 删除。
  • 避免： 在 标题 旁边，为您的新键添加描述性标签。

错误消息

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

  • 如果消息出现在 GitHub 的 Web 界面中，或在图形客户端应用程序（如 GitHub Desktop 或 GitHub Mobile）中，请将消息视为 UI 中的其他文本。有关更多信息，请参阅“用户界面文本”。

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

内容过期

一般来说，不要记录将过期的内容。访问 GitHub 文档的任何人都应该确信信息是准确且最新的。

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

脚注

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

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

请注意，无论您使用什么标识符（字母、单词），脚注都将呈现为连续的数字。

莫娜乌苏拉保罗戴维·琼斯1
最喜欢的消遣运送代码戏弄美人鱼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)

引用标题时，请将标题名称用引号括起来。

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

有关更多信息，请参阅“GitHub 文档文章的内容”。

图像

我们在整个文档中使用静态图像，包括屏幕截图、图表和图形，以补充文本信息。

不要在文档中使用动画 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 元素。镜像产品语言。使用连字符命名法。不要在文件名中使用 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
    • 避免： ⌘

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

    • 使用： ., ,, 和 →.
    • 避免： 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) 或 <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 文档根据 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 作为链接文本。有关详细信息，请参见 内容标记参考。

  • 对于指向其他页面的链接：参见 "[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)."

同一页面部分链接不适用于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 的介绍，请参阅以下文章
  • 以下国家/地区支持 SMS 身份验证

避免

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

权限声明和产品说明

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

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

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

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

定义权限与产品需求

考虑哪些信息应该放在权限说明中，哪些信息应该放在产品说明中。

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

重点关注关键信息，而不是解释

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

如果多个角色或产品适用于权限说明或产品说明，请使用无序列表格式化它们。您可以用一句话介绍复杂的权限说明和产品说明，但始终尝试使用尽可能少的词语来传达文章中描述的操作是谁可以执行的。

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

占位符

将任何占位符文本都以大写字母显示。如果占位符包含多个单词，请用连字符（短横线连接）连接这些单词（kebab-case）。如果您使用占位符，请解释人们可以用什么来替换它。这有助于人们修改示例以适应自己的需求，并帮助使用辅助技术的人识别占位符。

使用

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

避免

  • 在您的仓库中执行 git init 命令
  • git init <您的仓库>
  • 点击添加 用户名。

步骤

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

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

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

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

使用： 可选地，为了 原因，在 位置，执行 操作。

示例

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

产品名称

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

使用产品名称变量来呈现产品名称，不要以纯文本形式编写产品名称。这使得产品名称更改更容易在整个网站上实施，并避免产品名称中的拼写错误。有关产品名称变量的更多信息，请参阅本文档中的“可重用组件和变量”以及 github/docs 仓库的 数据目录。

产品名称始终是单数。

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

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

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

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

特定于产品的约定

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

GitHub Actions

用于第一方 action 的可重用组件

使用第一方 action 的代码示例必须使用该 action 的相应可重用组件。这使得 action 版本更新（例如，从 v1 到 v2）更容易管理，例如 GitHub Enterprise Server 等产品可能在未来的 GitHub Enterprise Server 版本发布之前无法使用相同的 action 版本。

Action 可重用组件位于 /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.json，如果使用的是它而不是 .devcontainer 目录中的 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 Bug Bounty 计划 报告了漏洞吗？

严重程度 (1)：攻击者可以通过 影响描述 (2) 通过 利用描述 (3) 来实现。GitHub 已为该漏洞请求了 CVE ID CVE-####-##### (4)，该漏洞是通过 GitHub Bug Bounty 计划 (5) 报告的。

安全修复发布说明示例

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

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

基础镜像和包更新

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

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

错误修复

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

编写错误修复的发布说明

错误修复的发布说明回答以下问题。

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

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

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

错误修复的发行说明示例

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

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

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

更改

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

编写更改的发行说明

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

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

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

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

更改的发行说明示例

  • 在具有 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 文档的相关链接。
  • 已知问题也是 GitHub Docs 上的一种内容类型。有关更多信息，请参阅 "故障排除内容类型。" 如果有用，请在文档中编写或链接到更深入且与上下文相关的內容。

已知问题发布说明示例

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

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

弃用

弃用发布说明总结了 GitHub 已删除或计划删除的行为或功能。通常，弃用说明仅是功能发布的一部分。

编写弃用发布说明

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

  1. 此现有功能是否适用于我，我的角色或访问权限？
  2. 正在弃用的功能是什么？
  3. 如果适用，弃用功能的替代方案是什么？
  4. 如果适用，在哪里可以了解更多信息？

受众 (1) 弃用功能描述 (2) 替代功能 (3) 有关更多信息，请参阅 "文章标题" (4)。

  • 说明使用现在时或将来时，用于即将发生的更改。如果适用，请指定即将发布的版本，其中将发生弃用。
  • 为了减少重复和不必要的词语，“现在”通常是隐含的。
  • 为了澄清参与者和影响，尽可能避免被动语态。
  • 将每个功能分类到一个部分，在功能标题下。

弃用发布说明示例

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

  • 提交评论，即用户在拉取请求之外直接添加到提交的评论，不再显示在拉取请求时间线上。用户无法回复或解决这些评论。时间线事件 REST API 和 GraphQL API 的 PullRequest 对象也不再返回提交评论。

勘误

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

撰写勘误

勘误回答以下问题。

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

内容 (1) 错误地指出 受众 (2) 可以 不准确信息的摘要 (3)。[更新：发布日期 4]

勘误示例

  • "功能" 错误地指出 GitHub Advisory Database 的用户可以看到 Elixir、Erlang 的 Hex 包管理器等的安全建议。此功能在 GitHub Enterprise Server 3.7 中不可用，将在未来版本中提供。[更新于 2023-06-01]

添加或更新发布说明

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

删除发布说明

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

可重用内容和变量

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

分节 TOC

如果文章的某个部分使用 `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 文档中的。由于表格可能难以阅读和维护，因此在创建表格之前，请确保表格中的数据以表格形式表示最佳，而不是其他格式，例如列表。表格中的每一行都必须以管道符号 `|` 开头和结尾。

表格仅用于呈现表格信息

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

避免描述表格数据

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

例如，在“使用自托管运行器进行自动扩展”中，介绍了一个比较两种受支持的自动扩展解决方案功能的表格，并附带句子“每个解决方案都有一些可能需要考虑的具体情况。”文章没有描述任何比较的不同功能，因为这些信息通过表格清晰地传达。

  • 使用：“每个仓库的尺寸限制因您的 GHES 版本而异。”
  • 避免：“表格的第一行显示 GitHub Enterprise Cloud 的信息。第二行显示 GitHub Enterprise Server 的信息。”
  • 避免：“下面的表格显示了导出哪些迁移数据。”

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

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

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

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

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

为每个单元格包含一个值

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

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

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

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

对于使用符号的表格

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

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

谨慎使用脚注

请参阅“脚注”。

一致地对齐表格内容

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

表格内容默认左对齐。使用 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 其他部分相同的样式和内容模型。

用户界面元素

粗体

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

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

分支名称

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

  • main
  • USERNAME.github.io

按钮

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

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

复选框

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

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

动态文本

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

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

列表和列表项

将列表和可点击的列表项格式化为粗体。要描述与列表交互，例如下拉菜单或展开的 UI 元素（无论列表名称是单词还是 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
用户名登录
登录登录，登录
注册注册
推荐限制软限制
电子邮件电子邮件
前置信息前置信息，前置信息
在 GitHub 上在远程存储库上
按（一个键）点击，轻触
输入（在用户界面中）输入（在用户界面中）
输入（在命令行中）输入（在命令行中）

用词

模棱两可的动词

当需要执行任务或一个选项优于另一个选项时，请避免使用模棱两可的助动词，例如“可能”、“也许”、“应该”、“应该”、“可以”、“将”和“能”。这些动词可以解释为命令或建议。相反，请使用明确指示操作是必需还是可选的动词。如果某件事是选项或建议，您可以使用这些动词，只要您明确说明该操作是可选的。

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

隐形复数

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

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

名词化

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

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

名词串

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

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

模糊名词和代词

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

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

脚注

  1. 不要与猴子的戴维·琼斯混淆 ↩

  2. 还有人类 ↩