页面内容类型

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

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

内容部分

每个页面内容类型都包含由 Markdown 注释和 HTML 标题定义的多个部分。你可以使用 heading 短代码将内容标题添加到页面中。注释和标题有助于维护页面内容类型的结构。

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

<!-- overview -->

<!-- body -->

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

标题字符串示例

• 后续步骤
• 先决条件
• 目标
• 清理
• 概要
• 另请参阅
• 选项

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

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

你可以按如下方式声明 先决条件 标题

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

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

i18n/en.toml:

[whatsnext_heading]
other = "What's next"

i18n/ko.toml:

[whatsnext_heading]
other = "다음 내용"

内容类型

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

概念

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

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

概念页面分为三个部分

概述 和 正文 部分在概念页面中显示为注释。你可以使用 heading 短代码将 后续步骤 部分添加到页面中。

用内容填充每个部分。请遵循以下准则

• 使用 H2 和 H3 标题组织内容。
• 对于 概述，请使用一段话来设置主题的上下文。
• 对于 正文，请解释概念。
• 对于 后续步骤，请提供一个主题项目符号列表（最多 5 个），以详细了解该概念。

注解 是已发布的概念页面示例。

任务

任务页面显示了如何完成一项任务，通常是通过给出简短的步骤序列来实现的。任务页面的解释很少，但通常会提供指向提供相关背景和知识的概念主题的链接。

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

概述、步骤 和 讨论 部分在任务页面中显示为注释。你可以使用 heading 短代码将 先决条件 和 后续步骤 部分添加到页面中。

在每个部分中，编写你的内容。请使用以下准则

• 尽量少用 H2 标题（带有两个前导 # 字符）。这些部分本身由模板自动添加标题。
• 对于 概述，请使用一段话来设置整个主题的上下文。
• 对于 先决条件，请尽可能使用项目符号列表。从 include 下方开始添加其他先决条件。默认的先决条件包括一个正在运行的 Kubernetes 集群。
• 对于 步骤，请使用编号列表。
• 对于 讨论，请使用正常内容来扩展 步骤 中涵盖的信息。
• 对于 后续步骤，请提供一个包含最多 5 个主题的项目符号列表，这些主题是读者接下来可能感兴趣阅读的内容。

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

教程

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

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

概述、目标 和 课程内容 部分在教程页面中显示为注释。你可以使用 heading 短代码将 先决条件、清理 和 后续步骤 部分添加到页面中。

在每个部分中，编写你的内容。请使用以下准则

• 尽量少用 H2 标题（带有两个前导 # 字符）。这些部分本身由模板自动添加标题。
• 对于 概述，请使用一段话来设置整个主题的上下文。
• 对于 先决条件，请尽可能使用项目符号列表。在默认包含的先决条件下方添加其他先决条件。
• 对于 目标，请使用项目符号列表。
• 对于 课程内容，请根据需要混合使用编号列表和叙述性内容。
• 对于 清理，请使用编号列表来描述在完成任务后清理集群状态的步骤。
• 对于 后续步骤，请提供一个包含最多 5 个主题的项目符号列表，这些主题是读者接下来可能感兴趣阅读的内容。

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

参考

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

工具参考页面包含多个可能的章节

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

• kubeadm init
• kube-apiserver
• kubectl

下一步

• 了解 风格指南
• 了解 内容指南
• 了解 内容组织