213 lines
10 KiB
Markdown
213 lines
10 KiB
Markdown
### 提示说明
|
||
|
||
区块编辑器手册支持与其他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 `<a href></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格式。 |