文档样式概述

• 1: 文档内容指南
• 2: 文档样式指南
• 3: 撰写新主题
• 4: 页面内容类型
• 5: 内容组织
• 6: 定制 Hugo 短代码

1 - 文档内容指南

本页包含 Kubernetes 文档的一些指南。

如果你不清楚哪些事情是可以做的，请加入到 Kubernetes Slack 的 #sig-docs 频道提问！ 你可以在 http://slack.k8s.io 注册到 Kubernetes Slack。

关于为 Kubernetes 文档创建新内容的更多信息，可参考 样式指南。

概述

Kubernetes 网站（包括其文档）源代码位于 kubernetes/website 仓库中。

在 kubernetes/website/content/<语言代码>/docs 目录下, 绝大多数 Kubernetes 文档都是特定于 Kubernetes 项目的。

可以发布的内容

只有当以下条件满足时，Kubernetes 文档才允许第三方项目的内容：

• 内容所描述的软件在 Kubernetes 项目内
• 内容所描述的软件不在 Kubernetes 项目内，却是让 Kubernetes 正常工作所必需的
• 内容是被 kubernetes.io 域名收编的，或者是其他位置的标准典型内容

第三方内容

Kubernetes 文档包含 Kubernetes 项目下的多个项目的应用示例。 这里的 Kubernetes 项目指的是 kubernetes 和 kubernetes-sigs GitHub 组织 下的项目。

链接到 Kubernetes 项目中活跃的内容是一直允许的。

Kubernetes 需要某些第三方内容才能正常工作。例如 容器运行时（containerd、CRI-O、Docker）， 联网策略 （CNI 插件），Ingress 控制器 以及日志等。

只有对应的第三方开源软件（OSS）是运行 Kubernetes 所必需的，才可以在文档中包含 指向这些 Kubernetes 项目之外的软件的链接。

双重来源的内容

只要有可能，Kubernetes 文档应该指向标准典型的信息源而不是直接托管多重来源的内容。

双重来源的内容需要双倍（甚至更多）的投入才能维护，而且通常很快就会变得停滞不前。

说明： 如果你是一个 Kubernetes 项目的维护者，需要帮忙托管你的文档， 请在 Kubernetes 的 #sig-docs 频道 提出请求。

更多信息

如果你对允许出现的内容有疑问，请加入到 Kubernetes Slack 的 #sig-docs 频道提问！

接下来

• 阅读样式指南。

2 - 文档样式指南

本页讨论 Kubernetes 文档的样式指南。 这些仅仅是指南而不是规则。 你可以自行决定，且欢迎使用 PR 来为此文档提供修改意见。

关于为 Kubernetes 文档贡献新内容的更多信息，可以参考 文档内容指南。

样式指南的变更是 SIG Docs 团队集体决定。 如要提议更改或新增条目，请先将其添加到下一次 SIG Docs 例会的 议程表 上，并按时参加会议讨论。

说明： Kubernetes 文档使用带调整的 Goldmark Markdown 解释器 和一些 Hugo 短代码 来支持词汇表项、Tab 页以及特性门控标注。

语言

Kubernetes 文档已经被翻译为多个语种 （参见 本地化 READMEs）。

为文档提供一种新的语言翻译的途径可以在 本地化 Kubernetes 文档中找到。

英语文档使用美国英语的拼写和语法。

文档格式标准

对 API 对象使用大写驼峰式命名法

当你与指定的 API 对象进行交互时，使用 大写驼峰式命名法， 也被称为帕斯卡拼写法. 通常在讨论 API 对象时，使用 句子式大写.

不要将 API 对象的名称切分成多个单词。例如，使用 PodTemplateList，不要 使用 Pod Template List。

引用 API 对象时不必强调 “object（对象）”，除非省略“object（object）” 会使得文字读起来很别扭。

在占位符中使用尖括号

在占位符中使用尖括号，并让读者知道其中代表的事物。例如：

1. 显示 Pod 信息：

    kubectl describe pod <pod-名称> -n <名字空间>
   

   如果名字空间被忽略，默认为 default，你可以忽略 '-n' 参数。

