title: "文档贡献指南" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - Contributors - Repos - Data

文档贡献指南

关于如何开始为 Gutenberg 项目贡献文档的指南。

讨论交流

Make WordPress Docs 博客是获取 WordPress 文档最新信息的主要渠道，包括公告、产品目标、会议记录、会议议程等。

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

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

文档类型

Gutenberg 项目主要包含两类文档：

用户文档介绍作者如何使用编辑器发布文章。参与用户文档贡献，请关注文档博客或加入 Slack 的 #docs 频道了解当前优先事项。
区块编辑器手册涵盖 Gutenberg 项目的所有内容，包括：开发、扩展以及您正在阅读的 Gutenberg 专项贡献指南。

本文档其余部分将介绍如何参与区块编辑器手册的贡献。

区块编辑器手册流程

区块编辑器手册由 Gutenberg 项目仓库 /docs/ 目录中的 Markdown 文件与各软件包生成的文档混合组成。

自动化任务每 15 分钟将文档发布至区块编辑器手册站点。

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

手册结构

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

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

模板

我们提供了一份操作指南模板，用于为指南提供统一的结构。如需创建新的操作指南，请复制模板中的 Markdown 内容作为起点。

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

更新文档

要更新现有页面：

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

创建新文档

添加新文档需要可运行的 JavaScript 开发环境来构建文档，请参阅 JavaScript 构建设置文档：

在 docs 文件夹中创建 Markdown 文件，使用小写字母、无空格，如需分隔请使用短横线，并采用 .md 扩展名。
使用 Markdown 语法添加内容。所有文档必须且只能包含一个 h1 标签。
将文档条目添加到 toc.json 层级结构中。格式请参考现有条目。
运行 npm run docs:build 以更新 manifest.json。
将 manifest.json 与其他更新的文件一并提交。

如果忘记运行 npm run docs:build，您的 PR 将无法通过静态分析检查，因为 manifest.json 文件是必须提交的未提交本地更改。

Documenting packages

Package documentation is generated automatically by the documentation tool by pulling the contents of the README.md file located in the root of the package. Sometimes, however, it is preferable to split the contents of the README into smaller, easier-to-read portions.

This can be accomplished by creating a docs directory in the package and adding toc.json file that contains references other markdown files also contained in the docs directory. The toc.json file should contain an array of pages to be added as sub-pages of the main README file. The formatting follows the manifest.json file that is generated automatically.

In order for these pages to be nested under the main package name, be sure to set the parent property correctly. See the example below that adds child pages to the @wordpress/create-block section.

[
    {
        "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 仓库中的完整目录和文件名，而不是发布后的路径；区块编辑器手册会创建短链接——您可以在教程部分看到这一点。同样，手册中会省略 readme.md 部分，但链接中应包含它。

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

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

代码示例

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

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

以下是一个 codetabs 部分的示例：

    \{\% codetabs \%\}
    \{\% JSX \%\}
    ```js
    // JSX 代码在此
    ```
    \{\% Plain \%\}
    ```js
    // Plain 代码在此
    ```
    \{\% end \%\}

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

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

提示框说明

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

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

<div class="callout callout-info">这是一个**信息**提示框。</div>

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

<div class="callout callout-tip">
这是一个**技巧**提示框。
</div>

<div class="callout callout-info">
这是一个**信息**提示框。
</div>

<div class="callout callout-alert">
这是一个**警报**提示框。
</div>

<div class="callout callout-warning">
这是一个**警告**提示框。
</div>

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

编辑器配置

您应配置编辑器以使用 Prettier 自动格式化 Markdown 文档。完整详情请参阅《入门文档》。

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

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

根据您查看本文档的位置，方括号可能显示为双括号。正确格式应为单层方括号。

Video embeds

Videos in the Block Editor Handbook need to be hosted on the WordPress YouTube channel as unlisted videos. This process requires additional permissions. Reach out in the #marketing Slack channel for assistance.

Once the video has been uploaded to YouTube, retrieve the video embed link. It should look something like this:

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

Then, place the following code where you want the video to be embedded in the documentation. Update the embed link and video title accordingly.

<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>

Videos should have an aspect ratio of 16:9 and be filmed at the highest resolution possible.

资源

文案指南 - 为 Gutenberg 项目撰写说明、文档或其他贡献的指南。
WordPress 文档团队的语气与风格指南。