我们在其他文章中创建参考文章和参考部分。
- 某些主要主题可能需要自己的参考文章,尤其是存在大量参考内容时,例如 GitHub Actions 中的搜索语法或 YAML 语法。
- 对于少量内容或更具体的信息(如功能支持的语言或硬件要求的列表),请在过程或概念性文章中使用上下文中的参考部分。
如何编写参考内容
有关参考内容模板,请参阅“模板”。
- 编写一个句子或整个概念性部分来介绍参考内容。
- 清晰、一致地呈现实际参考内容。
- 对于具有要说明的单个元素的主题,请使用列表。
- 示例:组织的存储库角色
- 对于具有要说明的多个元素的主题,请使用表。
- 示例:组织的存储库角色
- 对于较长的参考内容(例如工作流的 YAML 语法),请一致地使用标头。
- 每个不同部分的 H2 标头。
- 子部分的 H3 标头,例如示例。
- 示例:GitHub Actions 的工作流语法
参考内容的标题
- 参考文章或参考部分的标头清楚地描述了部分的内容,通常以名词开头。
- 标题包含可供新手访问的足够信息,并全面描述每个部分的内容。
- 标题应避免堆积名词 - 使用介词分解长串名词。
参考内容的示例
- 参考文章
- 键盘快捷方式
- 企业中的角色
- REST API 文档中的计费的 REST API 终结点
- GraphQL API 文档中的 突变
- 其他文章中的参考部分
- GitHub Mobile 中的“支持的语言”
- 在 AWS 上安装 GitHub Enterprise Server 中的“硬件注意事项”