GitHub 文档文章内容 - GitHub 文档

关于文章的结构

在一篇文章中，内容章节有标准的顺序。每篇文章都包含必需的元素。文章还会包含在内容设计或创作中概述的条件性元素和可选元素。请参阅下面的指南获取更多细节。

Screenshot of article with title, intro, permissions, product callout, conceptual section, procedural section, and table of contents labeled.

标题

标题应完整描述页面的主题，以及阅读后可以学到的内容。

标题可能具有挑战性。请使用以下通用指南来帮助创建清晰、有帮助且具描述性的标题。本文中每种内容类型的指南提供了更具体的标题规则。

所有内容类型的标题

标题应清晰地说明页面的主题。它们具有描述性且具体。
- 示例：Browsing actions in the workflow editor
- 示例：Example of configuring a codespace
- 避免：Using the workflow editor sidebar
- 避免：Example
标题有硬限制的长度，以保持易于理解（并更易在站点上渲染）。
- 分类标题：67 个字符，shortTitle 为 26 个字符
- 地图主题标题：63 个字符，shortTitle 为 29 个字符
- 文章标题：80 个字符，尽可能控制在 60 个字符，并且 shortTitle 为 30 个字符，理想长度为 20–25 个字符
标题使用句子大小写。
- 示例：Changing a commit message
- 避免：Changing A Commit Message
标题在同一种内容类型中保持一致。请参阅每种内容类型的具体指南。
标题应足够通用，以适应产品变化，涵盖文章全部内容，或包含多个产品的内容。
- 示例：GitHub's billing plans
- 避免：Billing plans for user and organization accounts
标题使用一致的术语。
- 在同一分类或相似主题下制定并遵循模式。
标题使用产品自身的术语。
同时撰写标题和简介。
- 在简介中展开标题所呈现的思路。
- 有关简介的更多信息，请参阅相应指南。
如果难以想出标题，请考虑内容类型。有时选择标题的困难表明另一种内容类型可能更合适。
思考标题在多个产品的搜索结果中将如何展示。
- 我们需要在标题或简介中加入哪些特定词汇，以免被误认为是其他产品的内容？
思考标题在实际发布时的呈现效果。

简介

每个页面和文章都有简介，说明它们的主题。简介的文字也会出现在搜索结果中，对 SEO 非常重要。

如何撰写简介

简介应简明扼要，理想情况下为一句话。
简介帮助读者判断自己是否来到正确的地方获取所需信息。使用用户可能使用并搜索的词汇，告知他们将获得的价值。
简介也是继续阅读的邀请。好的简介能让读者确信他们的时间花得值得。
如果重要术语有常用的缩写，请在简介中同时出现该缩写。（示例：Search engine optimization 与 SEO。）
最后，检查你的简介，确保其中包含相关关键词和短语，使其对搜索引擎友好。

权限声明

每个步骤都应包含权限声明，说明执行该步骤所需的角色，帮助用户了解自己是否有权限完成任务。

在概念性内容（尤其是独立的概念性文章）中，有时也需要提及所需权限。请确保在相关步骤中也加入权限声明（或撰写一篇更长的文章，将所有内容合并）。

如何撰写权限声明

当整个文章的所有步骤共用同一套权限时，请使用 permissions frontmatter。
当文章包含多个步骤且各自所需权限不同，需在每个相关标题下、每个步骤前单独添加权限声明。
不要在文章的简介中加入权限声明。
角色在不同层级上存在。只需引用与操作同层级的角色。例如，要配置受保护分支，需要对仓库拥有 admin 访问权限（仓库层级角色）。虽然通过成为组织所有者（组织层级角色）也能获得仓库的 admin 权限，但实际决定是否能执行该操作的仍是仓库层级角色，因此权限声明中只应提及仓库层级的角色。
权限声明的用语
- 具有 [ACCOUNT ROLE] 的人员。
- [ACCOUNT ROLE] 可以 [ACTION]。
- 具有 [FEATURE ROLE] 访问权限的人员可对 [FEATURE] 执行 [ACTION]。
- 避免：使用 [ACCOUNT ROLE] 与具有 [FEATURE ROLE] 访问权限的人员对 [FEATURE] 执行 [ACTION]。

