页面内容类型

Kubernetes 文档遵循几种页面内容类型

• 概念
• 任务
• 教程
• 参考

内容部分

每种页面内容类型都包含由 Markdown 注释和 HTML 标题定义的多节内容。您可以使用 heading 短代码来添加内容标题。注释和标题有助于维护页面内容类型的结构。

定义页面内容部分的 Markdown 注释示例

<!-- overview -->

<!-- body -->

要创建内容页面中的常用标题，请使用带有标题字符串的 heading 短代码。

标题字符串示例

• 下一步
• 先决条件
• 目标
• 清理
• 摘要
• 相关文章
• options

例如，要创建 whatsnext 标题，请添加带有“whatsnext”字符串的 heading 短代码

## {{% heading "whatsnext" %}}

您可以按如下方式声明 prerequisites 标题

## {{% heading "prerequisites" %}}

heading 短代码接受一个字符串参数。标题字符串参数与 i18n/<lang>/<lang>.toml 文件中的变量前缀匹配。例如

i18n/en/en.toml:

[whatsnext_heading]
other = "What's next"

i18n/ko.toml:

[whatsnext_heading]
other = "다음 내용"

内容类型

每种内容类型都非正式地定义了其预期的页面结构。使用建议的页面部分来创建页面内容。

概念

概念页面解释了 Kubernetes 的某些方面。例如，概念页面可能描述 Kubernetes Deployment 对象，并解释其在部署、扩展和更新应用程序后的作用。通常，概念页面不包含一系列步骤，而是提供指向任务或教程的链接。

要编写新的概念页面，请在 /content/en/docs/concepts 目录的子目录中创建一个 Markdown 文件，该文件具有以下特征

概念页面分为三个部分

overview 和 body 部分显示为概念页面中的注释。您可以使用 heading 短代码将 whatsnext 部分添加到页面。

用内容填充每个部分。遵循以下指南

• 使用 H2 和 H3 标题组织内容。
• 对于 overview，用一个段落设置主题的上下文。
• 对于 body，解释概念。
• 对于 whatsnext，提供一个项目符号列表（最多 5 个），以便您能了解有关该概念的更多信息。

Annotations 是一个已发布的示例概念页面。

任务

任务页面展示了如何完成某项单一任务，通常是通过一系列简短的步骤。任务页面只包含最少的解释，但通常会提供指向提供相关背景和知识的概念主题的链接。

要编写新的任务页面，请在 /content/en/docs/tasks 目录的子目录中创建一个 Markdown 文件，该文件具有以下特征

overview、steps 和 discussion 部分显示为任务页面中的注释。您可以使用 heading 短代码将 prerequisites 和 whatsnext 部分添加到页面。

在每个部分内，编写您的内容。使用以下指南

• 使用至少一个 H2 标题（带有两个前导 # 字符）。模板会自动为这些部分命名。
• 对于 overview，使用一个段落来设置整个主题的上下文。
• 对于 prerequisites，尽可能使用项目符号列表。在 include 下方开始添加其他先决条件。默认的先决条件包括一个正在运行的 Kubernetes 集群。
• 对于 steps，使用编号列表。
• 对于讨论，使用普通内容来扩展 steps 中涵盖的信息。
• 对于 whatsnext，提供一个最多包含 5 个主题的项目符号列表，读者可能会对这些主题感兴趣。

已发布的任务主题示例是 使用 HTTP 代理访问 Kubernetes API。

教程

教程页面展示了如何完成比单个任务更大的目标。通常，教程页面有多个部分，每个部分都有一个步骤序列。例如，教程可能会提供一个代码示例的演练，该示例说明了 Kubernetes 的某个特定功能。教程可以包含表面级的解释，但应链接到相关的概念主题以进行深入解释。

要编写新的教程页面，请在 /content/en/docs/tutorials 目录的子目录中创建一个 Markdown 文件，该文件具有以下特征

overview、objectives 和 lessoncontent 部分显示为教程页面中的注释。您可以使用 heading 短代码将 prerequisites、cleanup 和 whatsnext 部分添加到页面。

在每个部分内，编写您的内容。使用以下指南

• 使用至少一个 H2 标题（带有两个前导 # 字符）。模板会自动为这些部分命名。
• 对于 overview，使用一个段落来设置整个主题的上下文。
• 对于 prerequisites，尽可能使用项目符号列表。在默认包含的先决条件下方添加其他先决条件。
• 对于 objectives，使用项目符号列表。
• 对于 lessoncontent，根据需要使用编号列表和叙述性内容的组合。
• 对于 cleanup，使用编号列表描述完成任务后清理集群状态的步骤。
• 对于 whatsnext，提供一个最多包含 5 个主题的项目符号列表，读者可能会对这些主题感兴趣。

已发布的教程主题示例是 使用 Deployment 运行无状态应用程序。

参考

组件工具参考页面显示了 Kubernetes 组件工具的描述和标志选项输出。每个页面都由脚本生成，使用组件工具命令。

工具参考页面有几个可能的节

已发布的工具参考页面示例是

• kubeadm init
• kube-apiserver
• kubectl

下一步

• 了解 样式指南
• 了解 内容指南
• 了解 内容组织