| .. | ||
| copy-guide.md | ||
| how-to-guide-template.md | ||
| README.md | ||
提示说明
区块编辑器手册支持与其他WordPress手册相同的提示样式。但由于区块编辑器手册文档发布位置（npm、GitHub）不同，短代码的实现方式并不理想。
推荐的Markdown实现方式是使用原始HTML和callout callout-LEVEL类。例如：
<div class="callout callout-info">这是一个**信息**提示框。</div>
可用的样式类包括：info、tip、alert、warning
编辑器配置
您应该配置编辑器使用Prettier自动格式化Markdown文档。完整详情请参阅入门文档。
使用Visual Studio Code和Prettier扩展的配置示例：
"[[markdown]]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true
},
视频嵌入
区块编辑器手册中的视频需要以未公开形式托管在WordPress YouTube频道。此过程需要额外权限。如需帮助，请在Slack的#marketing频道中联系。
视频上传到YouTube后，获取视频嵌入链接。链接格式如下：
https://www.youtube.com/embed/nrut8SfXA44?si=YxvmHmAoYx-BDCog
然后，在文档中需要嵌入视频的位置放置以下代码。请相应更新嵌入链接和视频标题。
<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>
16:9宽高比，并以最高分辨率拍摄。
资源
文档贡献指南
关于如何开始为古腾堡项目贡献文档的指南。
讨论渠道
WordPress文档制作博客是获取WordPress文档最新信息的主要平台，包括公告、产品目标、会议记录、会议议程等。
文档相关的实时讨论在WordPress官方Slack的#docs频道进行（需要注册）。文档团队的每周例会于UTC时间每周二14:00举行。
古腾堡项目使用GitHub管理代码和跟踪问题。主代码库位于：https://github.com/WordPress/gutenberg。如需查找可处理的文档问题，请浏览带有文档标签的议题。
文档类型
古腾堡项目包含两大类文档：
- 用户文档：介绍作者如何使用编辑器发布文章。要贡献用户文档，请关注文档博客或通过#docs Slack频道了解当前优先事项。
- 区块编辑器手册：涵盖与古腾堡项目相关的所有内容，包括开发、扩展以及您正在阅读的专门针对古腾堡的贡献指南。
本文档剩余部分将重点说明如何贡献区块编辑器手册。
区块编辑器手册流程
区块编辑器手册由古腾堡项目代码库中/docs/目录的Markdown文件与软件包生成的文档共同组成。
自动化任务会每隔15分钟将文档发布至区块编辑器手册站点。
关于如何使用git通过拉取请求部署更改，请参阅Git工作流程文档。另可观看视频教程及配套的古腾堡文档贡献幻灯片。
手册结构
手册根据文档功能类型划分为四个部分。文档系统详细阐述了各类文档的需求和功能，简而言之包括：
- 入门教程 - 引导学习者逐步完成目标的完整课程，例如创建区块教程。
- 操作指南 - 针对完成特定小型任务的简短教程，例如如何向区块工具栏添加按钮。
- 参考指南 - API文档，纯功能说明。
- 概念解析 - 侧重于知识学习而非具体任务的深度文档。
模板
我们提供操作指南模板来规范指南结构。如需创建新操作指南，可复制模板中的Markdown内容开始编写。
该模板基于"优质文档项目"的范例制作。如需创建高质量文档，可参考其模板库获取更多示例。
更新文档
更新现有页面的步骤：
- 检出古腾堡代码库
- 创建功能分支，例如
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文件存在未提交的本地变更必须被提交。
软件包文档编写
软件包文档由文档工具自动生成，通过提取软件包根目录下README.md文件的内容实现。但有时将README内容拆分为更易读的小节更为合适。
可通过在软件包中创建docs目录并添加toc.json文件来实现，该文件包含对docs目录下其他markdown文件的引用。toc.json文件应包含要作为主README文件子页面添加的页面数组，其格式遵循自动生成的manifest.json文件。
为确保这些页面嵌套在主软件包名称下，请正确设置parent属性。以下示例展示了如何为@wordpress/create-block章节添加子页面：
[
{
"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
代码示例规范
Markdown中的代码示例应使用三个反引号```包裹，并需包含语言标识符。请参阅GitHub关于代码块的文档。
Gutenberg文档的独特功能是codetabs切换器，可同时显示两个版本的代码，常用于展示JSX和Plain代码示例。
以下是codetabs章节的示例：
\{\% codetabs \%\}
\{\% JSX \%\}
```js
// JSX代码示例
```
\{\% Plain \%\}
```js
// 原生代码示例
```
\{\% end \%\}
代码示例的首选格式是JSX，这应作为默认视图。源代码中排在第一的示例将作为默认显示。
注意： 并非每个指南都需要提供原生JavaScript代码示例。建议仅为入门教程或简短示例提供原生代码，但Gutenberg软件包及更广泛的React和JavaScript生态系统中的大多数代码都采用需要构建过程的JSX格式。