有关权限声明格式的更多信息，请参阅 Style guide（样式指南）。

产品提示

当某功能仅在特定产品中可用且仅靠版本号无法表达时，请使用产品提示。例如，如果某功能仅在 GHEC 和 GHES 中可用，你可以只针对这两个产品编写对应版本的内容；但如果功能在 Pro、Team、GHEC、GHES（但不在 Free）中可用，则需使用产品提示来说明可用性。

所有产品提示都以可复用文件的形式存放在 gated-features，并在相关文章的 YAML frontmatter 中引用。

如何撰写产品提示

产品提示遵循严格格式，明确标识功能及其可用的产品。
产品提示可包含指向帮助用户了解谁可以使用该功能的文章链接。这些链接可以是内联链接，指向特定的产品或 GitHub 计划。
示例
- [Feature name] 在 [product(s)] 中可用。
- [Feature name] 在具备 [free product(s)] 的公共仓库中可用，在具备 [paid products] 的公共和私有仓库中均可用。

带有产品提示的文章示例

查看源码文件和 gated-features，了解源码内容的编写方式。

管理分支保护规则

某些文章的内容会因使用的工具（如 GitHub CLI 或 GitHub Desktop）而有所不同。对大多数内容而言，概念或步骤信息对多种工具都是适用的。但如果唯一能让信息清晰、准确的方式是按工具区分内容，则应使用工具切换器。不要仅为展示不同语言的示例而使用工具切换器。只有当任务或概念因使用的工具而变化时才使用工具切换器。更多信息请参见 Creating tool switchers in articles（在文章中创建工具切换器）。

概念内容

概念内容帮助人们理解或学习某个主题。更多信息请参见内容模型中的 Conceptual content type（概念内容类型）。

引用内容

引用内容提供与实际使用产品或功能相关的结构化信息。更多信息请参见内容模型中的 Referential content type（引用内容类型）。

先决条件

先决条件是人们在执行步骤前必须了解的信息，以便在开始任务前做好准备。

如何编写先决条件

在步骤的编号列表前立即写出先决条件。
可使用列表、句子或段落来说明先决条件。
当满足以下情况时，也可以使用单独的先决条件章节：
- 先决条件信息非常重要，不能被遗漏。
- 先决条件不止一个。
为重复或强调有关数据丢失或破坏性操作的重要信息，可使用警告或危险提示来呈现先决条件。

先决条件标题指南

使用单独章节时，标题应为 Prerequisites

## Next steps

- You can monitor self-hosted runners and troubleshoot common issues. See "Monitoring and troubleshooting self hosted runners."

- GitHub recommends that you review security considerations for self-hosted runner machines. See "Security hardening for GitHub Actions."

在以下示例中（企业版自托管 Runner 入门），后续步骤章节列出了在使用本文所述功能后用户可能需要执行的步骤链接。

## Next steps

After your enterprise account is created, we recommend learning more about how enterprise accounts work and configuring settings and policies. Follow the "Get started with your enterprise account" learning path.

在以下示例中（创建企业账户），后续步骤链接指向大多数刚完成企业账户创建的用户接下来可能想要去的地方。

延伸阅读

如果还有其他文章可以帮助用户完成任务或学习当前文章中描述的主题，请将它们放入“进一步阅读”章节。只包含尚未在本文内容中链接过的文章。

仅包含能帮助用户完成当前任务或了解当前主题的链接。专注且提供有价值的资源要比提供所有可能的链接更好。

使用无序列表格式化“进一步阅读”章节。有关链接写法，请参阅 Style guide（样式指南）。

进一步阅读章节的标题和格式

## Further reading
- [Article title](article-URL)
- [External resource title](external-resource-URL) in External Resource Name

GitHub 文档文章的内容

本文内容