用粗体字表现用户界面元素

定义或引入新术语时使用斜体

使用代码样式表现文件名、目录和路径

在引号内使用国际标准标点

行间代码格式

为行间代码、命令与 API 对象使用代码样式

对于 HTML 文档中的行间代码，使用 <code> 标记。 在 Markdown 文档中，使用反引号（`）。

说明： 网站支持为代码示例使用语法加亮，不过指定语法加亮是可选的。 代码段的语法加亮要遵从对比度指南

为对象字段名和名字空间使用代码风格

用代码样式书写 Kubernetes 命令工具和组件名

用工具或组件名称开始一句话

尽量使用通用描述而不是组件名称

使用普通样式表达字符串和整数字段值

对于字符串或整数，使用正常样式，不要带引号。

代码段格式

不要包含命令行提示符

将命令和输出分开

例如：

验证 Pod 已经在你所选的节点上运行：

kubectl get pods --output=wide

输出类似于：

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

为 Kubernetes 示例给出版本

代码示例或者配置示例如果包含版本信息，应该与对应的文字描述一致。

如果所给的信息是特定于具体版本的，需要在 任务模版 或教程模版 的 prerequisites 小节定义 Kubernetes 版本。 页面保存之后，prerequisites 小节会显示为 开始之前。

如果要为任务或教程页面指定 Kubernetes 版本，可以在文件的前言部分包含 min-kubernetes-server-version 信息。

如果示例 YAML 是一个独立文件，找到并审查包含该文件的主题页面。 确认使用该独立 YAML 文件的主题都定义了合适的版本信息。 如果独立的 YAML 文件没有在任何主题中引用，可以考虑删除该文件， 而不是继续更新它。

例如，如果你在编写一个教程，与 Kubernetes 1.8 版本相关。那么你的 Markdown 文件的文件头应该开始起来像这样：

---
title: <教程标题>
min-kubernetes-server-version: v1.8
---

在代码和配置示例中，不要包含其他版本的注释信息。 尤其要小心不要在示例中包含不正确的注释信息，例如：

apiVersion: v1 # 早期版本使用...
kind: Pod
...

Kubernetes.io 术语列表

以下特定于 Kubernetes 的术语和词汇在使用时要保持一致性。

短代码（Shortcodes）

Hugo 短代码（Shortcodes） 有助于创建比较漂亮的展示效果。我们的文档支持三个不同的这类短代码。 注意 {{< note >}}、小心 {{< caution >}} 和 警告 {{< warning >}}。

1. 将要突出显示的文字用短代码的开始和结束形式包围。

2. 使用下面的语法来应用某种样式：

   {{< note >}}
   不需要前缀；短代码会自动添加前缀（注意：、小心：等）
   {{< /note >}}
   

输出的样子是：

说明： 你所选择的标记决定了文字的前缀。

注释（Note）

使用短代码 {{< note >}} 来突出显示某种提示或者有助于读者的信息。

例如:

{{< note >}}
在这类短代码中仍然 _可以_ 使用 Markdown 语法。
{{< /note >}}

输出为：

说明： 在这类短代码中仍然 可以 使用 Markdown 语法。

你可以在列表中使用 {{< note >}}：

1. 在列表中使用 note 短代码

1. 带嵌套 note 的第二个条目

   {{< note >}}
   警告、小心和注意短代码可以嵌套在列表中，但是要缩进四个空格。
   参见[常见短代码问题](#common-shortcode-issues)。
   {{< /note >}}

1. 列表中第三个条目

1. 列表中第四个条目

其输出为：

1. 在列表中使用 note 短代码

2. 带嵌套 note 的第二个条目

   说明： 警告、小心和注意短代码可以嵌套在列表中，但是要缩进四个空格。 参见常见短代码问题。

3. 列表中第三个条目

4. 列表中第四个条目

小心（Caution）

使用 {{< caution >}} 短代码来引起读者对某段信息的重视，以避免遇到问题。

例如：

{{< caution >}}
此短代码样式仅对标记之上的一行起作用。
{{< /caution >}}

其输出为：

注意： 此短代码样式仅对标记之上的一行起作用。

警告（Warning）

使用 {{< warning >}} 来表明危险或者必须要重视的一则信息。

例如：

{{< warning >}}
注意事项
{{< /warning >}}

其输出为：

警告： 注意事项

Katacoda 嵌套现场环境

此按钮允许用户使用 Katacoda 终端 在其浏览器中运行 Minikube。该环境降低了用户对 Minikube 的入门难度， 只需要一次鼠标点击即可完成，而不需要完全经历 Minikube 和 kubectl 的安装过程。

嵌套现场环境配置为运行 minikube start，允许用户在文档所在的窗口完成教程。

注意： 会话限制为 15 分钟。

例如：

{{< kat-button >}}

其输出为：

常见的短代码问题

编号列表

短代码会打乱编号列表的编号，除非你在信息和标志之前都缩进四个空格。

例如：

1. 预热到 350˚F
1. 准备好面糊，倒入烘烤盘
    {{< note >}}给盘子抹上油可以达到最佳效果。{{< /note >}}
1. 烘烤 20 到 25 分钟，或者直到满意为止。

其输出结果为：

1. 预热到 350˚F
2. 准备好面糊，倒入烘烤盘

   说明： 给盘子抹上油可以达到最佳效果。

3. 烘烤 20 到 25 分钟，或者直到满意为止。

Include 语句

如果短代码出现在 include 语境中，会导致网站无法构建。 你必须将他们插入到上级文档中，分别将开始标记和结束标记插入到 include 语句之前和之后。 例如：

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Markdown 元素

换行

使用单一换行符来隔离块级内容，例如标题、列表、图片、代码块以及其他元素。 这里的例外是二级标题，必须有两个换行符。 二级标题紧随一级标题（或标题），中间没有段落或文字。

两行的留白有助于在代码编辑器中查看整个内容的结构组织。

标题

访问文档的读者可能会使用屏幕抓取程序或者其他辅助技术。 屏幕抓取器是一种线性输出设备, 它们每次输出页面上的一个条目。 如果页面上内容过多，你可以使用标题来为页面组织结构。 页面的良好结构对所有读者都有帮助，使得他们更容易浏览或者过滤感兴趣的内容。

段落

链接

列表

将一组相互关联的内容组织到一个列表中，以便表达这些条目彼此之间有先后顺序或者某种相互关联关系。 当屏幕抓取器遇到列表时，无论该列表是否有序，它会告知用户存在一组枚举的条目。 用户可以使用箭头键来上下移动，浏览列表中条目。 网站导航链接也可以标记成列表条目，因为说到底他们也是一组相互关联的链接而已。

• 如果列表中一个或者多个条目是完整的句子，则在每个条目末尾添加句号。 出于一致性考虑，一般要么所有条目要么没有条目是完整句子。

  说明： 编号列表如果是不完整的介绍性句子的一部分，可以全部用小写字母，并按照 每个条目都是句子的一部分来看待和处理。

• 在编号列表中，使用数字一（1.）

• 对非排序列表，使用加号（+）、星号（*）、或者减号（-）

• 在每个列表之后留一个空行

• 对于嵌套的列表，相对缩进四个空格（例如，⋅⋅⋅⋅）。

• 列表条目可能包含多个段落。每个后续段落都要缩进或者四个空格或者一个制表符。

表格

数据表格的语义用途是呈现表格化的数据。 用户可以快速浏览表格，但屏幕抓取器需要逐行地处理数据。 表格标题可以用来给数据表提供一个描述性的标题。 辅助技术使用 HTML 表格标题元素来在页面结构中辨识表格内容。

• 请 Hugo 短代码 为表格添加标题。

内容最佳实践

本节包含一些建议的最佳实践，用来开发清晰、明确一致的文档内容。

使用现在时态

例外：如果需要使用过去时或将来时来表达正确含义时，是可以使用的。

使用主动语态

例外：如果主动语态会导致句子很难构造时，可以使用被动语态。

使用简单直接的语言

使用简单直接的语言。避免不必要的短语，例如说“请”。

将读者称为“你”

避免拉丁短语

尽可能使用英语而不是拉丁语缩写。

例外：使用 etc. 表示等等。

应避免的模式

避免使用“我们”

在句子中使用“我们”会让人感到困惑，因为读者可能不知道这里的 “我们”指的是谁。

避免使用俚语或行话

对某些读者而言，英语是其外语。 避免使用一些俚语或行话有助于他们更方便的理解内容。

避免关于将来的陈述

要避免对将来作出承诺或暗示。如果你需要讨论的是 Alpha 功能特性，可以将相关文字 放在一个单独的标题下，标示为 alpha 版本信息。

避免使用很快就会过时的表达

避免使用一些很快就会过时的陈述，例如“目前”、“新的”。 今天而言是新的功能，过了几个月之后就不再是新的了。

接下来

• 了解编写新主题.
• 了解页面内容类型.
• 了解发起 PR.

3 - 撰写新主题

本页面展示如何为 Kubernetes 文档库创建新主题。

准备开始

如发起 PR中所述，创建 Kubernetes 文档库的派生副本。

选择页面类型

当你准备编写一个新的主题时，考虑一下最适合你的内容的页面类型：

为每个新页面选择其内容类型。 使用页面类型有助于确保给定类型的各主题之间保持一致。

选择标题和文件名

选择一个标题，确保其中包含希望搜索引擎发现的关键字。 确定文件名时请使用标题中的单词，由连字符分隔。 例如，标题为Using an HTTP Proxy to Access Kubernetes API 的主题的文件名为 http-proxy-access-api.md。 你不需要在文件名中加上 "kubernetes"，因为 "kubernetes" 已经在主题的 URL 中了， 例如：

   /docs/tasks/extend-kubernetes/http-proxy-access-api/

在页面前言中添加主题标题

在你的主题中，在前言（front-matter） 中设置一个 title 字段。 前言是位于页面顶部三条虚线之间的 YAML 块。下面是一个例子：

---
title: 使用 HTTP 代理访问 Kubernetes API
---

选择目录

根据页面类型，将新文件放入其中一个子目录中：

• /content/en/docs/tasks/
• /content/en/docs/tutorials/
• /content/en/docs/concepts/

你可以将文件放在现有的子目录中，也可以创建一个新的子目录。

将主题放在目录中

目录是使用文档源的目录结构动态构建的。 /content/en/docs/ 下的顶层目录用于创建顶层导航条目， 这些目录和它们的子目录在网站目录中都有对应条目。

每个子目录都有一个 _index.md 文件，它表示的是该子目录内容的主页面。 _index.md 文件不需要模板。它可以包含各子目录中主题的概述内容。

默认情况下，目录中的其他文件按字母顺序排序。这一般不是最好的顺序。 要控制子目录中主题的相对排序，请将页面头部的键 weight: 设置为整数值。 通常我们使用 10 的倍数，添加后续主题时 weight 值递增。 例如，weight 为 10 的主题将位于 weight 为 20 的主题之前。

在主题中嵌入代码

如果你想在主题中嵌入一些代码，可以直接使用 Markdown 代码块语法将代码嵌入到文件中。 建议在以下场合（并非详尽列表）使用嵌入代码：

• 代码显示来自命令的输出，例如 kubectl get deploy mydeployment -o json | jq '.status'。
• 代码不够通用，用户无法验证。例如，你可以嵌入 YAML 文件来创建一个依赖于特定 FlexVolume 实现的 Pod。
• 该代码是一个不完整的示例，因为其目的是突出展现某个大文件中的部分内容。 例如，在描述出于某些原因定制 PodSecurityPolicy 的方法时，你可以在主题文件中直接提供一个短的代码段。
• 由于某些其他原因，该代码不适合用户验证。 例如，当使用 kubectl edit 命令描述如何将新属性添加到资源时， 你可以提供一个仅包含要添加的属性的简短示例。

引用来自其他文件的代码

在主题中引用代码的另一种方法是创建一个新的、完整的示例文件（或文件组）， 然后在主题中引用这些示例。当示例是通用的和可重用的，并且你希望读者自己验证时， 使用此方法引用示例 YAML 文件。

添加新的独立示例文件（如 YAML 文件）时，将代码放在 <LANG>/examples/ 的某个子目录中， 其中 <LANG> 是该主题的语言。在主题文件中使用 codenew 短代码：

{{< codenew file="<RELPATH>/my-example-yaml>" >}}

<RELPATH> 是要引用的文件的路径，相对于 examples 目录。以下 Hugo 短代码引用了位于 /content/en/examples/pods/storage/gce-volume.yaml 的 YAML 文件。

{{< codenew file="pods/storage/gce-volume.yaml" >}}

说明： 要展示上述示例中的原始 Hugo 短代码并避免 Hugo 对其进行解释， 请直接在 < 字符之后和 > 字符之前使用 C 样式注释。请查看此页面的代码。

显示如何从配置文件创建 API 对象

如果需要演示如何基于配置文件创建 API 对象，请将配置文件放在 <LANG>/examples 下的某个子目录中。

在主题中展示以下命令：

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml

说明： 将新的 YAML 文件添加到 <LANG>/examples 目录时，请确保该文件也在 <LANG>/examples_test.go 文件中被引用。 当提交拉取请求时，网站的 Travis CI 会自动运行此测试用例，以确保所有示例都通过测试。

有关使用此技术的主题的示例，请参见 运行单实例有状态的应用。

向主题添加图片

将图片文件放入 /images 目录。首选的图片格式是 SVG。

接下来

• 了解使用页面内容类型.
• 了解创建 PR.

4 - 页面内容类型

Kubernetes 文档包含以下几种页面内容类型：

• 概念（Concept）
• 任务（Task）
• 教程（Tutorial）
• 参考（Reference）

内容章节

每种页面内容类型都有一些使用 Markdown 注释和 HTML 标题定义的章节。 你可以使用 heading 短代码将内容标题添加到你的页面中。 注释和标题有助于维护对应页面内容类型的结构组织。

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

<!-- overview -->

<!-- body -->

要在内容页面中创建通用的标题，可以使用 heading 短代码加上标题字符串。

标题字符串示例：

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

例如，要创建一个 whatsnext 标题，添加 heading 短代码并指定 "whatsnext" 字符串：

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

你可以像下面这样声明一个 prerequisites 标题：

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

短代码 heading 需要一个字符串参数。 该字符串参数要与 i18n/<语言>.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 短代码向页面添加 wahtsnext 节。

在为每个章节撰写内容时，遵从一些规定：

• 使用二级和三级标题（H2、H3）来组织内容
• 在 overview 节中，使用一段文字来为主体部分铺陈上下文；
• 在 body 节中，详细解释对应概念；
• 对于 whatsnext 节，提供一个项目符号列表（最多 5 个），帮助读者进一步学习掌握概念

注解页面是一个已经 上线的概念页面的例子。

任务（Task）

任务页面讲解如何完成某项工作，通常包含由为数不多的几个步骤组成的序列。 任务页面的讲解文字很少，不过通常会包含指向概念主题的链接，以便读者 能够了解相关的背景和知识。

编写新的任务页面时，在 /content/en/docs/tasks 目录下的子目录中创建一个 新的 Markdown 文件。该文件特点如下。

其中的 overview、steps 和 discussion 节在任务页面中显示为注释。 你可以使用 heading 短代码添加 prerequisites 和 whatsnext 小节。

在每个小节内撰写内容时注意以下规定：

• 最低使用二级标题（H2，标题行前带两个 # 字符）。每个小节都会由模版自动给出标题。
• 在 overview 节中，用一个段落为整个任务主体设定语境；
• 在 prerequisites 节中，尽可能使用项目符号列表。 额外的环境准备条件要加在 include 短代码之后。 默认的环境准备条件是拥有一个在运行的 Kubernetes 集群。
• 在 steps 节中，使用编号符号列表。
• 在 discussion 节中，使用正常文字内容来对 steps 节中内容展开叙述。
• 在 whatsnext 节中，使用项目符号列表（不超过 5 项），列举读者可能接下来有兴趣 阅读的主题。

已上线的任务主题示例之一是使用 HTTP 代理来访问 Kubernetes API。

教程（Tutorial）

教程页面描述如果完成一个比单一任务规模更大的目标。通常教程页面会有多个小节， 每个小节由一系列步骤组成。例如，每个教程可能提供对代码示例的讲解，便于用户 了解 Kubernetes 的某个功能特性。教程可以包含表面层面的概念解释，对于更深层面 的概念主题应该使用链接。

撰写新的教程页面时，在 /content/en/docs/tutorials 目录下面的子目录中创建新的 Markdown 文件。该文件有以下特点。

教程页面的 overview、objectives 和 lessoncontent 小节显示为注释形式。 你可以使用 heading 短代码根据需要添加 prerequisites、cleanup 和 whatsnext 小节。

在每个小节中编写内容时，请注意以下规定：

• 最低使用二级标题（H2，标题前面有两个 # 字符）。模版会自动为每个小节设置标题。
• 在 overview 节中，用一个段落为整个主题设定语境；
• 在 prerequisites 节中，尽可能使用项目符号列表。 额外的环境准备条件要加在已包含的条件之后。
• 在 objectives 节中，使用项目符号列表。
• 在 lessoncontent 节中，结合使用编号符号列表和叙述性文字。
• 在 cleanup 节中，使用编号符号列表来描述任务结束后清理集群状态所需要的步骤。
• 在 whatsnext 节中，使用项目符号列表（不超过 5 项），列举读者可能接下来有兴趣 阅读的主题。

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

参考（Reference）

组件工具的参考页面给出的是某个 Kubernetes 组件工具的描述和参数选项输出。 每个页面都是使用组件工具命令基于脚本生成的。

每个工具参考页面可能包含以下小节：

已发布的工具参考页面示例包括：

• kubeadm init
• kube-apiserver
• kubectl

接下来

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

5 - 内容组织

本网站使用了 Hugo。在 Hugo 中，内容组织 是一个核心概念。

说明： Hugo 提示： 用 hugo server --navigateToChanged 命令启动 Hugo 以进行内容编辑会话。

页面列表

页面顺序

文档侧方菜单、文档页面浏览器等以 Hugo 的默认排序顺序列出。Hugo 会按照权重（从 1 开始）、 日期（最新的排最前面）排序，最后按链接标题排序。

有鉴于此，如果你想将一个页面或一个章节前移，请在页面头部设置一个较高的权重：

title: My Page
weight: 10

说明： 对于页面的权重，不建议使用连续的数值，比如1、2、3...，而应采用间隔的数值，比如10、20、30... 这样将来你可以将其他页面插入到想要的位置。

文档主菜单

文档 主菜单是从 docs/ 下面的章节构建的。 这些章节在其章节内容文件 _index.md 的头部设置了 main_menu 标志：

main_menu: true

注意，链接标题来自页面的 linkTitle 字段，因此如果希望它与页面标题不同，请在内容文件中更改它：

main_menu: true
title: Page Title
linkTitle: Title used in links

说明： 以上操作需要为每种语言分别完成。如果在菜单中没有看到你的章节，这可能是因为它没有被 Hugo 识别为一个章节。 请在章节对应的目录下创建 _index.md 内容文件。

文档侧方菜单

文档侧方菜单是基于 docs/ 下面的 当前章节的内容树 构建的。

菜单默认显示所有的章节和它们的页面。

如果你不想列出某个章节或页面，请在页面头部将 toc_hide 标志设置为 true。

toc_hide: true

当导航到具有内容的章节时，网站将显示出指定的章节或页面（例如 _index.md）。 否则，将显示该章节里的第一个页面。

文档浏览器

文档主页上的页面浏览器是基于 docs section 下一层的所有章节和页面构建的。

如果你不想列出某个章节或页面，请在页面头部将 toc_hide 标志设置为 true。

toc_hide: true

主菜单

右上菜单中的网站链接（也出现在页脚中）是通过页面查找构建的。 这是为了确保页面实际存在。因此，如果 case-studies 章节在网站（或者其本地化版本）中不存在， 则不会出现对应的链接。

页面包

除了独立的内容页面（Markdown 文件），Hugo 还支持 页面包。

一个例子是定制的 Hugo 短代码（shortcodes）。 它被认为是 leaf bundle（叶子包）。 目录下的所有内容，包括 index.md，都是包的一部分。此外还包括页面间相对链接、可被处理的图像等：

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

另一个广泛使用的例子是 includes 包。 这类包在页面头部设置 headless: true，意味着它没有得到自己的 URL。它只用于其他页面。

en/includes
├── default-storage-class-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

有关包中文件的一些重要说明：

• 已翻译的包会从上面的语言继承所有缺失的、非内容文件。这一设计可以避免重复。
• 包中的所有文件都是 Hugo 所指的 Resources，你可以为用不同语言为其提供元数据， 例如参数和标题，即使它不支持头部设置（YAML 文件等）。 参见页面资源元数据。
• 从 Resource 的 .RelPermalink 中获得的值是相对于当前页面的。 参见 Permalinks。

样式

网站的样式表的 SASS 源文件存储在 src/sass 下面，可以用 make sass 构建 （Hugo 很快就提供 SASS 的支持，参见 https://github.com/gohugoio/hugo/issues/4243）。

接下来

• 了解定制 Hugo 短代码
• 了解样式指南
• 了解内容指南

6 - 定制 Hugo 短代码

本页面将介绍 Hugo 自定义短代码，可以用于 Kubernetes Markdown 文档书写。

关于短代码的更多信息可参见 Hugo 文档。

功能状态

在本站的 Markdown 页面中，你可以加入短代码来展示所描述的功能特性的版本和状态。

功能状态示例

下面是一个功能状态代码段的演示，表明这个功能已经在最新版 Kubernetes 中稳定了。

{{< feature-state state="stable" >}}

会转换为：

state 的可选值如下：

• alpha
• beta
• deprecated
• stable

功能状态代码

所显示的 Kubernetes 默认为该页或站点版本。 修改 for_k8s_version 短代码参数可以调整要显示的版本。例如

{{< feature-state for_k8s_version="v1.10" state="beta" >}}

会转换为：

词汇

有两种词汇表提示：glossary_tooltip 和 glossary_definition。

你可以通过加入术语词汇的短代码，来自动更新和替换相应链接中的内容 （我们的词汇库） 在浏览在线文档时，术语会显示为超链接的样式，当鼠标移到术语上时，其解释就会显示在提示框中。

除了包含工具提示外，你还可以重用页面内容中词汇表中的定义。

词汇术语的原始数据保存在 https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary，每个内容文件对应相应的术语解释。

词汇演示

例如，下面的代码在 Markdown 中将会转换为 cluster， 然后在提示框中显示。

{{< glossary_tooltip text="cluster" term_id="cluster" >}}

这是一个简短的词汇表定义：

{{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}}

呈现为：

A cluster is 集群由一组被称作节点的机器组成。这些节点上运行 Kubernetes 所管理的容器化应用。集群具有至少一个工作节点。

你也可以包括完整的定义：

{{< glossary_definition term_id="cluster" length="all" >}}

呈现为：

集群由一组被称作节点的机器组成。这些节点上运行 Kubernetes 所管理的容器化应用。集群具有至少一个工作节点。

工作节点托管作为应用负载的组件的 Pod 。控制平面管理集群中的工作节点和 Pod 。 为集群提供故障转移和高可用性，这些控制平面一般跨多主机运行，集群跨多个节点运行。

表格标题

通过添加表格标题，你可以让表格能够被屏幕阅读器读取。 要向表格添加标题（Caption）， 可用 table 短代码包围表格定义，并使用 caption 参数给出表格标题。

说明： 表格标题对屏幕阅读器是可见的，但在标准 HTML 中查看时是不可见的。

下面是一个例子：

{{< table caption="配置参数" >}}
参数      | 描述        | 默认值
:---------|:------------|:-------
`timeout` | 请求的超时时长 | `30s`
`logLevel` | 日志输出的级别 | `INFO`
{{< /table >}}

所渲染的表格如下：

如果你查看表格的 HTML 输出结果，你会看到 <table> 元素 后面紧接着下面的元素：

<caption style="display: none;">配置参数</caption>

标签页

在本站的 Markdown 页面（.md 文件）中，你可以加入一个标签页集来显示 某解决方案的不同形式。

标签页的短代码包含以下参数：

• name： 标签页上显示的名字。
• codelang: 如果要在 tab 短代码中加入内部内容，需要告知 Hugo 使用的是什么代码语言，方便代码高亮。
• include: 标签页中所要包含的文件。如果标签页是在 Hugo 的 叶子包中定义， Hugo 会在包内查找文件（可以是 Hugo 所支持的任何 MIME 类型文件）。 否则，Hugo 会在当前路径的相对路径下查找所要包含的内容页面。 注意，在 include 页面中不能包含短代码内容，必须要使用自结束（self-closing）语法。 非内容文件将会被代码高亮。 如果没有在 codelang 进行声明的话，Hugo 会根据文件名推测所用的语言。

• 如果内部内容是 Markdown，你必须要使用 % 分隔符来包装标签页。 例如，{{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}。
• 可以在标签页集中混合使用上面的各种变形。

下面是标签页短代码的示例。

说明： 内容页面下的 tabs 定义中的标签页 name 必须是唯一的。

标签页演示：代码高亮

{{< tabs name="tab_with_code" >}}
{{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}}
{{< /tabs >}}

会转换为：

• Tab 1
• Tab 2

echo "This is tab 1."

println "This is tab 2."

标签页演示：内联 Markdown 和 HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
这是 **一些 markdown 。**
{{< note >}}它甚至可以包含短代码。{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>纯 HTML</h3>
	<p>这是一些 <i>纯</i> HTML 。</p>
</div>
{{< /tab >}}
{{< /tabs >}}

会转换为：

• Markdown
• HTML

标签页演示：文件嵌套

{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}

会转换为：

• Content File #1
• Content File #2
• JSON File

  {
    "apiVersion": "v1",
    "kind": "PodTemplate",
    "metadata": {
      "name": "nginx"
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "nginx"
        },
        "generateName": "nginx-"
      },
      "spec": {
         "containers": [{
           "name": "nginx",
           "image": "dockerfile/nginx",
           "ports": [{"containerPort": 80}]
         }]
      }
    }
  }

版本号信息

要在文档中生成版本号信息，可以从以下几种短代码中选择。每个短代码可以基于站点配置文件 config.toml 中的版本参数生成一个版本号取值。最常用的参数为 latest 和 version。

{{< param "version" >}}

{{< param "version" >}} 短代码可以基于站点参数 version 生成 Kubernetes 文档的当前版本号取值。短代码 param 允许传入一个站点参数名称，在这里是 version。

说明： 在先前已经发布的文档中，latest 和 version 参数值并不完全等价。新版本文档发布后，参数 latest 会增加，而 version 则保持不变。例如，在上一版本的文档中使用 version 会得到 v1.19，而使用 latest 则会得到 v1.20。

转换为：

{{< latest-version >}}

{{< latest-version >}} 返回站点参数 latest 的取值。每当新版本文档发布时，该参数均会被更新。 因此，参数 latest 与 version 并不总是相同。

转换为：

{{< latest-semver >}}

{{< latest-semver >}} 短代码可以生成站点参数 latest 不含前缀 v 的版本号取值。

转换为：

{{< version-check >}}

{{< version-check >}} 会检查是否设置了页面参数 min-kubernetes-server-version 并将其与 version 进行比较。

转换为：

{{< latest-release-notes >}}

{{< latest-release-notes >}} 短代码基于站点参数 latest 生成不含前缀 v 的版本号取值，并输出该版本更新日志的超链接地址。

转换为：

接下来

• 了解Hugo。
• 了解撰写新的话题。
• 了解使用页面内容类型。
• 了解发起 PR。
• 了解高级贡献。