页面内容类型

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

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

内容部分

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

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

<!-- overview -->

<!-- body -->

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

标题字符串示例

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

例如，要创建一个 `whatsnext` 标题，请将标题短代码与字符串 "whatsnext" 一起添加

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

您可以如下声明一个 `prerequisites` 标题

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

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

i18n/en.toml:

[whatsnext_heading]
other = "What's next"

i18n/ko.toml:

[whatsnext_heading]
other = "다음 내용"

内容类型

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

概念

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

要编写新的概念页面，请在 `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`，使用编号列表。
• 对于 discussion，使用普通内容来扩展 `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 个主题的项目符号列表，读者可能希望接下来阅读这些主题。

发布的教程主题示例是 使用部署运行无状态应用程序.

参考

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

工具参考页面可能有多个部分

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

• kubeadm init
• kube-apiserver
• kubectl

下一步

• 了解有关 样式指南 的信息
• 了解有关 内容指南 的信息
• 了解有关 内容组织 的信息