为 Kubernetes 文档做贡献

Edit This Page

使用页面模板

当贡献新主题时,选择下列模板中的一种。 这使指定页面的用户体验标准化。

页面模板在 kubernetes/website 仓库的 layouts/partials/templates 目录中。

注意:

每个新主题都需要使用模板。如果你不确定新主题要使用哪个模板,请从概念模板开始。

概念模板

每个概念页面负责解释 Kubernetes 的某方面。例如,概念页面可以描述 Kubernetes Deployment 对象,并解释当部署、扩展和更新时,它作为应用程序所扮演的角色。一般来说,概念页面不包括步骤序列,而是提供任务或教程的链接。

要编写新的概念页面,请在 /content/en/docs/concepts 目录的子目录中创建一个 Markdown 文件,其特点如下:

  • 在页面的 YAML 头部,设置 content_template: templates/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 个主题。

使用概念模板的已发布主题的一个示例是注解。你当前正在阅读的页面也使用概念模板。

任务模板

任务页面展示了如何完成单个任务,通常是通过给出一个简短的步骤序列。任务页面中解释性质的文字极少,但是通常会给出提供相关背景和知识的概念主题的链接。

要编写新的任务页面,请在 /content/en/docs/tasks 目录的子目录中创建一个 Markdown 文件,其特点如下:

  • 在页面的 YAML 头部,设置 content_template: templates/task
  • 在页面的 body 中,设置所需的 capture 变量和所有想要包含的变量:

    变量必需?
    overview
    prerequisites
    steps
    discussion
    whatsnext
页面的 body 看起来像这样(移除所有不想要的可选 `capture` 变量):

```
{{% capture overview %}}

{{% /capture %}}

{{% capture prerequisites %}}

{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}

{{% /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

教程模板

教程页面展示了如何完成比单个任务更大的目标。通常教程页有几个章节,每个章节都有步骤说明。例如,教程可以提供说明 Kubernetes 的特定特性的代码示例的演练。教程可以包括表层解释,但是应该链接到相关的概念主题以进行深入解释。

要编写新的教程页面,请在 /content/en/docs/tutorials 目录的子目录中创建一个 Markdown 文件,其特点如下:

  • 在页面的 YAML 头部,设置 content_template: templates/tutorial
  • 在页面的 body 中,设置所需的 capture 变量和所有想要包含的变量:

    变量必需?
    overview
    prerequisites
    objectives
    lessoncontent
    cleanup
    whatsnext
页面的 body 看起来像这样(移除所有不想要的可选 `capture` 变量):

```
{{% capture overview %}}

{{% /capture %}}

{{% capture prerequisites %}}

{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}

{{% /capture %}}

{{% capture objectives %}}

{{% /capture %}}

{{% capture lessoncontent %}}

{{% /capture %}}

{{% capture cleanup %}}

{{% /capture %}}

{{% capture whatsnext %}}

{{% /capture %}}
```
  • 在每个章节中写下你的内容。请遵从以下规则:
    • 使用不低于 H2 级别的标题(避免使用 H1 的标题,但 H3、H4 的标题是可以的)(以两个 # 字符开头)。这些章节本身是由模板自动命名的。
    • overview 节,用一个段落的篇幅来为当前话题设定语境。
    • prerequisites 节,如果有可能,请使用列表。在默认情况下添加额外的先决条件。
    • objectives 节,使用列表。
    • lessoncontent 节,适当地使用编号列表和叙述内容的组合。
    • cleanup 节,使用编号列表描述完成任务后清理集群状态的步骤。
    • whatsnext 节,列出读者接下来可能感兴趣的最多 5 个主题。

使用教程模板的已发布主题的一个示例是使用部署运行无状态应用程序

接下来

反馈