页面内容类型

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

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

内容节

每种页面内容类型都包含由 Markdown 注释和 HTML 标题定义的一些节。你可以使用 heading shortcode 为页面添加内容标题。注释和标题有助于维护页面内容类型的结构。

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

<!-- overview -->

<!-- body -->

要在你的内容页面中创建常用标题，请使用带标题字符串的 heading shortcode。

标题字符串示例

• whatsnext
• prerequisites
• objectives
• cleanup
• synopsis
• seealso
• options

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

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

你可以按如下方式声明一个 prerequisites 标题

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

heading shortcode 期望一个字符串参数。标题字符串参数与 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 shortcode 将 whatsnext 节添加到页面中。

用内容填充每个节。遵循这些指南：

• 使用 H2 和 H3 标题组织内容。
• 对于 overview，用一个段落设置主题的背景。
• 对于 body，解释概念。
• 对于 whatsnext，提供一个有关此概念的项目的无序列表（最多 5 个），以便读者进一步学习。

注解（Annotations） 是一个已发布的示例概念页面。

任务

任务页面展示如何做一件单一的事情，通常通过提供一个简短的步骤序列。任务页面解释最少，但通常提供链接到相关的概念主题，以提供相关的背景和知识。

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

overview、steps 和 discussion 节在任务页面中显示为注释。你可以使用 heading shortcode 将 prerequisites 和 whatsnext 节添加到页面中。

在每个节中撰写你的内容。使用以下指南：

• 最少使用 H2 标题（带有两个前导 # 字符）。这些节本身由模板自动命名。
• 对于 overview，使用一个段落为整个主题设置上下文。
• 对于 prerequisites，尽可能使用无序列表。在 include 下开始添加额外的先决条件。默认的先决条件包括一个正在运行的 Kubernetes 集群。
• 对于 steps，使用有序列表。
• 对于 discussion，使用正常内容来扩展 steps 中涵盖的信息。
• 对于 whatsnext，提供一个无序列表（最多 5 个）列出读者可能感兴趣的后续主题。

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

教程

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

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

overview、objectives 和 lessoncontent 节在教程页面中显示为注释。你可以使用 heading shortcode 将 prerequisites、cleanup 和 whatsnext 节添加到页面中。

在每个节中撰写你的内容。使用以下指南：

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

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

参考

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

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

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

• kubeadm init
• kube-apiserver
• kubectl

接下来

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