关于文章结构
在文章中，内容部分遵循标准顺序。每篇文章都包含必需的元素。文章还将包含在内容设计或创建中概述的条件元素和可选元素。有关更多详细信息，请参阅以下指南。
标题
标题全面描述了页面的内容以及读者通过阅读可以学到什么。
标题可能具有挑战性。使用以下一般指南来帮助创建清晰、有用且描述性的标题。本文档中每种内容类型的指南提供了更具体的标题规则。
所有内容类型的标题
- 标题清楚地描述了页面的内容。它们具有描述性和特异性。
- 使用：“在工作流编辑器中浏览操作”
- 使用：“配置 Codespace 的示例”
- 避免：“使用工作流编辑器侧边栏”
- 避免：“示例”
- 标题的长度有严格限制，以确保易于理解（并且更容易在网站上呈现）
- 类别标题：67 个字符和
shortTitle26 个字符 - 地图主题标题：63 个字符和
shortTitle29 个字符 - 文章标题：80 个字符，如果可能，则为 60 个字符，和
shortTitle30 个字符，理想情况下为 20-25 个字符
- 类别标题：67 个字符和
- 标题使用句子大小写。
- 使用：“更改提交消息”
- 避免：“更改提交消息”
- 标题在内容类型中保持一致。请参阅每种内容类型的具体指南。
- 标题足够通用，可以随着产品更改而扩展，反映文章中的所有内容，或包含多个产品上的内容。
- 使用：“GitHub 的计费计划”
- 避免：“用户和组织帐户的计费计划”
- 标题使用一致的术语。
- 在类别或类似主题中制定并遵循模式。
- 标题使用产品本身的术语。
- 同时编写标题和简介。
- 使用简介来扩展标题中提出的想法。
- 有关更多信息，请参阅有关 简介 的指南。
- 如果难以想出标题，请考虑内容类型。有时，难以选择标题表明另一种内容类型更适合。
- 考虑标题在多个产品的搜索结果中将如何显示。
- 我们需要在标题或简介中包含哪些特定词语，以避免将其误认为是关于其他产品的內容？
- 考虑标题在生产环境中的外观。
简介
每个页面的顶部都有一个简介，提供上下文并设定预期，使读者能够快速决定该页面是否与他们相关。简介也会显示在搜索结果中，以提供上下文信息，帮助读者选择结果。
如何编写简介
- 文章简介为一到两句话。
- 地图主题和类别简介为一句话。
- API 参考简介为一句话。
- API 页面的简介应定义功能，以便用户无需阅读整篇文章即可了解该功能是否满足其需求。
- 简介包含页面内容的高级摘要，并详细阐述标题中提出的想法。
- 使用页面标题中单词的通俗同义词，帮助读者以不同的方式理解文章的目的。如果可能，避免重复标题中的单词。
- 简介相对常青且高级，因此它们可以随着页面上内容的未来更改而扩展，而无需频繁更新。
- 为了可搜索性，请在简介中包含页面主题的关键词。
- 当简介中的术语在文章的其他地方使用首字母缩略词时，请指出该首字母缩略词。
- 简介通常不包含文章中包含的任何任务的权限。
权限声明
每个过程都包含一个权限声明，说明执行过程中描述的操作所需的权限，这有助于用户了解他们是否能够完成任务。
有时，在概念性内容中提及所需的权限也很重要，尤其是在独立的概念性文章中。请确保还在相关过程中包含权限声明（或编写一篇包含所有内容的较长文章）。
如何编写权限声明
- 当一组权限适用于文章中的所有过程时，请使用 权限前置信息。
- 当文章包含多个过程并且适用不同的权限时，请在每个相关标题下，在每个过程之前包含单独的权限声明。
- 不要在文章的简介中包含权限。
- 权限存在于不同的级别。仅引用与操作相同级别的权限。例如，您需要对存储库（存储库级权限）具有管理员访问权限才能配置受保护的分支。您可以通过成为组织所有者（组织级权限）来获得对存储库的管理员访问权限，但存储库级权限实际上控制着您执行操作的能力，因此这是权限声明中唯一应提及的权限。
- 权限声明中使用的语言
- [帐户角色] 可以 [操作]。
- 具有 [功能角色] 访问权限的人员可以 [操作]。
- 避免：[帐户角色] 和具有 [功能角色] 访问权限的人员可以 [操作]。
权限声明示例
- 包含多个过程的单个权限声明的文章：在您的企业中实施存储库管理策略
产品说明
仅当功能仅在特定产品中可用且无法仅通过版本控制来传达可用性时，才使用产品说明。例如，如果某个功能可用于 GHEC 和 GHES，则您只能为 GHEC 和 GHES 版本化有关该功能的内容。如果某个功能可用于 Pro、Team、GHEC 和 GHES（但不适用于免费版），则使用产品说明来传达该可用性。
所有产品说明都存储为 gated-features 中的可复用内容，并在相关文章的 YAML 前置信息中添加。
如何编写产品说明
- 产品说明遵循严格的格式，清楚地标识功能及其可用的产品。
- 产品说明还包含指向“GitHub 产品”的链接，有时还会指向另一篇相关文章。
- 示例
- [功能名称] 在 [产品] 中可用。有关更多信息，请参阅“GitHub 产品”。
- “[功能名称]” 可在包含 [免费产品] 的公共存储库中使用，也可在包含 [付费产品] 的公共和私有存储库中使用。有关更多信息，请参阅“GitHub 的产品”。
包含产品说明的文章示例
检查源文件和 gated-features，了解源内容的编写方式。
工具切换器
某些文章的内容会根据用户使用何种工具完成任务而有所不同，例如 GitHub CLI 或 GitHub Desktop。对于大多数内容，相同的基本概念或程序信息对多种工具都适用。但是，如果只有通过根据工具区分内容才能使信息清晰准确，请使用工具切换器。请勿仅为显示不同语言的示例而使用工具切换器。仅当任务或概念根据用户使用的工具发生变化时，才使用工具切换器。有关更多信息，请参阅“在文章中创建工具切换器”。
目录
目录会自动生成。有关更多信息，请参阅“自动生成的迷你 TOC”。
概念性内容
概念性内容帮助用户理解或学习某个主题。有关更多信息，请参阅内容模型中的“概念性内容类型”。
参考性内容
参考性内容提供与主动使用产品或功能相关的结构化信息。有关更多信息，请参阅内容模型中的“参考性内容类型”。
先决条件
先决条件是用户在继续执行某个过程之前需要了解的信息，以便他们能够在开始任务之前准备好所需的一切。
如何编写先决条件
- 在过程的编号步骤之前立即编写先决条件。
- 可以使用列表、句子或段落来解释先决条件。
- 在以下情况下，还可以使用单独的先决条件部分：
- 先决条件信息非常重要，不容错过。
- 存在多个先决条件。
- 要重复或突出显示有关数据丢失或破坏性操作的重要信息，还可以使用警告或危险提示来共享先决条件。
先决条件标题指南
- 使用单独的部分时，请使用标题
Prerequisites
包含先决条件部分的文章示例
程序性内容
程序性内容帮助用户完成任务。有关更多信息，请参阅内容模型中的“程序性内容类型”。
故障排除内容
故障排除内容帮助用户避免或解决错误。有关更多信息，请参阅内容模型中的“故障排除内容类型”。
后续步骤
当文章描述较大流程中的一个步骤或具有大多数用户想要执行的逻辑后续步骤时，请包含“后续步骤”部分。您可以将用户链接到文章或其他 GitHub 资源。
后续步骤部分示例
## 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."
在此示例中，来自“为您的企业入门使用自托管运行器”的后续步骤部分包含指向用户在开始使用文章中描述的功能后需要执行的过程的链接。
## 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.
在此示例中，来自“创建企业帐户”的后续步骤链接到大多数刚完成创建企业帐户的用户接下来想要访问的位置。
进一步阅读
如果还有其他文章可以帮助用户完成其任务或学习使用当前文章中描述的主题，请将其包含在“进一步阅读”部分中。仅包含指向文章内容中尚未链接到的文章的链接。
仅包含有助于用户完成手头任务或主题的链接。专注并为用户提供有价值的资源比提供所有可能的链接更好。
使用无序列表格式化“进一步阅读”部分。有关如何编写链接，请参阅“样式指南”。
“进一步阅读”部分的标题和格式
## Further reading
- "[Article title](article-URL)"
- [External resource title](external-resource-URL) in External Resource Name