页面内容类型

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

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

内容部分

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

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

<!-- overview -->

<!-- body -->

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

标题字符串示例

• 下一步
• 前提条件
• 目标
• 清理
• 概要
• 另请参阅
• 选项

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

## {{% 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 Deployment 对象，并解释它在部署、扩展和更新后作为应用程序所起的作用。通常，概念页面不包括步骤序列，而是提供指向任务或教程的链接。

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

概念页面分为三个部分

overview 和 body 部分以注释的形式出现在概念页面中。您可以使用 heading 短代码向页面添加 whatsnext 部分。

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

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

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

任务

任务页面展示了如何做一件事情，通常是通过给出简短的步骤序列。任务页面有最少的解释，但通常提供指向概念主题的链接，这些主题提供相关的背景和知识。

要编写新的任务页面，请在 /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

下一步是什么

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