diff --git a/content/zh/docs/contribute/style/_index.md b/content/zh/docs/contribute/style/_index.md index aacaf26575a..2b50a245fa8 100644 --- a/content/zh/docs/contribute/style/_index.md +++ b/content/zh/docs/contribute/style/_index.md @@ -1,15 +1,13 @@ --- -title: 文档风格概述 +title: 文档样式概述 main_menu: true weight: 80 --- - -本节的主题是提供有关编写风格、内容格式和组织以及使用 Hugo 定制生成 Kubernetes 文档的指导。 +本节的主题是提供有关写作风格、内容格式和组织以及如何使用 +特定于 Kubernetes 文档的 Hugo 定制代码的指导。 diff --git a/content/zh/docs/contribute/style/content-guide.md b/content/zh/docs/contribute/style/content-guide.md new file mode 100644 index 00000000000..3c5cfa6e1b2 --- /dev/null +++ b/content/zh/docs/contribute/style/content-guide.md @@ -0,0 +1,142 @@ +--- +title: 文档内容指南 +linktitle: 内容指南 +content_type: concept +weight: 10 +--- + + + + +本页包含 Kubernetes 文档的一些指南。 + +如果你不清楚哪些事情是可以做的，请加入到 +[Kubernetes Slack](http://slack.k8s.io/) 的 `#sig-docs` 频道提问！ +你可以在 http://slack.k8s.io 注册到 Kubernetes Slack。 + +关于为 Kubernetes 文档创建新内容的更多信息，可参考 +[样式指南](/zh/docs/contribute/style/style-guide)。 + + + + +## 概述 {#overview} + +Kubernetes 网站（包括其文档）源代码位于 +[kubernetes/website](https://github.com/kubernetes/website) 仓库中。 + +在 `kubernetes/website/content/<语言代码>/docs` 目录下, 绝大多数 Kubernetes +文档都是特定于 [Kubernetes 项目](https://github.com/kubernetes/kubernetes)的。 + +## 可以发布的内容 {#whats-allowed} + +只有当以下条件满足时，Kuberentes 文档才允许第三方项目的内容： + +- 内容所描述的软件在 Kubernetes 项目内 +- 内容所描述的软件不在 Kubernetes 项目内，却是让 Kubernetes 正常工作所必需的 +- 内容是被 kubernetes.io 域名收编的，或者是其他位置的标准典型内容 + + +### 第三方内容 {#third-party-content} + +Kubernetes 文档包含 Kubernetes 项目下的多个项目的应用示例。 +这里的 Kubernetes 项目指的是 [kubernetes](https://github.com/kubernetes) 和 +[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub 组织 +下的项目。 + +链接到 Kubernetes 项目中活跃的内容是一直允许的。 + +Kubernetes 需要某些第三方内容才能正常工作。例如 +容器运行时（containerd、CRI-O、Docker）， +[联网策略](/zh/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) +（CNI 插件），[Ingress 控制器](/zh/docs/concepts/services-networking/ingress-controllers/) +以及[日志](https://kubernetes.io/zh/docs/concepts/cluster-administration/logging/)等。 + +只有对应的第三方开源软件（OSS）是运行 Kubernetes 所必需的，才可以在文档中包含 +指向这些 Kubernetes 项目之外的软件的链接。 + + +### 双重来源的内容 {#dual-sourced-content} + +只要有可能，Kubernetes 文档应该指向标准典型的信息源而不是直接托管多重来源的内容。 + +双重来源的内容需要双倍（甚至更多）的投入才能维护，而且通常很快就会变得停滞不前。 + +{{< note >}} +如果你是一个 Kubernetes 项目的维护者，需要帮忙托管你的文档， +请在 Kubernetes 的 [#sig-docs 频道](https://kubernetes.slack.com/messages/C1J0BPD2M/) +提出请求。 +{{< /note >}} + + +### 更多信息 {#more-information} + +如果你对允许出现的内容有疑问，请加入到 [Kubernetes Slack](http://slack.k8s.io/) +的 `#sig-docs` 频道提问！ + +## {{% heading "whatsnext" %}} + +* 阅读[样式指南](/zh/docs/contribute/style/style-guide)。 + + diff --git a/content/zh/docs/contribute/style/content-organization.md b/content/zh/docs/contribute/style/content-organization.md index b8976252fca..cd9ebcd0b13 100644 --- a/content/zh/docs/contribute/style/content-organization.md +++ b/content/zh/docs/contribute/style/content-organization.md @@ -3,99 +3,80 @@ title: 内容组织 content_type: concept weight: 40 --- - - - 本网站使用了 Hugo。在 Hugo 中，[内容组织](https://gohugo.io/content-management/organization/) 是一个核心概念。 - - - -{{% note %}} -**Hugo 提示:** 用 `hugo server --navigateToChanged` 命令启动 Hugo 以进行内容编辑会话。 -{{% /note %}} +{{< note >}} +**Hugo 提示：** 用 `hugo server --navigateToChanged` 命令启动 Hugo 以进行内容编辑会话。 +{{< /note >}} ## 页面列表 - - ### 页面顺序 - +文档侧方菜单、文档页面浏览器等以 Hugo 的默认排序顺序列出。Hugo 会按照权重（从 1 开始）、 +日期（最新的排最前面）排序，最后按链接标题排序。 -文档侧方菜单、文档页面浏览器等以 Hugo 的默认排序顺序列出，它按照权重（从1开始）、日期（最新的排第一个）排序，最后按链接标题排序。 - - - -如果你想提升一个页面或一个章节，请在页面头部设置一个较高的权重： +有鉴于此，如果你想将一个页面或一个章节前移，请在页面头部设置一个较高的权重： ```yaml title: My Page weight: 10 ``` - -{{% note %}} - -对于页面的权重，不建议使用连续的数值，比如1、2、3...，而是采用间隔的数值，比如10、20、30...，这样你可以将后续的页面插入到想要的位置。 -{{% /note %}} - +{{< note >}} +对于页面的权重，不建议使用连续的数值，比如1、2、3...，而应采用间隔的数值，比如10、20、30... +这样将来你可以将其他页面插入到想要的位置。 +{{< /note >}} -### 文档主菜单 - - +### 文档主菜单 -`Documentation` 主菜单是从 `docs/` 下面的章节构建的，它在 `_index.md` 章节内容文件的头部设置了 `main_menu` 标志： - +`文档` 主菜单是从 `docs/` 下面的章节构建的。 +这些章节在其章节内容文件 `_index.md` 的头部设置了 `main_menu` 标志： ```yaml main_menu: true ``` - - -注意，链接标题是从页面的 `linkTitle` 中提取的，因此如果希望它与标题不同，请在内容文件中更改它： - +注意，链接标题来自页面的 `linkTitle` 字段，因此如果希望它与页面标题不同，请在内容文件中更改它： ```yaml main_menu: true @@ -103,36 +84,31 @@ title: Page Title linkTitle: Title used in links ``` - -{{% note %}} -以上每种语言都需要完成。如果在菜单中没有看到你的章节，这可能是因为它没有被 Hugo 标识为一个章节。请在章节对应的目录下创建 `_index.md` 内容文件。 -{{% /note %}} +{{< note >}} +以上操作需要为每种语言分别完成。如果在菜单中没有看到你的章节，这可能是因为它没有被 Hugo 识别为一个章节。 +请在章节对应的目录下创建 `_index.md` 内容文件。 +{{< /note >}} +The documentation side-bar menu is built from the _current section tree_ starting below `docs/`. + +It will show all sections and their pages. + +If you don't want to list a section or page, set the `toc_hide` flag to `true` in front matter: + +When you navigate to a section that has content, the specific section or page (e.g. `_index.md`) is shown. Else, the first page inside that section is shown. +--> ### 文档侧方菜单 - +文档侧方菜单是基于 `docs/` 下面的 _当前章节的内容树_ 构建的。 -文档侧方菜单是从 `docs/` 下面的 _current 章节的 tree_ 开始构建的。 - - - -它将显示所有的章节和它们的页面。 - - +菜单默认显示所有的章节和它们的页面。 如果你不想列出某个章节或页面，请在页面头部将 `toc_hide` 标志设置为 `true`。 @@ -140,27 +116,19 @@ If you don't want to list a section or page, set the `toc_hide` flag to `true` i toc_hide: true ``` - - -当导航到具有内容的章节时，将显示出指定的章节或页面（例如 `_index.md`）。否则，将显示该章节里的第一个页面。 +当导航到具有内容的章节时，网站将显示出指定的章节或页面（例如 `_index.md`）。 +否则，将显示该章节里的第一个页面。 -### 文档浏览器 - - -文档主页上的页面浏览器是用 `docs section` 下一层的所有章节和页面构建的。 - - +### 文档浏览器 {#documentation-browser} + +文档主页上的页面浏览器是基于 `docs section` 下一层的所有章节和页面构建的。 如果你不想列出某个章节或页面，请在页面头部将 `toc_hide` 标志设置为 `true`。 @@ -170,34 +138,30 @@ toc_hide: true -### 主菜单 - - +### 主菜单 -右上菜单中的网站链接（也在页脚中）是通过页面查找构建的。这是为了确保页面实际存在。因此，如果 `case-studies` 章节在网站中不存在（按语言），则它将链接不到。 - +右上菜单中的网站链接（也出现在页脚中）是通过页面查找构建的。 +这是为了确保页面实际存在。因此，如果 `case-studies` 章节在网站（或者其本地化版本）中不存在， +则不会出现对应的链接。 -## 页面包 - - -除了独立的内容页面（Markdown文件），Hugo 还支持 [页面包](https://gohugo.io/content-management/page-bundles/)。 - - +## 页面包 -一个例子是 [定制 Hugo 短代码](/docs/contribute/style/hugo-shortcodes/)。它被认为是 `leaf bundle`。目录下的所有内容，包括 `index.md`，都是包的一部分。这还包括页面相关的链接、可被处理的图像等： +除了独立的内容页面（Markdown 文件），Hugo 还支持 +[页面包](https://gohugo.io/content-management/page-bundles/)。 + +一个例子是[定制的 Hugo 短代码（shortcodes）](/zh/docs/contribute/style/hugo-shortcodes/)。 +它被认为是 `leaf bundle`（叶子包）。 +目录下的所有内容，包括 `index.md`，都是包的一部分。此外还包括页面间相对链接、可被处理的图像等： ```bash en/docs/home/contribute/includes @@ -210,8 +174,8 @@ en/docs/home/contribute/includes - -另一个广泛使用的例子是 `includes` 包。它在页面头部设置 `headless: true`，这意味着它没有得到自己的 URL。它只用于其他页面。 +另一个广泛使用的例子是 `includes` 包。 +这类包在页面头部设置 `headless: true`，意味着它没有得到自己的 URL。它只用于其他页面。 ```bash en/includes @@ -228,44 +192,39 @@ en/includes -包中文件的一些重要说明： - - +有关包中文件的一些重要说明： -* 对于已翻译的包，任何丢失的非内容文件将从上面的语言继承。这避免了重复。 -* 包中的所有文件都是 Hugo 所指的 `Resources`，你可以为每种语言提供元数据，例如参数和标题，即使它不支持头部设置（YAML 文件等）。参见[页面资源元数据](https://gohugo.io/content-management/page-resources/#page-resources-metadata)。 -* 从 `Resource` 的 `.RelPermalink` 中获得的值是页面相关的。参见 [Permalinks](https://gohugo.io/content-management/urls/#permalinks)。 - +* 已翻译的包会从上面的语言继承所有缺失的、非内容文件。这一设计可以避免重复。 +* 包中的所有文件都是 Hugo 所指的 `Resources`，你可以为用不同语言为其提供元数据， + 例如参数和标题，即使它不支持头部设置（YAML 文件等）。 + 参见[页面资源元数据](https://gohugo.io/content-management/page-resources/#page-resources-metadata)。 +* 从 `Resource` 的 `.RelPermalink` 中获得的值是相对于当前页面的。 + 参见 [Permalinks](https://gohugo.io/content-management/urls/#permalinks)。 -## 样式 - - +## 样式 {#styles} -本网站的样式表的 `SASS` 源存储在 `src/sass` 下面，可以用 `make sass` 构建（Hugo很快就会得到 `SASS` 的支持，参见https://github.com/gohugoio/hugo/issues/4243）。 - - +网站的样式表的 `SASS` 源文件存储在 `src/sass` 下面，可以用 `make sass` 构建 +（Hugo 很快就提供 `SASS` 的支持，参见 https://github.com/gohugoio/hugo/issues/4243）。 ## {{% heading "whatsnext" %}} - -* [定制 Hugo 短代码](/docs/contribute/style/hugo-shortcodes/) -* [样式指南](/docs/contribute/style/style-guide) - +* 了解[定制 Hugo 短代码](/zh/docs/contribute/style/hugo-shortcodes/) +* 了解[样式指南](/zh/docs/contribute/style/style-guide) +* 了解[内容指南](/zh/docs/contribute/style/content-guide) diff --git a/content/zh/docs/contribute/style/hugo-shortcodes/example1.md b/content/zh/docs/contribute/style/hugo-shortcodes/example1.md index 0656ce48839..9359bf1c164 100644 --- a/content/zh/docs/contribute/style/hugo-shortcodes/example1.md +++ b/content/zh/docs/contribute/style/hugo-shortcodes/example1.md @@ -3,21 +3,18 @@ title: 例子 #1 --- - 这是一个内容文件**示例**，位于一个**includes**叶子包中。 -{{< note >}} +{{< note >}} +被包含的内容文件也可以包含短代码。 +{{< /note >}} -包含的内容文件也可以包含短代码。 -{{< /note >}} \ No newline at end of file diff --git a/content/zh/docs/contribute/style/hugo-shortcodes/example2.md b/content/zh/docs/contribute/style/hugo-shortcodes/example2.md index 356983f3c00..5648fdc1997 100644 --- a/content/zh/docs/contribute/style/hugo-shortcodes/example2.md +++ b/content/zh/docs/contribute/style/hugo-shortcodes/example2.md @@ -1,17 +1,12 @@ --- title: 例子 #1 --- - - 这是另一个内容文件**示例**，位于一个**includes**叶子包中。 - diff --git a/content/zh/docs/contribute/style/hugo-shortcodes/index.md b/content/zh/docs/contribute/style/hugo-shortcodes/index.md index 8f9a3a260bc..7e12d2da8a9 100644 --- a/content/zh/docs/contribute/style/hugo-shortcodes/index.md +++ b/content/zh/docs/contribute/style/hugo-shortcodes/index.md @@ -1,37 +1,41 @@ --- -approvers: -- chenopis title: 定制 Hugo 短代码 content_type: concept --- - - +--> + 本页面将介绍定制 Hugo 短代码，可以用于 Kubernetes markdown 文档书写。 -更多关于短代码参见 [Hugo 文档](https://gohugo.io/content-management/shortcodes)。 - +关于短代码的更多信息可参见 [Hugo 文档](https://gohugo.io/content-management/shortcodes)。 - + + ## 功能状态 - -本站上面的 markdown 页面，你可以加入短代码来展示已经文档介绍的功能的版本和状态(state)。 +在本站的 markdown 页面中，你可以加入短代码来展示所描述的功能特性的版本和状态。 - -### 功能状态演示 + -下面是一个功能状态代码段的演示，表明这个功能已经在 Kubernetes v1.10时就已经稳定了。 +Below is a demo of the feature state snippet, which displays the feature as stable +in Kubernetes version 1.10. +--> +### 功能状态示例 + +下面是一个功能状态代码段的演示，表明这个功能已经在 Kubernetes v1.10 时就已经稳定了。 ``` {{}} @@ -43,32 +47,33 @@ content_type: concept {{< feature-state for_k8s_version="v1.10" state="stable" >}} -`state`的可选值如下： +`state` 的可选值如下： * alpha * beta * deprecated * stable - + ### 功能状态代码 - -下面是为每个现有的功能状态的模板代码。 - - - -显示的 Kubernetes 默认为该页或站点版本。 -这个可以通过修改 for_k8s_version 短代码参数来调整。 +所显示的 Kubernetes 默认为该页或站点版本。 +可以通过修改 for_k8s_version 短代码参数来调整要显示的版本。 ``` -{{}} +{{}} ``` 会转换为： -{{< feature-state for_k8s_version="v1.10" state="stable" >}} +{{< feature-state for_k8s_version="v1.11" state="stable" >}} #### Alpha 功能 @@ -82,7 +87,6 @@ content_type: concept {{< feature-state state="alpha" >}} - #### Beta 功能 @@ -119,63 +123,165 @@ content_type: concept {{< feature-state state="deprecated" >}} - + ## 词汇 - - -你可以通过加入术语词汇的短代码，来自动更新和替换相应链接中的内容（[我们的词汇库](/docs/reference/glossary/)） +你可以通过加入术语词汇的短代码，来自动更新和替换相应链接中的内容 +（[我们的词汇库](/zh/docs/reference/glossary/)） 这样，在浏览在线文档，鼠标移到术语上时，术语解释就会显示在提示框中。 - + 词汇术语的原始数据保存在 [https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary)，每个内容文件对应相应的术语解释。 - + ### 词汇演示 - +例如，下面的代码在 markdown 中将会转换为 `{{< glossary_tooltip text="cluster" term_id="cluster" >}}`， +然后在提示框中显示。 -例如，下面的代码在 markdown 中将会转换为 `{{< glossary_tooltip text="cluster" term_id="cluster" >}}`，然后在提示框中显示。 - -````liquid +```liquid {{}} -```` +``` - -## 标签页 + -在本站的 markdown 页面（`.md` 文件）中，你可以加入一个标签页集来显示不同形式的解决方案。 - - -标签页的短代码包含以下参数： - - - -* `name`: 标签页上的名字。 -* `codelang`: 如果要在`tab`短代码中加入内部内容，需要告知 Hugo 使用的是什么代码语言，方便代码高亮。 -* `include`: 标签页中所要包含的文件。如果标签页是在 Hugo 的页面包（[leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles)）中，文件（可以是 Hugo 所支持的 MIME 类型文件）将会在包中查找。如果不是，所要包含的内容页面将会在当前路径的相关路径下查找。注意，在`include`属性部分，不能加入短代码内部内容，必须要使用自结束（self-closing）的语法。 -非内容文件将会被代码高亮。如果没有在`codelang`进行声明的话，所用的代码语言将会来自文件名。 - - - -* 如果内部内容是 markdown， 你必须要使用 `%` 分隔符来包装标签页，例如，`{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}` -* 可以在标签页集中混合使用上面的各种变形。 - - -下面是演示标签页短代码。 +You can make tables more accessible to screen readers by adding a table caption. To add a [caption](https://www.w3schools.com/tags/tag_caption.asp) to a table, enclose the table with a `table` shortcode and specify the caption with the `caption` parameter. {{< note >}} -The tab **name** in a `tabs` definition must be unique within a content page. -一个内容页面下的，标签页定义中的标签页 **名** 必须是唯一的。 +Table captions are visible to screen readers but invisible when viewed in standard HTML. {{< /note >}} - +Here's an example: +--> +## 表格标题 {#table-captions} + +通过添加表格标题，你可以让表格能够被屏幕阅读器读取。 +要向表格添加[标题（Caption）](https://www.w3schools.com/tags/tag_caption.asp)， +可用 `table` 短代码包围表格定义，并使用 `caption` 参数给出表格标题。 + +{{< note >}} +表格标题对屏幕阅读器是可见的，但在标准 HTML 中查看时是不可见的。 +{{< /note >}} + +下面是一个例子： + + + +```go-html-template +{{}} +参数 | 描述 | 默认值 +:---------|:------------|:------- +`timeout` | 请求的超时时长 | `30s` +`logLevel` | 日志输出的级别 | `INFO` +{{< /table */>}} +``` + +所渲染的表格如下： + +{{< table caption="配置参数" >}} +参数 | 描述 | 默认值 +:---------|:------------|:------- +`timeout` | 请求的超时时长 | `30s` +`logLevel` | 日志输出的级别 | `INFO` +{{< /table >}} + + +如果你查看表格的 HTML 输出结果，你会看到 `` 元素 +后面紧接着下面的元素： + +```html + +``` + + +## 标签页 + +在本站的 markdown 页面（`.md` 文件）中，你可以加入一个标签页集来显示 +某解决方案的不同形式。 + +标签页的短代码包含以下参数： + + +* `name`： 标签页上显示的名字。 +* `codelang`: 如果要在 `tab` 短代码中加入内部内容，需要告知 Hugo 使用的是什么代码语言，方便代码高亮。 +* `include`: 标签页中所要包含的文件。如果标签页是在 Hugo 的 + [叶子包](https://gohugo.io/content-management/page-bundles/#leaf-bundles)中定义， + Hugo 会在包内查找文件（可以是 Hugo 所支持的任何 MIME 类型文件）。 + 否则，Hugo 会在当前路径的相对路径下查找所要包含的内容页面。 + 注意，在 `include` 页面中不能包含短代码内容，必须要使用自结束（self-closing）语法。 + 非内容文件将会被代码高亮。 + 如果没有在 `codelang` 进行声明的话，Hugo 会根据文件名推测所用的语言。 + +* 如果内部内容是 Markdown，你必须要使用 `%` 分隔符来包装标签页。 + 例如，`{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`。 +* 可以在标签页集中混合使用上面的各种变形。 + + +下面是标签页短代码的示例。 + +{{< note >}} +内容页面下的 **tabs** 定义中的标签页 **name** 必须是唯一的。 +{{< /note >}} + + ### 标签页演示：代码高亮 ```go-text-template @@ -255,20 +361,17 @@ println "This is tab 2." {{< tab name="JSON File" include="podtemplate" />}} {{< /tabs >}} - - - ## {{% heading "whatsnext" %}} - + * 了解 [Hugo](https://gohugo.io/)。 -* 了解 [撰写新的话题](/docs/home/contribute/write-new-topic/)。 -* 了解 [使用页面模板](/docs/home/contribute/page-templates/)。 -* 了解 [暂存修改](/docs/home/contribute/stage-documentation-changes/)。 -* 了解 [创建 pull request](/docs/home/contribute/create-pull-request/)。 +* 了解 [撰写新的话题](/zh/docs/contribute/write-new-topic/)。 +* 了解 [使用页面类型](/zh/docs/contribute/style/page-content-types/)。 +* 了解 [发起 PR](/zh/docs/contribute/new-content/create-a-pr/)。 diff --git a/content/zh/docs/contribute/style/page-content-types.md b/content/zh/docs/contribute/style/page-content-types.md new file mode 100644 index 00000000000..241f440e73e --- /dev/null +++ b/content/zh/docs/contribute/style/page-content-types.md @@ -0,0 +1,412 @@ +--- +title: 页面内容类型 +content_type: concept +weight: 30 +card: + name: 贡献 + weight: 30 +--- + + + + + +Kubernetes 文档包含以下几种页面内容类型： + +- 概念（Concept） +- 任务（Task） +- 教程（Tutorial） +- 参考（Reference） + + + + +## 内容章节 {#content-sections} + +每种页面内容类型都有一些使用 Markdown 注释和 HTML 标题定义的章节。 +你可以使用 `heading` 短代码将内容标题添加到你的页面中。 +注释和标题有助于维护对应页面内容类型的结构组织。 + +定义页面内容章节的 Markdown 注释示例： + +```markdown + +``` + +```markdown + +``` + + +要在内容页面中创建通用的标题，可以使用 `heading` 短代码加上标题字符串。 + +标题字符串示例： + +- whatsnext +- prerequisites +- objectives +- cleanup +- synopsis +- seealso +- options + +例如，要创建一个 `whatsnext` 标题，添加 heading 短代码并指定 "whatsnext" 字符串： + +```none +## {{%/* heading "whatsnext" */%}} +``` + + +你可以像下面这样声明一个 `prerequisites` 标题： + +```none +## {{%/* heading "prerequisites" */%}} +``` + + +短代码 `heading` 需要一个字符串参数。 +该字符串参数要与 `i18n/<语言>.toml` 文件中以其为前缀的某个变量匹配。 +例如： + +`i18n/en.toml`: + +```toml +[whatsnext_heading] +other = "What's next" +``` + +`i18n/ko.toml`: + +```toml +[whatsnext_heading] +other = "다음 내용" +``` + + +## 内容类型 {#content-types} + +每种内容类型都非正式地定义了期望的页面结构组织。 +请按照所建议的页面章节来创建内容页面。 + + +### 概念 {#concept} + +概念页面用来解释 Kubernetes 的某些方面。例如，概念页面可以用来描述 Kubernetes +中的 Deployment 对象，解释其作为应用的角色如何部署、扩缩和更新。 +通常，概念页面不需要包含步骤序列，但包含指向任务或教程的链接。 + +要编写一个新的概念页面，在 `/content/en/docs/concepts` 目录下面的子目录中新建 +一个 Markdown 文件。该文件具有以下特点。 + +概念页面分为三个章节： + +| 页面章节 | +|--------------------| +| overview （概述） | +| body (主体） | +| whatsnext (接下来）| + + +其中的 `overview` 和 `body` 章节在概念页面中显示为注释。 +你可以使用 `heading` 短代码向页面添加 `wahtsnext` 节。 + +在为每个章节撰写内容时，遵从一些规定： + +- 使用二级和三级标题（H2、H3）来组织内容 +- 在 `overview` 节中，使用一段文字来为主体部分铺陈上下文； +- 在 `body` 节中，详细解释对应概念； +- 对于 `whatsnext` 节，提供一个项目符号列表（最多 5 个），帮助读者进一步学习掌握概念 + +[注解](/zh/docs/concepts/overview/working-with-objects/annotations/)页面是一个已经 +上线的概念页面的例子。 + + +### 任务（Task） {#task} + +任务页面讲解如何完成某项工作，通常包含由为数不多的几个步骤组成的序列。 +任务页面的讲解文字很少，不过通常会包含指向概念主题的链接，以便读者 +能够了解相关的背景和知识。 + +编写新的任务页面时，在 `/content/en/docs/tasks` 目录下的子目录中创建一个 +新的 Markdown 文件。该文件特点如下。 + +| 页面章节 | +|---------------------------| +| overview （概述） | +| prerequisites （准备工作）| +| steps （步骤） | +| discussion （讨论） | +| whatsnext （接下来） | + + +其中的 `overview`、`steps` 和 `discussion` 节在任务页面中显示为注释。 +你可以使用 `heading` 短代码添加 `prerequisites` 和 `whatsnext` 小节。 + +在每个小节内撰写内容时注意以下规定： + +- 最低使用二级标题（H2，标题行前带两个 `#` 字符）。每个小节都会由模版自动给出标题。 +- 在 `overview` 节中，用一个段落为整个任务主体设定语境； +- 在 `prerequisites` 节中，尽可能使用项目符号列表。 + 额外的环境准备条件要加在 `include` 短代码之后。 + 默认的环境准备条件是拥有一个在运行的 Kubernetes 集群。 +- 在 `steps` 节中，使用编号符号列表。 +- 在 `discussion` 节中，使用正常文字内容来对 `steps` 节中内容展开叙述。 +- 在 `whatsnext` 节中，使用项目符号列表（不超过 5 项），列举读者可能接下来有兴趣 + 阅读的主题。 + +已上线的任务主题示例之一是[使用 HTTP 代理来访问 Kubernetes API](/zh/docs/tasks/extend-kubernetes/http-proxy-access-api/)。 + + +### 教程（Tutorial） {#tutorial} + +教程页面描述如果完成一个比单一任务规模更大的目标。通常教程页面会有多个小节， +每个小节由一系列步骤组成。例如，每个教程可能提供对代码示例的讲解，便于用户 +了解 Kubernetes 的某个功能特性。教程可以包含表面层面的概念解释，对于更深层面 +的概念主题应该使用链接。 + +撰写新的教程页面时，在 `/content/en/docs/tutorials` 目录下面的子目录中创建新的 +Markdown 文件。该文件有以下特点。 + +| 页面节区 | +|---------------------------| +| overview （概述） | +| prerequisites （环境准备）| +| objectives （目标） | +| lessoncontent （教程内容）| +| cleanup （清理工作） | +| whatsnext （接下来） | + + +教程页面的 `overview`、`objectives` 和 `lessoncontent` 小节显示为注释形式。 +你可以使用 `heading` 短代码根据需要添加 `prerequisites`、`cleanup` 和 +`whatsnext` 小节。 + +在每个小节中编写内容时，请注意以下规定： + +- 最低使用二级标题（H2，标题前面有两个 `#` 字符）。模版会自动为每个小节设置标题。 +- 在 `overview` 节中，用一个段落为整个主题设定语境； +- 在 `prerequisites` 节中，尽可能使用项目符号列表。 + 额外的环境准备条件要加在已包含的条件之后。 +- 在 `objectives` 节中，使用项目符号列表。 +- 在 `lessoncontent` 节中，结合使用编号符号列表和叙述性文字。 +- 在 `cleanup` 节中，使用编号符号列表来描述任务结束后清理集群状态所需要的步骤。 +- 在 `whatsnext` 节中，使用项目符号列表（不超过 5 项），列举读者可能接下来有兴趣 + 阅读的主题。 + +已发布的教程主题的一个例子是 +[使用 Deployment 运行无状态应用](/zh/docs/tutorials/stateless-application/run-stateless-application-deployment/). + + +### 参考（Reference） {#reference} + +组件工具的参考页面给出的是某个 Kubernetes 组件工具的描述和参数选项输出。 +每个页面都是使用组件工具命令基于脚本生成的。 + +每个工具参考页面可能包含以下小节： + +| 页面小节 | +|-----------------| +| synopsis (用法）| +| options（选项） | +| options from parent commands (从父命令集成的选项） | +| examples （示例）| +| seealso （参考）| + +已发布的工具参考页面示例包括： + +- [kubeadm init](/zh/docs/reference/setup-tools/kubeadm/kubeadm-init/) +- [kube-apiserver](/zh/docs/reference/command-line-tools-reference/kube-apiserver/) +- [kubectl](/zh/docs/reference/kubectl/kubectl/) + +## {{% heading "whatsnext" %}} + + +- 了解[样式指南](/zh/docs/contribute/style/style-guide/) +- 了解[内容指南](/zh/docs/contribute/style/content-guide/) +- 了解[内容组织](/zh/docs/contribute/style/content-organization/) + diff --git a/content/zh/docs/contribute/style/page-templates.md b/content/zh/docs/contribute/style/page-templates.md deleted file mode 100644 index fc427417a80..00000000000 --- a/content/zh/docs/contribute/style/page-templates.md +++ /dev/null @@ -1,353 +0,0 @@ ---- -title: 使用页面模板 -content_type: concept -weight: 30 ---- - - - - - - - -当贡献新主题时，选择下列模板中的一种。 -这使指定页面的用户体验标准化。 - - - -页面模板在 [`kubernetes/website`](https://github.com/kubernetes/website) 仓库的 [`layouts/partials/templates`](https://git.k8s.io/website/layouts/partials/templates) 目录中。 - -{{< note >}} - - -每个新主题都需要使用模板。如果你不确定新主题要使用哪个模板，请从[概念模板](#概念模板)开始。 -{{< /note >}} - - - - - - - - - -## 概念模板 - - - -每个概念页面负责解释 Kubernetes 的某方面。例如，概念页面可以描述 Kubernetes Deployment 对象，并解释当部署、扩展和更新时，它作为应用程序所扮演的角色。一般来说，概念页面不包括步骤序列，而是提供任务或教程的链接。 - - - - -要编写新的概念页面，请在 `/content/en/docs/concepts` 目录的子目录中创建一个 Markdown 文件，其特点如下： - - - -- 在页面的 YAML 头部，设置 `content_type: concept`。 -- 在页面的 body 中，设置所需的 `capture` 变量和所有想要包含的变量： - - | 变量 | 必需? | - |---------------|-----------| - | overview | 是 | - | body | 是 | - | whatsnext | 否 | - - - - 页面的 body 看起来像这样（移除所有不想要的可选 `capture` 变量）： - - ``` - {{%/* capture overview */%}} - - {{%/* /capture */%}} - - {{%/* capture body */%}} - - {{%/* /capture */%}} - - {{%/* capture whatsnext */%}} - - {{%/* /capture */%}} - ``` - - - -- 在每个章节中写下你的内容。请遵从以下规则： - - 使用不低于 H2 级别的标题（避免使用 H1 的标题，但 H3、H4 的标题是可以的）（以两个 `#` 字符开头）。这些章节本身是由模板自动命名的。 - - 在 `overview` 节，用一个段落的篇幅来为当前话题设定语境。 - - 在 `body` 节，使用自由形式的 Markdown 文件来解释概念。 - - 在 `whatsnext` 节，列出读者接下来可能感兴趣的最多 5 个主题。 - - - -使用概念模板的已发布主题的一个示例是[注解](/docs/concepts/overview/working-with-objects/annotations/)。你当前正在阅读的页面也使用概念模板。 - - - -## 任务模板 - - - -任务页面展示了如何完成单个任务，通常是通过给出一个简短的步骤序列。任务页面中解释性质的文字极少，但是通常会给出提供相关背景和知识的概念主题的链接。 - - - -要编写新的任务页面，请在 `/content/en/docs/tasks` 目录的子目录中创建一个 Markdown 文件，其特点如下： - - - -- 在页面的 YAML 头部，设置 `content_type: task`。 -- 在页面的 body 中，设置所需的 `capture` 变量和所有想要包含的变量： - - | 变量 | 必需? | - |---------------|-----------| - | overview | 是 | - | prerequisites | 是 | - | steps | 否 | - | discussion | 否 | - | whatsnext | 否 | - - - - 页面的 body 看起来像这样（移除所有不想要的可选 `capture` 变量）： - - ``` - {{%/* capture overview */%}} - - {{%/* /capture */%}} - - {{%/* capture prerequisites */%}} - - {{}} {{}} - - {{%/* /capture */%}} - - {{%/* capture steps */%}} - - {{%/* /capture */%}} - - {{%/* capture discussion */%}} - - {{%/* /capture */%}} - - {{%/* capture whatsnext */%}} - - {{%/* /capture */%}} - ``` - - - -- 在每个章节中写下你的内容。请遵从以下规则： - - 使用不低于 H2 级别的标题（避免使用 H1 的标题，但 H3、H4 的标题是可以的）（以两个 `#` 字符开头）。这些章节本身是由模板自动命名的。 - - 在 `overview` 节，用一个段落的篇幅来为当前话题设定语境。 - - 在 `prerequisites 节`，如果有可能，请使用列表。在 `include` 下开始添加额外的先决条件。默认的先决条件包括运行中的 Kubernetes 集群。 - - 在 `steps` 节，使用编号列表。 - - 在讨论部分，使用通常的内容来扩展 `steps` 中包含的信息。 - - 在 `whatsnext` 节，列出读者接下来可能感兴趣的最多 5 个主题。 - - - -使用任务模板的已发布主题的一个示例是[使用 HTTP 代理访问 Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api)。 - - - -## 教程模板 - - - -教程页面展示了如何完成比单个任务更大的目标。通常教程页有几个章节，每个章节都有步骤说明。例如，教程可以提供说明 Kubernetes 的特定特性的代码示例的演练。教程可以包括表层解释，但是应该链接到相关的概念主题以进行深入解释。 - - - -要编写新的教程页面，请在 `/content/en/docs/tutorials` 目录的子目录中创建一个 Markdown 文件，其特点如下： - - - -- 在页面的 YAML 头部，设置 `content_type: tutorial`。 -- 在页面的 body 中，设置所需的 `capture` 变量和所有想要包含的变量： - - | 变量 | 必需? | - |---------------|-----------| - | overview | 是 | - | prerequisites | 是 | - | objectives | 是 | - | lessoncontent | 是 | - | cleanup | 否 | - | whatsnext | 否 | - - - - 页面的 body 看起来像这样（移除所有不想要的可选 `capture` 变量）： - - ``` - {{%/* capture overview */%}} - - {{%/* /capture */%}} - - {{%/* capture prerequisites */%}} - - {{}} {{}} - - {{%/* /capture */%}} - - {{%/* capture objectives */%}} - - {{%/* /capture */%}} - - {{%/* capture lessoncontent */%}} - - {{%/* /capture */%}} - - {{%/* capture cleanup */%}} - - {{%/* /capture */%}} - - {{%/* capture whatsnext */%}} - - {{%/* /capture */%}} - ``` - - - -- 在每个章节中写下你的内容。请遵从以下规则： - - 使用不低于 H2 级别的标题（避免使用 H1 的标题，但 H3、H4 的标题是可以的）（以两个 `#` 字符开头）。这些章节本身是由模板自动命名的。 - - 在 `overview` 节，用一个段落的篇幅来为当前话题设定语境。 - - 在 `prerequisites` 节，如果有可能，请使用列表。在默认情况下添加额外的先决条件。 - - 在 `objectives` 节，使用列表。 - - 在 `lessoncontent` 节，适当地使用编号列表和叙述内容的组合。 - - 在 `cleanup` 节，使用编号列表描述完成任务后清理集群状态的步骤。 - - 在 `whatsnext` 节，列出读者接下来可能感兴趣的最多 5 个主题。 - - - -使用教程模板的已发布主题的一个示例是[使用部署运行无状态应用程序](/docs/tutorials/stateless-application/run-stateless-application-deployment/)。 - - - -## {{% heading "whatsnext" %}} - - - - -- 学习[样式指南](/docs/contribute/style/style-guide/) -- 学习[内容组织](/docs/contribute/style/content-organization/) - - diff --git a/content/zh/docs/contribute/style/style-guide.md b/content/zh/docs/contribute/style/style-guide.md new file mode 100644 index 00000000000..c3c00b5be96 --- /dev/null +++ b/content/zh/docs/contribute/style/style-guide.md @@ -0,0 +1,1207 @@ +--- +title: 文档样式指南 +linktitle: 样式指南 +content_type: concept +weight: 10 +--- + + + + +本页讨论 Kubernetes 文档的样式指南。 +这些仅仅是指南而不是规则。 +你可以自行决定，且欢迎使用 PR 来为此文档提供修改意见。 + +关于为 Kubernetes 文档贡献新内容的更多信息，可以参考 +[文档内容指南](/zh/docs/contribute/style/content-guide/)。 + +样式指南的变更是 SIG Docs 团队集体决定。 +如要提议更改或新增条目，请先将其添加到下一次 SIG Docs 例会的 +[议程表](https://docs.google.com/document/d/1ddHwLK3kUMX1wVFIwlksjTk0MsqitBnWPe1LRa1Rx5A/edit) +上，并按时参加会议讨论。 + + + +{{< note >}} +Kubernetes 文档 [Blackfriday Markdown 解释器](https://github.com/russross/blackfriday) +和一些 [Hugo 短代码](/zh/docs/home/contribute/includes/) 来支持词汇表项、Tab +页以及特性门控标注。 +{{< /note >}} + + +## 语言 {#language} + +Kubernetes 文档已经被翻译为多个语种 +（参见 [本地化 READMEs](https://github.com/kubernetes/website/blob/master/README.md#localization-readmemds)）。 + +为文档提供一种新的语言翻译的途径可以在 +[本地化 Kubernetes 文档](/zh/docs/contribute/localization/)中找到。 + +英语文档使用美国英语的拼写和语法。 + +{{< comment >}}[如果你在翻译本页面，你可以忽略关于美国英语的这一条。]{{< /comment >}} + + +## 文档格式标准 {#documentation-formatting-standards} + +### 对 API 对象使用驼峰式命名法 {#use-camel-case-for-api-objects} + +当指代 API 对象时，请使用与实际对象名称中一样的大写和小写字母。 +通常 API 对象使用[驼峰式命名](https://en.wikipedia.org/wiki/Camel_case). + +不要将 API 对象的名称切分成多个单词。例如，使用 PodTemplateList，不要 +使用 Pod Template List。 + +引用 API 对象时不必强调 “object（对象）”，除非省略“object（object）” +会使得文字读起来很别扭。 + + +{{< table caption = "关于 API 对象的约定" >}} +可以 | 不可以 +:--| :----- +Pod 有两个容器 | pod 中有两个容器 +此 Deployment 负责... | 此 Deployment 对象负责 ... +PodList 是 Pod 的列表 | Pod List 是 pods 的列表 +这两个 ContainerPorts ... | 这两个 ContainerPort 对象 ... +这两个 ContainerStateTerminated 对象 ... | 这两个 ContainerStateTerminateds ... +{{< /table >}} + + +### 在占位符中使用尖括号 + +在占位符中使用尖括号，并让读者知道其中代表的事物。例如： + +1. 显示 Pod 信息： + + kubectl describe pod -n <名字空间> + + 如果名字空间被忽略，默认为 `default`，你可以忽略 '-n' 参数。 + + + +### 用粗体字表现用户界面元素 + +{{< table caption = "粗体界面元素约定" >}} +可以 | 不可以 +:--| :----- +点击 **Fork**. | 点击 "Fork". +选择 **Other**. | 选择 "Other". +{{< /table >}} + + +### 定义或引入新术语时使用斜体 + +{{< table caption = "新术语约定" >}} +可以 | 不可以 +:--| :----- +每个 _集群_ 是一组节点 ... | 每个“集群”是一组节点 ... +这些组件构成了 _控制面_. | 这些组件构成了 **控制面**. +{{< /table >}} + + +### 使用代码样式表现文件名、目录和路径 + +{{< table caption = "文件名、目录和路径约定" >}} +可以 | 不可以 +:--| :----- +打开 `envars.yaml` 文件 | 打开 envars.yaml 文件 +进入到 `/docs/tutorials` 目录 | 进入到 /docs/tutorials 目录 +打开 `/_data/concepts.yaml` 文件 | 打开 /\_data/concepts.yaml 文件 +{{< /table >}} + + +### 在引号内使用国际标准标点 + +{{< table caption = "标点符号约定" >}} +可以 | 不可以 +:--| :----- +事件记录中都包含对应的“stage”。 | 事件记录中都包含对应的“stage。” +此副本称作一个“fork”。| 此副本称作一个“fork。” +{{< /table >}} + + +## 行间代码格式 {#inline-code-formatting} + +### 为行间代码和命令使用代码样式 + +对于 HTML 文档中的行间代码，使用 `` 标记。 +在 Markdown 文档中，使用反引号（`` ` ``）。 + + +{{< table caption = "行间代码和命令约定" >}} +可以 | 不可以 +:--| :----- +命令 `kubectl run` 会创建一个 Deployment | 命令 "kubectl run" 会创建一个 Deployment。 +在声明式管理中，使用 `kubectl apply`。 | 在声明式管理中，使用 "kubectl apply"。 +用三个反引号来（\`\`\`）标示代码示例 | 用其他语法来标示代码示例。 +使用单个反引号来标示行间代码。例如：`var example = true`。 | 使用两个星号（`**`）或者一个下划线（`_`）来标示行间代码。例如：**var example = true**。 +在多行代码块之前和之后使用三个反引号标示隔离的代码块。 | 使用多行代码块来创建示意图、流程图或者其他表示。 +使用符合上下文的有意义的变量名。 | 使用诸如 'foo'、'bar' 和 'baz' 这类无意义且无语境的变量名。 +删除代码中行尾空白。 | 在代码中包含行尾空白，因为屏幕抓取工具通常也会抓取空白字符。 +{{< /table >}} + + +{{< note >}} +网站支持为代码示例使用语法加亮，不过指定语法加亮是可选的。 +代码段的语法加亮要遵从[对比度指南](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0&showtechniques=141%2C143#contrast-minimum) +{{< /note >}} + + +### 为对象字段名和名字空间使用代码风格 + +{{< table caption = "对象字段名约定" >}} +可以 | 不可以 +:--| :----- +在配置文件中设置 `replicas` 字段的值。 | 在配置文件中设置 "replicas" 字段的值。 +`exec` 字段的值是一个 ExecAction 对象。 | "exec" 字段的值是一个 ExecAction 对象。 +在 `kube-system` 名字空间中以 Daemonset 形式运行此进程。 | 在 kube-system 名字空间中以 DaemonSet 形式运行此进程。 +{{< /table >}} + + +### 用代码样式书写 Kubernetes 命令工具和组件名 + +{{< table caption = "Kubernetes 命令工具和组件名" >}} +可以 | 不可以 +:--| :----- +`kubelet` 维持节点稳定性。 | kubelet 负责维护节点稳定性。 +`kubectl` 处理 API 服务器的定位和身份认证。| kubectl 处理 API 服务器的定位和身份认证。 +使用该证书运行进程 `kube-apiserver --client-ca-file=FILENAME`. | 使用证书运行进程 kube-apiserver --client-ca-file=FILENAME. | +{{< /table >}} + + +### 用工具或组件名称开始一句话 + +{{< table caption = "工具或组件名称使用约定" >}} +可以 | 不可以 +:--| :----- +The `kubeadm` tool bootstraps and provisions machines in a cluster. | `kubeadm` tool bootstraps and provisions machines in a cluster. +The kube-scheduler is the default scheduler for Kubernetes. | kube-scheduler is the default scheduler for Kubernetes. +{{< /table >}} + + +### 尽量使用通用描述而不是组件名称 + +{{< table caption = "组件名称与通用描述" >}} +可以 | 不可以 +:--| :----- +Kubernetes API 服务器提供 OpenAPI 规范。| apiserver 提供 OpenAPI 规范 +聚合 APIs 是下级 API 服务器。 | 聚合 APIs 是下级 APIServers。 +{{< /table >}} + + +### 使用普通样式表达字符串和整数字段值 + +对于字符串或整数，使用正常样式，不要带引号。 + +{{< table caption = "字符串和整数字段值约定" >}} +可以 | 不可以 +:--| :----- +将 `imagePullPolicy` 设置为 Always。 | 将 `imagePullPolicy` 设置为 "Always"。 +将 `image` 设置为 nginx:1.16. | 将 `image` 设置为 `nginx:1.16`。 +将 `replicas` 字段值设置为 2. | 将 `replicas` 字段值设置为 `2`. +{{< /table >}} + + +## 代码段格式 + +### 不要包含命令行提示符 + +{{< table caption = "命令行提示符约定" >}} +可以 | 不可以 +:--| :----- +kubectl get pods | $ kubectl get pods +{{< /table >}} + + +### 将命令和输出分开 + +例如： + +验证 Pod 已经在你所选的节点上运行： + + kubectl get pods --output=wide + +输出类似于： + + NAME READY STATUS RESTARTS AGE IP NODE + nginx 1/1 Running 0 13s 10.200.0.4 worker0 + + +### 为 Kubernetes 示例给出版本 + +代码示例或者配置示例如果包含版本信息，应该与对应的文字描述一致。 + +如果所给的信息是特定于具体版本的，需要在 +[任务模版](/zh/docs/contribute/style/page-content-types/#task) +或[教程模版](/zh/docs/contribute/style/page-content-types/#tutorial) +的 `prerequisites` 小节定义 Kubernetes 版本。 +页面保存之后，`prerequisites` 小节会显示为 **开始之前**。 + +如果要为任务或教程页面指定 Kubernetes 版本，可以在文件的前言部分包含 +`min-kubernetes-server-version` 信息。 + + +如果示例 YAML 是一个独立文件，找到并审查包含该文件的主题页面。 +确认使用该独立 YAML 文件的主题都定义了合适的版本信息。 +如果独立的 YAML 文件没有在任何主题中引用，可以考虑删除该文件， +而不是继续更新它。 + +例如，如果你在编写一个教程，与 Kubernetes 1.8 版本相关。那么你的 Markdown +文件的文件头应该开始起来像这样： + +```yaml +--- +title: <教程标题> +min-kubernetes-server-version: v1.8 +--- +``` + + +在代码和配置示例中，不要包含其他版本的注释信息。 +尤其要小心不要在示例中包含不正确的注释信息，例如： + +```yaml +apiVersion: v1 # 早期版本使用... +kind: Pod +... +``` + +## Kubernetes.io 术语列表 + +以下特定于 Kubernetes 的术语和词汇在使用时要保持一致性。 + +{{< table caption = "Kubernetes.io 词汇表" >}} +术语 | 用法 +:--- | :---- +Kubernetes | Kubernetes 的首字母要保持大写。 +Docker | Docker 的首字母要保持大写。 +SIG Docs | SIG Docs 是正确拼写形式，不要用 SIG-DOCS 或其他变体。 +On-premises | On-premises 或 On-prem 而不是 On-premise 或其他变体。 +{{< /table >}} + + + +## 短代码（Shortcodes） {#shortcodes} + +Hugo [短代码（Shortcodes）](https://gohugo.io/content-management/shortcodes) +有助于创建比较漂亮的展示效果。我们的文档支持三个不同的这类短代码。 +**注意** `{{}}`、**小心** `{{}}` 和 **警告** `{{}}`。 + +1. 将要突出显示的文字用短代码的开始和结束形式包围。 +2. 使用下面的语法来应用某种样式： + + ``` + {{}} + 不需要前缀；短代码会自动添加前缀（注意：、小心：等） + {{}} + ``` + +输出的样子是： + +{{< note >}} +你所选择的标记决定了文字的前缀。 +{{< /note >}} + + +### 注释（Note） {#note} + +使用短代码 `{{}}` 来突出显示某种提示或者有助于读者的信息。 + +例如: + +``` +{{}} +在这类短代码中仍然 _可以_ 使用 Markdown 语法。 +{{}} +``` + +输出为： + +{{< note >}} +在这类短代码中仍然 _可以_ 使用 Markdown 语法。 +{{< /note >}} + + +你可以在列表中使用 `{{}}`： + +``` +1. 在列表中使用 note 短代码 + +1. 带嵌套 note 的第二个条目 + + {{}} + 警告、小心和注意短代码可以嵌套在列表中，但是要缩进四个空格。 + 参见[常见短代码问题](#common-shortcode-issues)。 + {{}} + +1. 列表中第三个条目 + +1. 列表中第四个条目 +``` + + +其输出为： + +1. 在列表中使用 note 短代码 + +1. 带嵌套 note 的第二个条目 + + {{< note >}} + 警告、小心和注意短代码可以嵌套在列表中，但是要缩进四个空格。 + 参见[常见短代码问题](#common-shortcode-issues)。 + {{< /note >}} + +1. 列表中第三个条目 + +1. 列表中第四个条目 + + +### 小心（Caution） {#caution} + +使用 `{{}}` 短代码来引起读者对某段信息的重视，以避免遇到问题。 + +例如： + +``` +{{}} +此短代码样式仅对标记之上的一行起作用。 +{{}} +``` + +其输出为： + +{{< caution >}} +此短代码样式仅对标记之上的一行起作用。 +{{< /caution >}} + + +### 警告（Warning） {#warning} + +使用 `{{}}` 来表明危险或者必须要重视的一则信息。 + +例如： + +``` +{{}} +注意事项 +{{}} +``` + +其输出为： + +{{< warning >}} +注意事项 +{{< /warning >}} + + +### Katacoda 嵌套现场环境 + +此按钮允许用户使用 [Katacoda 终端](https://www.katacoda.com/embed/panel) +在其浏览器中运行 Minikube。该环境降低了用户对 Minikube 的入门难度， +只需要一次鼠标点击即可完成，而不需要完全经历 Minikube 和 kubectl 的安装过程。 + +嵌套现场环境配置为运行 `minikube start`，允许用户在文档所在的窗口完成教程。 + +{{< caution >}} +会话限制为 15 分钟。 +{{< /caution >}} + +例如： + +``` +{{}} +``` + +其输出为： + +{{< kat-button >}} + +## 常见的短代码问题 {#common-shortcode-issues} + +### 编号列表 + +短代码会打乱编号列表的编号，除非你在信息和标志之前都缩进四个空格。 + +例如： + +``` +1. 预热到 350˚F +1. 准备好面糊，倒入烘烤盘 + {{}}给盘子抹上油可以达到最佳效果。{{}} +1. 烘烤 20 到 25 分钟，或者直到满意为止。 +``` + +其输出结果为： + +1. 预热到 350˚F +1. 准备好面糊，倒入烘烤盘 + {{< note >}}给盘子抹上油可以达到最佳效果。{{< /note >}} +1. 烘烤 20 到 25 分钟，或者直到满意为止。 + + +### Include 语句 + +如果短代码出现在 include 语境中，会导致网站无法构建。 +你必须将他们插入到上级文档中，分别将开始标记和结束标记插入到 include 语句之前和之后。 +例如： + +``` +{{}} +{{}} +{{}} +``` + + +## Markdown 元素 {#markdown-elements} + +### 换行 {#line-breaks} + +使用单一换行符来隔离块级内容，例如标题、列表、图片、代码块以及其他元素。 +这里的例外是二级标题，必须有两个换行符。 +二级标题紧随一级标题（或标题），中间没有段落或文字。 + +两行的留白有助于在代码编辑器中查看整个内容的结构组织。 + + +### 标题 {#headings} + +访问文档的读者可能会使用屏幕抓取程序或者其他辅助技术。 +[屏幕抓取器](https://en.wikipedia.org/wiki/Screen_reader)是一种线性输出设备, +它们每次输出页面上的一个条目。 +如果页面上内容过多，你可以使用标题来为页面组织结构。 +页面的良好结构对所有读者都有帮助，使得他们更容易浏览或者过滤感兴趣的内容。 + +{{< table caption = "标题约定" >}} +可以 | 不可以 +:--| :----- +更新页面或博客在前言部分中的标题 | 使用一级标题。因为 Hugo 会自动将页面前言部分的标题转化为一级标题。 +使用编号的标题以便内容组织有一个更有意义的结构。| 使用四级到六级标题，除非非常有必要这样。如果你要编写的内容有非常多细节，可以尝试拆分成多个不同页面。 +在非博客内容页面中使用井号（`#`）| 使用下划线 `---` 或 `===` 来标记一级标题。 +使用正常大小写来标示标题。例如：**Extend kubectl with plugins** | 使用首字母大写来标示标题。例如：**Extend Kubectl With Plugins** +{{< /table >}} + + +### 段落 {#paragraphs} + +{{< table caption = "段落约定" >}} +可以 | 不可以 +:--| :----- +尝试不要让段落超出 6 句话。 | 用空格来缩进第一段。例如，⋅⋅⋅段落前面的三个空格会将其缩进。 +使用三个连字符（`---`）来创建水平线。使用水平线来分隔段落内容。例如，在故事中切换场景或者在上下文中切换主题。 | 使用水平线来装饰页面。 +{{< /table >}} + + +### 链接 {#links} + +{{< table caption = "链接约定" >}} +可以 | 不可以 +:--| :----- +插入超级链接时给出它们所链接到的目标内容的上下文。例如：你的机器上某些端口处于开放状态。参见检查所需端口了解更详细信息。| 使用有二义性的术语，如“点击这里”。例如：你的机器上某些端口处于打开状态。参见这里了解详细信息。 +编写 Markdown 风格的链接：`[链接文本](URL)`。例如：`[Hugo 短代码](/zh/docs/contribute/style/hugo-shortcodes/#table-captions)`，输出是[Hugo 短代码](/zh/docs/contribute/style/hugo-shortcodes/#table-captions). | 编写 HTML 风格的超级链接：`访问我们的教程！`，或者创建会打开新 Tab 页或新窗口的链接。例如：`[网站示例](https://example.com){target="_blank"}`。 +{{< /table >}} + + +### 列表 {#lists} + +将一组相互关联的内容组织到一个列表中，以便表达这些条目彼此之间有先后顺序或者某种相互关联关系。 +当屏幕抓取器遇到列表时，无论该列表是否有序，它会告知用户存在一组枚举的条目。 +用户可以使用箭头键来上下移动，浏览列表中条目。 +网站导航链接也可以标记成列表条目，因为说到底他们也是一组相互关联的链接而已。 + + - 如果列表中一个或者多个条目是完整的句子，则在每个条目末尾添加句号。 + 出于一致性考虑，一般要么所有条目要么没有条目是完整句子。 + + {{< note >}} 编号列表如果是不完整的介绍性句子的一部分，可以全部用小写字母，并按照 + 每个条目都是句子的一部分来看待和处理。{{< /note >}} + + + - 在编号列表中，使用数字一（`1.`） + + - 对非排序列表，使用加号（`+`）、星号（`*`）、或者减号（`-`） + + - 在每个列表之后留一个空行 + + - 对于嵌套的列表，相对缩进四个空格（例如，⋅⋅⋅⋅）。 + + - 列表条目可能包含多个段落。每个后续段落都要缩进或者四个空格或者一个制表符。 + + +### 表格 {#tables} + +数据表格的语义用途是呈现表格化的数据。 +用户可以快速浏览表格，但屏幕抓取器需要逐行地处理数据。 +表格标题可以用来给数据表提供一个描述性的标题。 +辅助技术使用 HTML 表格标题元素来在页面结构中辨识表格内容。 + +- 请 [Hugo 短代码](/zh/docs/contribute/style/hugo-shortcodes/#table-captions) + 为表格添加标题。 + + +## 内容最佳实践 {#content-best-practices} + +本节包含一些建议的最佳实践，用来开发清晰、明确一致的文档内容。 + +### 使用现在时态 + +{{< table caption = "使用现在时态" >}} +可以 | 不可以 +:--| :----- +此命令启动代理。| 此命令将启动一个代理。 +{{< /table >}} + +例外：如果需要使用过去时或将来时来表达正确含义时，是可以使用的。 + + +### 使用主动语态 + +{{< table caption = "使用主动语态" >}} +可以 | 不可以 +:--| :----- +你可以使用浏览器来浏览 API。| API 可以被使用浏览器来浏览。 +YAML 文件给出副本个数。 | 副本个数是在 YAML 文件中给出的。 +{{< /table >}} + +例外：如果主动语态会导致句子很难构造时，可以使用被动语态。 + + +### 使用简单直接的语言 + +使用简单直接的语言。避免不必要的短语，例如说“请”。 + +{{< table caption = "使用简单直接语言" >}} +可以 | 不可以 +:--| :----- +要创建 ReplicaSet，... | 如果你想要创建 ReplicaSet，... +参看配置文件。 | 请自行查看配置文件。 +查看 Pods。| 使用下面的命令，我们将会看到 Pods。 +{{< /table >}} + + +### 将读者称为“你” + +{{< table caption = "将读者称为“你”" >}} +可以 | 不可以 +:--| :----- +你可以通过 ... 创建一个 Deployment。 | 通过...我们将创建一个 Deployment。 +在前面的输出中，你可以看到... | 在前面的输出中，我们可以看到... +{{< /table >}} + + +### 避免拉丁短语 + +尽可能使用英语而不是拉丁语缩写。 + +{{< table caption = "避免拉丁语短语" >}} +可以 | 不可以 +:--| :----- +例如，... | e.g., ... +也就是说，...| i.e., ... +{{< /table >}} + +例外：使用 etc. 表示等等。 + + +## 应避免的模式 + +### 避免使用“我们” + +在句子中使用“我们”会让人感到困惑，因为读者可能不知道这里的 +“我们”指的是谁。 + +{{< table caption = "要避免的模式" >}} +可以 | 不可以 +:--| :----- +版本 1.4 包含了 ... | 在 1.4 版本中，我们添加了 ... +Kubernetes 为 ... 提供了一项新功能。 | 我们提供了一项新功能... +本页面教你如何使用 Pods。| 在本页中，我们将会学到如何使用 Pods。 +{{< /table >}} + + +### 避免使用俚语或行话 + +对某些读者而言，英语是其外语。 +避免使用一些俚语或行话有助于他们更方便的理解内容。 + +{{< table caption = "避免使用俚语或行话" >}} +可以 | 不可以 +:--| :----- +Internally, ... | Under the hood, ... +Create a new cluster. | Turn up a new cluster. +{{< /table >}} + + +### 避免关于将来的陈述 + +要避免对将来作出承诺或暗示。如果你需要讨论的是 Alpha 功能特性，可以将相关文字 +放在一个单独的标题下，标示为 alpha 版本信息。 + +### 避免使用很快就会过时的表达 + +避免使用一些很快就会过时的陈述，例如“目前”、“新的”。 +今天而言是新的功能，过了几个月之后就不再是新的了。 + +{{< table caption = "避免使用很快过时的表达" >}} +可以 | 不可以 +:--| :----- +在版本 1.4 中，... | 在当前版本中，... +联邦功能特性提供 ... | 新的联邦功能特性提供 ... +{{< /table >}} + +## {{% heading "whatsnext" %}} + +* 了解[编写新主题](/zh/docs/contribute/style/write-new-topic/). +* 了解[页面内容类型](/zh/docs/contribute/style/page-content-types/). +* 了解[发起 PR](/zh/docs/contribute/new-content/open-a-pr/). diff --git a/content/zh/docs/contribute/style/write-new-topic.md b/content/zh/docs/contribute/style/write-new-topic.md index 671b1108810..4bb8f812543 100644 --- a/content/zh/docs/contribute/style/write-new-topic.md +++ b/content/zh/docs/contribute/style/write-new-topic.md @@ -3,13 +3,10 @@ title: 撰写新主题 content_type: task weight: 20 --- - @@ -18,30 +15,24 @@ This page shows how to create a new topic for the Kubernetes docs. --> 本页面展示如何为 Kubernetes 文档库创建新主题。 - ## {{% heading "prerequisites" %}} - -如[开始贡献](/docs/contribute/start/)中所述，创建 Kubernetes 文档库的分支。 - +如[发起 PR](/zh/docs/contribute/new-content/open-a-pr/)中所述，创建 Kubernetes 文档库的派生副本。 -## 选择页面类型 - - +## 选择页面类型 -当你准备写一个新的主题时，考虑一下最适合你的内容的页面类型： +当你准备编写一个新的主题时，考虑一下最适合你的内容的页面类型： - -{{< table caption = "选择页面类型的准则" >}} +{{< table caption = "选择页面类型的说明" >}} 类型 | 描述 :--- | :---------- -概念 | 每个概念页面负责解释 Kubernetes 的某方面。例如，概念页面可以描述 Kubernetes Deployment 对象，并解释当部署、扩展和更新时，它作为应用程序所扮演的角色。一般来说，概念页面不包括步骤序列，而是提供任务或教程的链接。一个概念主题的示例，请参见 节点。 -任务 | 任务页面展示了如何完成单个任务。这样做的目的是给读者提供一系列的步骤，让他们在阅读时可以实际执行。任务页面可长可短，前提是它始终围绕着某个主题。在任务页面中，可以将简短的解释与要执行的步骤混合在一起。如果需要提供较长的解释，则应在概念主题中进行。相关联的任务和概念主题应该相互链接。一个简短的任务页面的实例，请参见 配置一个使用卷进行存储的 Pod。一个较长的任务页面的实例，请参见 配置活动性和就绪性探针。 -教程 | 教程页面展示如何实现某个目标，该目标将几个 Kubernetes 特性联系在一起。教程可能提供一些步骤序列，读者可以在阅读页面时实际执行这些步骤。或者它可以提供相关代码片段的解释。例如，教程可以提供代码示例的讲解。教程可以包括对 Kubernetes 几个关联特性的简要解释，但应该链接到相关概念主题，以便深入解释各个特性。 +概念（Concept） | 概念页面负责解释 Kubernetes 的某方面。例如，概念页面可以描述 Kubernetes Deployment 对象，并解释当部署、扩展和更新时，它作为应用程序所扮演的角色。一般来说，概念页面不包括步骤序列，而是提供任务或教程的链接。概念主题的示例可参见 节点。 +任务（Task） | 任务页面展示如何完成特定任务。其目的是给读者提供一系列的步骤，让他们在阅读时可以实际执行。任务页面可长可短，前提是它始终围绕着某个主题展开。在任务页面中，可以将简短的解释与要执行的步骤混合在一起。如果需要提供较长的解释，则应在概念主题中进行。相关联的任务和概念主题应该相互链接。一个简短的任务页面的实例可参见 配置 Pod 使用卷存储。一个较长的任务页面的实例可参见 配置活跃性和就绪性探针。 +教程（Tutorial） | 教程页面展示如何实现某个目标，该目标将若干 Kubernetes 功能特性联系在一起。教程可能提供一些步骤序列，读者可以在阅读页面时实际执行这些步骤。或者它可以提供相关代码片段的解释。例如，教程可以提供代码示例的讲解。教程可以包括对 Kubernetes 几个关联特性的简要解释，但有关更深入的特性解释应该链接到相关概念主题。 {{< /table >}} -为每个新页面使用模板。每种页面类型都有一个[模板](/docs/contribute/style/page-templates/)，这个模板可以在编写主题时使用。使用模板有助于确保给定类型主题之间的一致性。 +为每个新页面选择其[内容类型](/zh/docs/contribute/style/page-content-types/)。 +使用页面类型有助于确保给定类型的各主题之间保持一致。 -## 选择标题和文件名 - - +## 选择标题和文件名 -选择一个标题，标题中包含了要通过搜索引擎要查找的关键字。创建一个文件名，使用标题中由连字符分隔的单词。例如，标题为[使用 HTTP 代理访问 Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api/) 的主题的文件名为 `http-proxy-access-api.md`。你不需要在文件名中加上 "kubernetes"，因为 "kubernetes" 已经在主题的 URL 中了，例如： +选择一个标题，确保其中包含希望搜索引擎发现的关键字。 +确定文件名时请使用标题中的单词，由连字符分隔。 +例如，标题为[Using an HTTP Proxy to Access Kubernetes API](/zh/docs/tasks/extend-kubernetes/http-proxy-access-api/) +的主题的文件名为 `http-proxy-access-api.md`。 +你不需要在文件名中加上 "kubernetes"，因为 "kubernetes" 已经在主题的 URL 中了， +例如： - /docs/tasks/access-kubernetes-api/http-proxy-access-api/ + /docs/tasks/extend-kubernetes/http-proxy-access-api/ -## 在页面头部添加主题标题 - - +## 在页面前言中添加主题标题 -在你的主题中，在[页面头部](https://gohugo.io/content-management/front-matter/)设置一个 `title` 字段。页面头部是位于页面顶部三条虚线之间的 YAML 块。下面是一个例子： +在你的主题中，在[前言（front-matter）](https://gohugo.io/content-management/front-matter/) +中设置一个 `title` 字段。 +前言是位于页面顶部三条虚线之间的 YAML 块。下面是一个例子： - - - --- - title: 使用 HTTP 代理访问 Kubernetes API - --- +``` +--- +title: 使用 HTTP 代理访问 Kubernetes API +--- +``` -## 选择目录 - - +## 选择目录 根据页面类型，将新文件放入其中一个子目录中： @@ -134,31 +122,29 @@ Depending on your page type, put your new file in a subdirectory of one of these You can put your file in an existing subdirectory, or you can create a new subdirectory. --> - 你可以将文件放在现有的子目录中，也可以创建一个新的子目录。 -## 将主题放在目录中 - - +## 将主题放在目录中 -目录是使用文档源的目录结构动态构建的。`/content/en/docs/` 下的顶层目录创建顶层导航，它和子目录在目录中都有条目。 +目录是使用文档源的目录结构动态构建的。 +`/content/en/docs/` 下的顶层目录用于创建顶层导航条目， +这些目录和它们的子目录在网站目录中都有对应条目。 - -每个子目录都有一个 `_index.md` 文件，它表示指定子目录内容的主页面。`_index.md` 文件不需要模板。它可以包含有关子目录中主题的概述内容。 +每个子目录都有一个 `_index.md` 文件，它表示的是该子目录内容的主页面。 +`_index.md` 文件不需要模板。它可以包含各子目录中主题的概述内容。 - -默认情况下，目录中的其他文件按字母顺序排序。这几乎不是最好的顺序。要控制子目录中主题的相对排序，请将页面头部的键 `weight:` 设置为整数。通常我们使用 10 的倍数，添加后续主题时 `weight` 值递增。例如，`weight` 为 `10` 的主题将位于 `weight` 为 `20` 的主题之前。 +默认情况下，目录中的其他文件按字母顺序排序。这一般不是最好的顺序。 +要控制子目录中主题的相对排序，请将页面头部的键 `weight:` 设置为整数值。 +通常我们使用 10 的倍数，添加后续主题时 `weight` 值递增。 +例如，`weight` 为 `10` 的主题将位于 `weight` 为 `20` 的主题之前。 -## 在主题中嵌入代码 - - +## 在主题中嵌入代码 -如果你想在主题中嵌入一些代码，可以直接使用标记代码块语法将代码嵌入到文件中。建议用于以下情况（并非详尽列表）： +如果你想在主题中嵌入一些代码，可以直接使用 Markdown 代码块语法将代码嵌入到文件中。 +建议在以下场合（并非详尽列表）使用嵌入代码： - 代码显示来自命令的输出，例如 `kubectl get deploy mydeployment -o json | jq '.status'`。 -- 代码不够通用，用户无法验证。例如，你可以嵌入 YAML 文件来创建一个依赖于特定 [FlexVolume](/docs/concepts/storage/volumes#flexvolume)实现的 Pod。 -- 该代码是一个不完整的示例，因为它的目的是高亮显示大文件的部分内容。例如，在描述自定义 [PodSecurityPolicy](/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy)的方法时，出于某些原因，你可以直接在主题文件中提供一个简短的片段。 -- 由于其他原因，该代码不适合用户验证。例如，当使用 `kubectl edit` 命令描述如何将新属性添加到资源时，你可以提供一个仅包含要添加的属性的简短示例。 +- 代码不够通用，用户无法验证。例如，你可以嵌入 YAML 文件来创建一个依赖于特定 + [FlexVolume](/zh/docs/concepts/storage/volumes#flexvolume) 实现的 Pod。 +- 该代码是一个不完整的示例，因为其目的是突出展现某个大文件中的部分内容。 + 例如，在描述出于某些原因定制 + [PodSecurityPolicy](/zh/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy) + 的方法时，你可以在主题文件中直接提供一个短的代码段。 +- 由于某些其他原因，该代码不适合用户验证。 + 例如，当使用 `kubectl edit` 命令描述如何将新属性添加到资源时， + 你可以提供一个仅包含要添加的属性的简短示例。 -## 引用来自其他文件的代码 - - +## 引用来自其他文件的代码 -在主题中引用代码的另一种方法是创建一个新的、完整的示例文件（或示例文件组），然后从主题中引用这些示例。当示例是通用的和可重用的，并且你希望读者自己验证时，使用此方法引用示例 YAML 文件。 +在主题中引用代码的另一种方法是创建一个新的、完整的示例文件（或文件组）， +然后在主题中引用这些示例。当示例是通用的和可重用的，并且你希望读者自己验证时， +使用此方法引用示例 YAML 文件。 +添加新的独立示例文件（如 YAML 文件）时，将代码放在 `/examples/` 的某个子目录中， +其中 `` 是该主题的语言。在主题文件中使用 `codenew` 短代码： -添加新的独立示例文件（如 YAML 文件）时，将代码放在 `/examples/` 的某个子目录中，其中 `` 是该主题的语言。在主题文件中使用 `codenew` 短代码： - -
{{< codenew file="<RELPATH>/my-example-yaml>" >}}
+```none +{{/my-example-yaml>" */>}} +``` -`` 是要引用的文件的路径，相对于 `examples` 目录。以下 Hugo 短代码引用了位于 `/content/en/examples/pods/storage/gce-volume.yaml` 的 YAML 文件。 +`` 是要引用的文件的路径，相对于 `examples` 目录。以下 Hugo +短代码引用了位于 `/content/en/examples/pods/storage/gce-volume.yaml` 的 YAML +文件。 ```none {{}} @@ -249,26 +244,23 @@ from interpreting them, use C-style comments directly after the `<` and before the `>` characters. View the code for this page for an example. --> {{< note >}} -要展示上述示例中的原始 Hugo 短代码并避免 Hugo 对其进行解释，请直接在 `<` 字符之后和 `>` 字符之前使用 C 样式注释。请查看此页面的代码。 +要展示上述示例中的原始 Hugo 短代码并避免 Hugo 对其进行解释， +请直接在 `<` 字符之后和 `>` 字符之前使用 C 样式注释。请查看此页面的代码。 {{< /note >}} -## 显示如何从配置文件创建 API 对象 - - -如果需要演示如何基于配置文件创建 API 对象，请将配置文件放在 `/examples` 下的某个子目录中。 - - +## 显示如何从配置文件创建 API 对象 + +如果需要演示如何基于配置文件创建 API 对象，请将配置文件放在 `/examples` +下的某个子目录中。 在主题中展示以下命令： @@ -283,39 +275,33 @@ Travis CI for the Website automatically runs this test case when PRs are submitted to ensure all examples pass the tests. --> {{< note >}} -将新的 YAML 文件添加到 `/examples` 目录时，请确保该文件也在 `/examples_test.go` 文件中被引用。当提交拉取请求时，网站的 Travis CI 会自动运行此测试用例，以确保所有示例都通过测试。 +将新的 YAML 文件添加到 `/examples` 目录时，请确保该文件也在 +`/examples_test.go` 文件中被引用。 +当提交拉取请求时，网站的 Travis CI 会自动运行此测试用例，以确保所有示例都通过测试。 {{< /note >}} - -有关使用此技术的主题的示例，请参见[运行单实例有状态的应用](/docs/tutorials/stateful-application/run-stateful-application/)。 +有关使用此技术的主题的示例，请参见 +[运行单实例有状态的应用](/zh/docs/tutorials/stateful-application/run-stateful-application/)。 +## 向主题添加图片 -## 向主题添加镜像 +将图片文件放入 `/images` 目录。首选的图片格式是 SVG。 - - -将镜像文件放入 `/images` 目录。首选的镜像格式是 SVG。 - - - - ## {{% heading "whatsnext" %}} -* 学习[使用页面模板](/docs/home/contribute/page-templates/)。 -* 学习[展示你的修改](/docs/home/contribute/stage-documentation-changes/)。 -* 学习[创建一个拉取请求](/docs/home/contribute/create-pull-request/)。 + +* 了解[使用页面内容类型](/zh/docs/contribute/style/page-content-types/). +* 了解[创建 PR](/zh/docs/contribute/new-content/open-a-pr/).
配置参数