文档贡献

本指南介绍如何开始为 Gutenberg 项目贡献文档。

讨论

Make WordPress Docs 博客是获取最新 WordPress 文档相关信息的主要场所，包括公告、产品目标、会议纪要、会议议程等。

实时文档讨论在 Make WordPress Slack（需注册）的 #docs 频道中进行。文档团队的每周会议定于周二 UTC 时间 14:00 举行。

Gutenberg 项目使用 GitHub 管理代码并跟踪问题。主仓库位于：https://github.com/WordPress/gutenberg。要查找可处理的文档相关问题，请浏览带有 documentation 标签的问题。

文档类型

Gutenberg 项目主要有两套文档：

1. 用户文档是关于作为作者发布文章时如何使用编辑器的信息。若要为用户文档做出贡献，请关注 docs 博客或在 #docs Slack 频道中询问以了解当前优先事项。
2. 块编辑器手册包含与 Gutenberg 项目相关的所有内容，包括：开发、扩展以及——您正在阅读的这部分——针对 Gutenberg 的贡献工作。

本文档其余部分涵盖对块编辑器手册的贡献工作。

块编辑器手册流程

块编辑器手册由两部分组成：一部分是 Gutenberg 项目仓库中 /docs/ 目录下的 Markdown 文件混合体，另一部分是来自各个包的生成文档。

自动化作业每 15 分钟将文档发布到块编辑器手册站点。

有关如何使用 git 通过拉取请求部署更改，请参阅Git 工作流程文档。此外，请观看视频演示及配套关于向 Gutenberg 贡献文档的幻灯片。

手册结构

手册根据文档的功能类型分为四个部分。The Documentation System很好地解释了每种类型的需求和功能，简而言之，它们是：

• 入门教程 – 完整的课程，逐步引导学习者完成一个目标，例如创建块教程。
• 操作指南 – 专门用于完成一个小特定任务的简短课程，例如如何在块工具栏中添加按钮。
• 参考指南 – API 文档，纯粹的功能描述，
• 解释说明 – 侧重于学习的较长文档，而非针对特定任务。

模板

提供一个操作指南模板，以便为指南提供通用结构。如果开始编写新的操作指南，请复制模板中的 Markdown 以起步。

该模板基于 The Good Docs Project 的示例。如需更多帮助创建高质量文档的示例，请查看他们的模板仓库。

更新文档

要更新现有页面：

1. 检出 Gutenberg 仓库。
2. 创建一个工作分支，例如 docs/update-contrib-guide。
3. 对现有文档进行必要的修改。
4. 提交您的更改。
5. 使用 [Type] Developer Documentation 标签创建拉取请求。

创建新文档

添加新文档需要一个可用的 JavaScript 开发环境来构建文档，请参阅在块编辑器中使用 JavaScript指南：

1. 在 docs 文件夹中创建一个 Markdown 文件，使用小写字母，无空格，如有需要可使用短横线分隔符，并以 .md 结尾。
2. 使用 Markdown 语法添加内容。所有文档都需要且仅需要一个 h1 标签。
3. 将文档条目添加到 toc.json 层级结构中。参见现有条目的格式。
4. 运行 npm run docs:build 以更新 manifest.json。
5. 与其他更新的文件一起提交 manifest.json。

如果您忘记运行 npm run docs:build，由于 manifest.json 文件是必须提交的未提交本地更改，您的 PR 将在静态分析检查中失败。

记录包

包文档由文档工具自动生成，方法是提取位于包根目录下的 README.md 文件的内容。然而，有时最好将 README 的内容拆分为更小、更易读的部分。

这可以通过在包中创建一个 docs 目录并添加一个 toc.json 文件来实现，该文件包含指向同样位于 docs 目录中的其他 Markdown 文件的引用。toc.json 文件应包含一个数组，列出作为主 README 文件子页面的页面。其格式遵循自动生成的 manifest.json 文件。

为了使这些页面嵌套在主包名称下，请务必正确设置 parent 属性。参见下方示例，它为 @wordpress/create-block 章节添加了子页面。

[
    {
        "title": "@wordpress/create-block External Template",
        "slug": "packages-create-block-external-template",
        "markdown_source": "../packages/create-block/docs/external-template.md",
        "parent": "packages-create-block"
    }
]

使用链接

在某些时候，您可能希望链接到其他内部文档页面。值得强调的是，所有文档都可以在不同的上下文中浏览：

• 块编辑器手册
• GitHub 网站
• npm 网站

为了在所有上下文中都能正常工作的链接，您必须使用不带 `https://github.com/WordPress/gutenberg` 前缀的绝对路径链接。您可以使用以下模式引用文件：

• /docs/*.md
• /packages/*/README.md
• /packages/components/src/**/README.md

这样，它们将在上述三个上下文中得到正确处理。

请使用 Gutenberg 仓库中的完整目录和文件名，而不是发布后的路径；块编辑器手册会创建短 URL——您可以在教程部分看到这一点。同样，readme.md 部分在手冊中被省略了，但在链接中应包含在内。

例如，本页面的链接是：/docs/contributors/documentation/README.md

注意：通常的链接转换不适用于标注框中的链接。见下文。

代码示例

