文档贡献
Gatsby 不出所料地使用 Gatsby 作为其文档网站。提前感谢您对 Gatsby 文档的贡献！正是像您这样的人才使这个社区如此伟大！
在编写（或审阅）用于指导 Gatsby 用户完成任务的学习材料时，您需要测试所有代码示例或步骤，以确保它们能够正常工作。这也有助于您用自己的话来写，而不是从其他来源复制。如果您有一个能够增强文档的演示项目或代码示例，并且不知道放在哪里，请在 PR 中告知 Gatsby 文档团队。
首要任务
在 GitHub 仓库中，查找带有“type: documentation”和“good first issue”标签的 issue，这是您首次为 Gatsby 贡献的好起点，或者查找type: documentation”和“help wanted”以查看所有已准备好供社区帮助的文档 issue。
为 Gatsby 文档贡献的选项
在处理 Gatsby 文档时，您可以选择两种主要的贡献方式
- 直接在 GitHub UI 中工作，使用“编辑此文件”和提交功能，无需克隆存储库。这对于快速更新文档、修复拼写错误和进行轻量级的 Markdown 更改非常有用。
- 克隆 Gatsby 仓库，并使用您喜欢的文本编辑器修改 Markdown 文件。目前（截至 2022 年 2 月），社区成员无法在本地构建文档站点。我们正在内部努力解决这个问题。
修复图片和链接路径
如果您在 Gatsby 文档中发现损坏的图片 URL，应该将其修复，并使其相对于站点源保持相对路径，而不是直接链接到 GitHub 上的远程仓库。这确保了当站点部署时，所有图片都包含在构建中。
要解决图片丢失的问题，请在 Gatsby 仓库中检查文档或教程源Gatsby 仓库，查看它是否在其历史记录中被移动过，以及图片是否仍在其旧位置。检查这些图片是否也从多个文档中引用。如果不是，请将它们移动到新的目录位置（并在必要时更新相对于内容的 URL 引用）。如果它们在多个位置被引用，请使用相对路径，不要重复图片。
如果您在 Gatsby 文档中发现损坏的链接，请随时修复它并提交一个 PR！
请注意，其中一些链接已经正确，因为它们在 gatsbyjs.com 上可以正常工作。虽然我们希望文档中的链接能在 GitHub 上正常工作，但让它们在 gatsbyjs.com 上工作是更高的优先级！
标题
带有前端元数据（包括 title）的文档将在渲染页面上自动生成一个 <h1> 标题，并且应该是唯一的。文档内容中的其他标题应以 <h2> 开始，在 Markdown 中用 ## 表示。
为了便于访问的文档大纲，内容标题应按 h2-h4 (####) 的顺序排列，直到所有层级都建立起来。这将确保 Gatsby 文档拥有一个对辅助技术用户来说效果很好的内容层级结构。阅读更多关于HTML 中的标题和语义结构重要性的内容。
修改 Markdown 文件
💡 新接触 Markdown 写作？查看 Gatsby 的Markdown 语法指南！
- 如果您想添加/修改任何 Gatsby 文档，请前往 GitHub 上的docs 文件夹或contributing 文件夹，并使用文件编辑器进行编辑，然后预览您的更改。
- 在提交更改并在 UI 中提出 PR 之前，您需要确保 PR 符合文档贡献标准
- 遵循Gatsby 风格指南中概述的标准。
- 如果您的 PR 不是来自核心团队编写的 issue，请在您的 PR 中添加一条评论，解释为什么它应该被包含在文档中，根据文档决策树。
注意：如果您的 issue 和/或 PR 不符合上述贡献标准，可能会收到一条评论提醒您这样做。如果在两周后仍未进行这些更新，您的 issue 和/或 PR 可能会被关闭，这有助于我们高效地分类 issue 和 PR。当您准备好进行所需的更新时，可以请求重新打开它。
- GitHub 会允许您直接在 UI 中提交更改并提出 PR。这是您为项目做出贡献的最简单的方式！
文档站点设置说明
文档站点的内容主要存在于docs目录下。仓库中还有一些示例，这些示例在文档中被引用。您可以直接编辑 markdown 文件。
更改标题
有时需要更改文档中的标题。需要注意的是，标题会自动生成带有相应 URL 的链接，这些链接可以从站点上的其他地方进行深度链接。更改标题时，请务必将所有相应的链接指向新的 URL。以下是一些工作流程技巧
- 确定您要查找的 URL。
Changing headers（更改标题）的链接 URL 以changing-headers结尾，Docs renaming instructions（文档重命名说明）变成docs-renaming-instructions，依此类推。 - 更新旧 URL 的所有实例到新 URL。VS Code 中的查找和替换功能对此有帮助。检查原始链接引用的上下文是否与新链接仍然匹配。
添加描述
站点会自动创建描述标签以提升 SEO
默认情况下，此描述由page.excerpt生成。如果您想添加自定义描述，可以使用description前端标签。
配置站点导航
文档包含自定义组件以协助导航。为了定制导航体验，这些组件允许进行一些配置，而无需更改任何 React 代码。
调整面包屑标题
在布局文件中使用 <Breadcrumb /> 组件来显示用户当前正在浏览的页面层次结构，位于每个文档的顶部。目前，只有当您可以访问构建 Gatsby 文档站点的私有 GitHub 仓库时，才能更改面包屑标题。（目前这仅限于 Gatsby 内部员工。我们计划将来向开源社区成员提供此功能，但尚未有时间表。）
要更改在 Breadcrumb 组件中显示的文档的标题，breadcrumbTitle 被支持为侧边栏 YAML 文件中的一个键。它通常用于提供文档标题的缩写版本，例如，当显示在其父页面标题旁边时，将“Adding a Custom webpack Config”（添加自定义 webpack 配置）缩短为“webpack Config”。
禁用或缩短目录
<TableOfContents /> 组件用于渲染文档页面的子标题列表，并自动提供它们的深度链接。可以通过文档 Markdown 的前端元数据中的值进行调整。
在不需要目录且应禁用目录的文档中，前端元数据中的一个键 disableTableOfContents 可以设置为 true，如下所示
在其他文档中，当目录非常长时，可以只显示文档中特定级别的标题，而不是所有子标题。您可以将 tableOfContentsDepth 键设置为一个数字，该数字将限制目录中显示的子标题到该“深度”。如果设置为 2，将列出 <h2>/## 和 <h3>/### 标题；如果设置为 3，将显示 <h2>/##、<h3>/### 和 <h4>/####。设置方式如下
文档重命名说明
有时，作为文档重构或内容澄清的一部分，移动或重命名文件是很有意义的。虽然我们建议尽可能保持 URL 的一致性，但以下是一些尽量减少错误并保持文档良好状态的技巧
- 在GitHub issue中向 Gatsby 文档团队提出拟议的结构更改，以确保您的更改被接受。
- 更新旧 URL 的所有实例到新 URL。VS Code 中的查找和替换功能对此有帮助。检查原始链接引用的上下文是否与新链接仍然匹配。
领取您的周边礼品
在您首次向 Gatsby 仓库（包括文档）做出代码贡献后，您就有资格获得免费的 T 恤或一双袜子。有关更多详情，请参阅周边礼品页面！