### 提示说明

区块编辑器手册支持与其他WordPress手册相同的[提示样式](https://make.wordpress.org/docs/handbook/documentation-team-handbook/handbooks-style-and-formatting-guide/#formatting)。但由于区块编辑器手册文档发布位置（npm、GitHub）不同，短代码的实现方式并不理想。

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

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

<div class="callout callout-warning">
注意：在提示框中，链接也需要使用HTML `&lt;a href>&lt;/a>`标签表示法。
常规的链接转换不适用于提示框中的链接。
例如，要访问"入门指南 > 创建区块"页面，GitHub中的URL是
https://developer.wordpress.org/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> 才能正确链接。
</div>

### 编辑器配置

您应该配置编辑器使用Prettier自动格式化Markdown文档。完整详情请参阅[入门文档](/docs/contributors/code/getting-started-with-code-contribution.md)。

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

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

<div class="callout callout-info">
根据您查看本文档的位置，方括号可能显示为双括号。正确格式应为单层方括号。
</div>

### 视频嵌入

区块编辑器手册中的视频需要以未公开形式托管在[WordPress YouTube频道](https://www.youtube.com/@WordPress)。此过程需要额外权限。如需帮助，请在Slack的#marketing频道中联系。

视频上传到YouTube后，获取视频嵌入链接。链接格式如下：

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

然后，在文档中需要嵌入视频的位置放置以下代码。请相应更新嵌入链接和视频标题。

```html
<iframe width="960" height="540" src="[视频嵌入链接]" title="[视频标题]" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="true"></iframe>
```

<div class="callout callout-info">
视频应采用<code>16:9</code>宽高比，并以最高分辨率拍摄。
</div>

## 资源

-   [文案指南](/docs/contributors/documentation/copy-guide.md) - 为Gutenberg项目编写说明、文档或其他贡献的指南

-   WordPress文档团队的[语气与风格指南](https://make.wordpress.org/docs/handbook/documentation-team-handbook/tone-and-voice-guide/)

# 文档贡献指南

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

## 讨论渠道

[WordPress文档制作博客](https://make.wordpress.org/docs/)是获取WordPress文档最新信息的主要平台，包括公告、产品目标、会议记录、会议议程等。

文档相关的实时讨论在[WordPress官方Slack](https://make.wordpress.org/chat)的`#docs`频道进行（需要注册）。文档团队的每周例会于UTC时间每周二14:00举行。

古腾堡项目使用GitHub管理代码和跟踪问题。主代码库位于：[https://github.com/WordPress/gutenberg](https://github.com/WordPress/gutenberg)。如需查找可处理的文档问题，请浏览[带有文档标签的议题](https://github.com/WordPress/gutenberg/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22%5BType%5D+Documentation%22+)。

## 文档类型

古腾堡项目包含两大类文档：

1. [用户文档](https://wordpress.org/documentation/article/wordpress-block-editor/)：介绍作者如何使用编辑器发布文章。要贡献用户文档，请关注文档博客或通过#docs Slack频道了解当前优先事项。
2. [区块编辑器手册](https://developer.wordpress.org/block-editor/)：涵盖与古腾堡项目相关的所有内容，包括开发、扩展以及您正在阅读的专门针对古腾堡的贡献指南。

本文档剩余部分将重点说明如何贡献区块编辑器手册。

## 区块编辑器手册流程

区块编辑器手册由[古腾堡项目代码库](https://github.com/WordPress/gutenberg/)中`/docs/`目录的Markdown文件与软件包生成的文档共同组成。

自动化任务会每隔15分钟将文档发布至[区块编辑器手册站点](https://developer.wordpress.org/block-editor/)。

关于如何使用git通过拉取请求部署更改，请参阅[Git工作流程](/docs/contributors/code/git-workflow.md)文档。另可观看[视频教程](https://wordpress.tv/2020/09/02/marcus-kazmierczak-contribute-developer-documentation-to-gutenberg/)及配套的[古腾堡文档贡献幻灯片](https://mkaz.blog/wordpress/contribute-developer-documentation-to-gutenberg/)。

### 手册结构

手册根据文档功能类型划分为四个部分。[文档系统](https://documentation.divio.com/)详细阐述了各类文档的需求和功能，简而言之包括：

-   **入门教程** - 引导学习者逐步完成目标的完整课程，例如[创建区块教程](/docs/getting-started/devenv/get-started-with-create-block.md)。
-   **操作指南** - 针对完成特定小型任务的简短教程，例如[如何向区块工具栏添加按钮](/docs/how-to-guides/format-api.md)。
-   **参考指南** - API文档，纯功能说明。
-   **概念解析** - 侧重于知识学习而非具体任务的深度文档。

### 模板

我们提供[操作指南模板](https://raw.githubusercontent.com/WordPress/gutenberg/trunk/docs/contributors/documentation/how-to-guide-template.md)来规范指南结构。如需创建新操作指南，可复制模板中的Markdown内容开始编写。

该模板基于"优质文档项目"的范例制作。如需创建高质量文档，可参考其[模板库](https://github.com/thegooddocsproject/templates)获取更多示例。

### 更新文档

更新现有页面的步骤：

1. 检出古腾堡代码库
2. 创建功能分支，例如`docs/update-contrib-guide`
3. 对现有文档进行必要修改
4. 提交更改
5. 使用[[Type] Developer Documentation](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Developer%20Documentation)标签创建拉取请求

### 创建新文档

添加新文档需要配置可运行的JavaScript开发环境来构建文档，请参阅[JavaScript构建设置文档](/docs/how-to-guides/javascript/js-build-setup.md)：

1. 在[docs](https://github.com/WordPress/gutenberg/tree/HEAD/docs)文件夹中创建Markdown文件，使用小写字母、无空格（如需分隔请使用连字符）及`.md`扩展名
2. 使用markdown语法添加内容。所有文档必须包含且仅包含一个`h1`标签
3. 在[toc.json](https://github.com/WordPress/gutenberg/blob/HEAD/docs/toc.json)层级结构中添加文档条目。格式请参考现有条目
4. 运行`npm run docs:build`以更新`manifest.json`
5. 将`manifest.json`与其他更新文件一并提交

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

### 软件包文档编写

软件包文档由文档工具自动生成，通过提取软件包根目录下README.md文件的内容实现。但有时将README内容拆分为更易读的小节更为合适。

可通过在软件包中创建`docs`目录并添加`toc.json`文件来实现，该文件包含对`docs`目录下其他markdown文件的引用。`toc.json`文件应包含要作为主README文件子页面添加的页面数组，其格式遵循自动生成的[`manifest.json`](https://github.com/WordPress/gutenberg/blob/HEAD/docs/manifest.json)文件。

为确保这些页面嵌套在主软件包名称下，请正确设置`parent`属性。以下示例展示了如何为[`@wordpress/create-block`章节](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/)添加子页面：

```json
[
	{
		"title": "@wordpress/create-block 外部模板",
		"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`

<div class="callout callout-warning">
<b>注意：</b>常规链接转换不适用于标注框内的链接。详见下文。
</div>

### 代码示例规范

Markdown中的代码示例应使用三个反引号```` ``` ````包裹，并需包含语言标识符。请参阅[GitHub关于代码块的文档](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks)。

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

以下是`codetabs`章节的示例：

````md
    \{\% codetabs \%\}
    \{\% JSX \%\}
    ```js
    // JSX代码示例
    ```
    \{\% Plain \%\}
    ```js
    // 原生代码示例
    ```
    \{\% end \%\}
````

代码示例的首选格式是JSX，这应作为默认视图。源代码中排在第一的示例将作为默认显示。

**注意：** 并非每个指南都需要提供原生JavaScript代码示例。建议仅为入门教程或简短示例提供原生代码，但Gutenberg软件包及更广泛的React和JavaScript生态系统中的大多数代码都采用需要构建过程的JSX格式。