Markdown 中的代码示例应包裹在三个反引号 ``` 中，并且还应包含语言标识符。请参阅此关于围栏式代码块的 GitHub 文档。

Gutenberg 文档的一个独特功能是 codetabs 切换开关，它允许同时显示两个版本的代码。这用于展示 JSX 和 Plain 两种代码样本。

这是一个 codetabs 部分的示例：

    \{\% codetabs \%\}
    \{\% JSX \%\}
    ```js
    // JSX code here
    ```
    \{\% Plain \%\}
    ```js
    // Plain code here
    ```
    \{\% end \%\}

代码示例的首选格式是 JSX。这应该是默认视图。源代码中放置的第一个示例将显示为默认值。

注意：并非每个指南都必须包含纯 JavaScript 代码示例。建议在初学者教程或简短示例中包含纯代码，但 Gutenberg 包以及更广泛的 React 和 JavaScript 生态系统中的大多数代码都采用需要构建过程的 JSX 形式。

标注通知

Block Editor 手册支持与其他 WordPress 手册相同的提示样式。然而，由于 Block Editor 手册文档发布在不同位置（npm、GitHub），短代码实现并不理想。

在 markdown 中推荐的实现方式是使用原始 HTML 和 callout callout-LEVEL 类。例如：

<div class="callout callout-info">This is an **info** callout.</div>

可用的类包括：info、tip、alert、warning

<div class="callout callout-tip">
This is a **tip** callout.
</div>

<div class="callout callout-info">
This is an **info** callout.
</div>

<div class="callout callout-alert">
This is an **alert** callout.
</div>

<div class="callout callout-warning">
This is a **warning** callout.
</div>

注意：在 callout 提示框中，链接也需要使用 HTML <a href=""></a> 标记。
通常的链接转换不适用于 callout 中的链接。
例如，要访问 Getting started > Create Block 页面，GitHub 上的 URL 是
https://github.com/WordPress/gutenberg/blob/trunk/docs/getting-started/devenv/get-started-with-create-block.md/
并且必须在 Block Editor Handbook 中硬编码端点为
<a href="https://developer.wordpress.org/block-editor/getting-started/create-block/">https://developer.wordpress.org/block-editor/getting-started/create-block/</a>
以便在手冊中正确链接。

行换行

不要对散文进行硬换行。将每个段落、列表项和表格行保持在单行上，并让编辑器在屏幕上软换行。文档没有行长限制；项目的 markdownlint 配置中禁用了 MD013 规则。

硬换行的文本渲染效果相同，但会使后续编辑难以审查：更改一个单词会重排整个段落，导致差异覆盖每一行，而不仅仅是实际发生变化的那一行。

硬换行在源文件中也是一个无障碍问题。屏幕阅读器逐行读取纯文本文件，盲文显示器一次显示一行，因此跨四行的句子会被当作四个片段接收，而且大多数屏幕阅读器无法按句子导航源文本以将其拼合回来。将句子保留在一行意味着阅读一行就能获得完整的想法。Google 开发者文档风格指南也给出了同样的规则：“不要在句子和段落内强制换行（硬回车）。”

在 Markdown 需要换行的地方保留换行符，例如列表项和表格行之间，并且永远不要重新排列围栏代码块。

编辑器配置

你应该配置编辑器使用 Prettier 自动格式化 markdown 文档。有关完整详情，请参阅入门文档。

以下是使用 Visual Studio Code 和 Prettier 扩展的配置示例：

"[[markdown]]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
},

根据你查看此文档的位置，括号可能显示为双括号。正确的格式只是单个括号。

图片

Block Editor 手册中显示的图片必须托管在 developer.wordpress.org 媒体库中，而不是从 GitHub 链接。

直接从 GitHub 链接的图片（例如，以 `https://raw.githubusercontent.com` 开头的 URL）受到速率限制的影响，一旦文档同步到 Block Editor 手册，加载可能会失败。将它们托管在媒体库中可以避免这种情况。

要添加图片：

1. 将图片上传到 developer.wordpress.org 上的媒体库。这需要额外的权限——如果你没有访问权限，请在 Make WordPress Slack 的 #docs 频道中寻求帮助。
2. 复制上传图片的 URL。它看起来应该像这样 `https://developer.wordpress.org/files/2026/06/your-image.png`。
3. 在 markdown 中使用该 URL 引用图片，并提供描述性的 alt 文本。

例如：

![Descriptive alt text](https://developer.wordpress.org/files/2026/06/your-image.png)

媒体库不接受 SVG 上传。如果 SVG 在手冊中被展示，请将栅格版本（如 PNG）上传到媒体库并进行引用。仅当 SVG 旨在被下载时（例如，作为矢量文件提供的徽标），才将其保留在仓库中并直接链接——下载链接不会在每次页面渲染时被获取，因此不受速率限制影响。

视频嵌入

Block Editor 手册中的视频需要作为未列出视频托管在 WordPress YouTube 频道上。此过程需要额外权限。请在 #marketing Slack 频道中联系以寻求帮助。

视频上传到 YouTube 后，检索视频嵌入链接。它看起来应该像这样：

https://www.youtube.com/embed/nrut8SfXA44?si=YxvmHmAoYx-BDCog

然后，将你希望视频嵌入文档的位置放置以下代码。相应地更新嵌入链接和视频标题。

<iframe width="960" height="540" src="[Video embed link]" title="[Video title]" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="true"></iframe>

视频应具有 16:9 的宽高比，并以尽可能高的分辨率拍摄。

资源

• 撰写说明、文档或对 Gutenberg 项目其他贡献的文案指南。

• 来自 WordPress 文档团队的语气与语调指南。