文档样式指南

此页面提供了 Kubernetes 文档的写作样式指南。这些是指导原则，而不是规则。请根据您的最佳判断，并随时通过 pull request 提出修改此文档的建议。

有关创建 Kubernetes 文档新内容的更多信息，请阅读文档内容指南。

样式指南的更改由 SIG Docs 作为一个团队进行。要提出更改或添加建议，请将其添加到议程中，以便参加即将举行的 SIG Docs 会议，并在会议上参与讨论。

语言

Kubernetes 文档已被翻译成多种语言（请参阅 本地化 README）。

将文档本地化为不同语言的方法在 本地化 Kubernetes 文档 中有描述。

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

文档格式标准

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

当您专门指与 API 对象交互时，请使用 大驼峰式命名，也称为 Pascal 命名法。您可能会在 API 参考 中看到不同的首字母大小写，例如 "configMap"。在编写通用文档时，最好使用大驼峰式命名法，将其称为 "ConfigMap"。

当您通常讨论 API 对象时，请使用 句子式大小写。

以下示例侧重于大小写。有关格式化 API 对象名称的更多信息，请查看相关的 代码风格 指南。

使用尖括号表示占位符

使用尖括号表示占位符。告诉读者占位符代表什么，例如

显示 Pod 的信息

kubectl describe pod <pod-name> -n <namespace>

如果 Pod 的命名空间是 default，您可以省略 '-n' 参数。

使用粗体表示用户界面元素

使用斜体定义或介绍新术语

使用代码风格表示文件名、目录和路径

使用国际标准表示引号内的标点符号

内联代码格式

使用代码风格表示内联代码、命令

在 HTML 文档中，使用 <code> 标签表示内联代码。在 Markdown 文档中，使用反引号 (`)。但是，StatefulSet 或 ConfigMap 等 API 类型按原样书写（不使用反引号）；这允许使用所有格撇号。

使用代码风格表示对象字段名和命名空间

使用代码风格表示 Kubernetes 命令工具和组件名称

以组件工具或组件名称开头

使用通用描述符代替组件名称

使用常规样式表示字符串和整数字段值

对于字符串或整数类型的字段值，请使用常规样式，不带引号。

但是，请考虑引用值，以防读者将该值与 API 类型混淆。

引用 Kubernetes API 资源

本节讨论了我们在文档中引用 API 资源的方式。

“资源”的澄清

Kubernetes 使用术语 resource (资源) 来指代 API 资源。例如，URL 路径 /apis/apps/v1/namespaces/default/deployments/my-app 代表名为 "my-app" 的 Deployment，位于 "default" namespace (命名空间) 中。在 HTTP 术语中，namespace (命名空间) 也是一种资源——就像所有 Web URL 都标识一种资源一样。

Kubernetes 文档也使用 "resource" (资源) 来讨论 CPU 和内存的请求和限制。通常，最好将 API 资源称为 "API 资源"，这有助于避免与 CPU 和内存资源，或其他类型的资源混淆。

如果使用资源名称的复数小写形式，例如 deployments 或 configmaps，请提供额外的书面上下文来帮助读者理解你的意思。如果你在可以使用 UpperCamelCase (大驼峰命名法) 名称的上下文中，并且存在歧义的风险，请考虑使用 UpperCamelCase (大驼峰命名法) 的 API 类型。

何时使用 Kubernetes API 术语

不同的 Kubernetes API 术语是

• API kinds (API 类型)：在 API URL 中使用的名称（例如 pods、namespaces）。API kinds (API 类型) 有时也称为 resource types (资源类型)。
• API resource (API 资源)：API kind (API 类型) 的单个实例（例如 pod、secret）。
• Object (对象)：作为“意图记录”的资源。Object (对象) 是集群特定部分的期望状态，Kubernetes 控制平面尝试维护该状态。Kubernetes API 中的所有对象也是资源。

为了清晰起见，在 Kubernetes 文档中引用 API 资源时，可以添加 "resource" (资源) 或 "object" (对象)。例如：写 "a Secret object" (一个 Secret 对象) 而不是 "a Secret"。如果仅从大小写就可以清楚地判断，则无需添加额外的单词。

如果更改有助于避免误解，请考虑重新措辞。常见的情况是你想用 API kind (API 类型) 开始一个句子，例如“Secret”；因为英语和其他语言在句子的开头会大写，读者无法判断你指的是 API kind (API 类型) 还是通用概念。重新措辞可以帮助解决这个问题。

API 资源名称

始终使用 UpperCamelCase (大驼峰命名法)，也称为 PascalCase (帕斯卡命名法) 来格式化 API 资源名称。不要使用代码格式化来编写 API 类型。

不要将 API 对象名称拆分为单独的单词。例如，使用 PodTemplateList，而不是 Pod Template List。

有关 PascalCase (帕斯卡命名法) 和代码格式化的更多信息，请查看关于 对 API 对象使用大驼峰命名法 和 对内联代码、命令和 API 对象使用代码样式 的相关指南。

有关 Kubernetes API 术语的更多信息，请查看关于 Kubernetes API 术语 的相关指南。

代码片段格式

不要包含命令提示符

将命令与输出分开

验证 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 示例的版本控制

包含版本信息的代码示例和配置示例应与附带的文本保持一致。

如果信息与特定版本相关，则需要在 Task template (任务模板) 或 Tutorial template (教程模板) 的 prerequisites (先决条件) 部分中定义 Kubernetes 版本。保存页面后，prerequisites (先决条件) 部分将显示为 Before you begin (在开始之前)。

要为任务或教程页面指定 Kubernetes 版本，请在页面的 front matter (正文头部) 中包含 min-kubernetes-server-version。

如果示例 YAML 位于单独的文件中，请查找并查看包含它的主题作为参考。验证使用单独 YAML 的任何主题是否定义了适当的版本信息。如果单独的 YAML 文件未被任何主题引用，请考虑删除它而不是更新它。

例如，如果你正在编写一个与 Kubernetes 1.8 版本相关的教程，你的 markdown 文件的 front matter (正文头部) 应该如下所示

---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---

在代码和配置示例中，不要包含关于替代版本的注释。小心不要在你的示例中包含不正确的语句作为注释，例如

apiVersion: v1 # earlier versions use...
kind: Pod
...

公式和方程

你可以使用 Docsy 对 图表和公式 提供支持。

例如：\\(\frac{7}{9} \sqrt{K^8 s}\\)，渲染为 \(\frac{7}{9} \sqrt{K^8 s}\)。

在合理的情况下，优先使用行内公式，但如果这可能有助于读者，你可以使用 math (数学) 块。

阅读 Docsy 指南，了解你需要更改页面中的哪些内容才能激活支持；如果遇到问题，请将 math: true 添加到页面的 front matter (正文头部) (即使你认为自动激活应该足够)。

Kubernetes.io 词汇表

一个 Kubernetes 特定术语和单词列表，将在整个网站中一致使用。

Shortcodes (短代码)

Hugo Shortcodes (短代码) 有助于创建不同水平的修辞吸引力。我们的文档支持这一类别的三个不同的 shortcodes (短代码)：Note (注意) {{< note >}}、Caution (警告) {{< caution >}} 和 Warning (警示) {{< warning >}}。

1. 用一个开始标签和一个结束标签将文本包围起来。

2. 使用以下语法来应用样式

   {{< note >}}
   No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.)
   {{< /note >}}
   

   输出如下：

   说明

   你选择的前缀与标签的文本相同。

说明

使用 {{< note >}} 来突出显示提示或可能对了解有帮助的信息。

例如

{{< note >}}
You can _still_ use Markdown inside these callouts.
{{< /note >}}

输出如下：

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

1. Use the note shortcode in a list

1. A second item with an embedded note

   {{< note >}}
   Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues).
   {{< /note >}}

1. A third item in a list

1. A fourth item in a list

输出如下：

1. 在列表中使用 note shortcode (注意短代码)

2. 第二个带有嵌入式 note (注意) 的项目

   说明

   Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues).
   

3. 列表中的第三个项目

4. 列表中的第四个项目

注意

使用 {{< caution >}} 来引起对重要信息，以避免陷阱的注意。

例如

{{< caution >}}
The callout style only applies to the line directly above the tag.
{{< /caution >}}

输出如下：

警告

使用 {{< warning >}} 来指示危险或必须遵循的重要信息。

例如

{{< warning >}}
Beware.
{{< /warning >}}

输出如下：

常见的 Shortcode (短代码) 问题

有序列表

除非你在 notice (通知) 和标签之前缩进四个空格，否则 shortcodes (短代码) 会中断编号列表。

例如

1. Preheat oven to 350˚F

1. Prepare the batter, and pour into springform pan.
   {{< note >}}Grease the pan for best results.{{< /note >}}

1. Bake for 20-25 minutes or until set.

输出如下：

1. 将烤箱预热至 350˚F

2. 准备面糊，倒入 springform pan (弹簧扣模具)。

   说明

   为了获得最佳效果，请润滑模具。

3. 烘烤 20-25 分钟或直至凝固。

Include (包含) 语句

include (包含) 语句中的 shortcodes (短代码) 会破坏构建。你必须在调用 include (包含) 之前和之后，在父文档中插入它们。例如

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

Markdown 元素

换行符

使用单个换行符来分隔块级内容，例如标题、列表、图像、代码块等。例外是二级标题，应该使用两个换行符。二级标题紧随一级标题（或标题）之后，没有任何先前的段落或文本。两个换行符有助于更好地可视化代码编辑器中的内容结构。

在适当的时候，手动在 Markdown 源代码中换行段落。由于 git 工具和 GitHub 网站逐行生成文件差异，手动换行长行有助于审阅者轻松找到 PR 中所做的更改并提供反馈。它还帮助下游本地化团队，他们会逐行跟踪上游更改。换行可以在句子的结尾或标点符号处进行，例如。

标题和标题

访问此文档的人员可能会使用屏幕阅读器或其他辅助技术 (AT)。屏幕阅读器 是线性输出设备，它们一次输出页面上的一个项目。如果页面上有大量内容，你可以使用标题为页面提供内部结构。良好的页面结构有助于所有读者轻松浏览页面或过滤感兴趣的主题。

段落

链接

列表

将相关且需要按特定顺序显示或指示多个项目之间相关性的项目分组到列表中。当屏幕阅读器遇到列表（无论是无序列表还是有序列表）时，它会向用户通告这是一组列表项。然后，用户可以使用箭头键在列表中的各个项目之间上下移动。网站导航链接也可以标记为列表项；毕竟它们只是一组相关的链接。

• 如果列表中有一个或多个项目是完整的句子，则用句号结束列表中的每个项目。为了保持一致性，通常要么所有项目都是完整的句子，要么没有项目是完整的句子。

  说明

  作为不完整引言句一部分的有序列表可以使用小写字母并像每个项目都是引言句的一部分一样标点。

• 对于有序列表，使用数字一 (1.)。

• 对于无序列表，使用 (+)、(*) 或 (-)。

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

• 使用四个空格缩进嵌套列表（例如，⋅⋅⋅⋅）。

• 列表项可以包含多个段落。列表项中的每个后续段落必须缩进四个空格或一个制表符。

表格

数据表格的语义目的是呈现表格数据。有视力的用户可以快速扫描表格，但屏幕阅读器会逐行读取。表格标题用于为数据表格创建一个描述性标题。辅助技术 (AT) 使用 HTML 表格标题元素在页面结构中向用户标识表格内容。

• 使用 Hugo shortcodes 为表格添加表格标题。

内容最佳实践

本节包含清晰、简洁和一致内容的建议最佳实践。

使用现在时

例外：如果需要传达正确的含义，请使用将来时或过去时。

使用主动语态

例外：如果主动语态导致笨拙的结构，请使用被动语态。

使用简单直接的语言

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

以“您”称呼读者

避免使用拉丁语短语

优先使用英语术语而不是拉丁语缩写。

例外：对于“等等”，请使用“etc.”。

避免的模式

避免使用“我们”

在句子中使用“我们”可能会令人困惑，因为读者可能不知道您描述的“我们”中是否包含他们。

避免使用术语和习语

有些读者以英语为第二语言。避免使用术语和习语，以帮助他们更好地理解。

避免关于未来的陈述

避免做出承诺或暗示未来。如果您需要讨论一个 alpha 功能，请将文本放在一个标识其为 alpha 信息的标题下。

此规则的例外情况是关于宣布将在未来版本中删除的弃用功能的文档。一个这样的文档示例是 弃用 API 迁移指南。

避免会很快过时的陈述

避免使用“当前”和“新”等词语。今天很新的功能，几个月后可能就不再被认为是新的了。

避免使用假设特定理解水平的词语

避免使用“只是”、“简单”、“容易”、“轻松”或“简单”等词语。这些词语没有价值。

EditorConfig 文件

Kubernetes 项目维护一个 EditorConfig 文件，该文件在 VS Code 等文本编辑器中设置常见的样式首选项。如果您希望确保您的贡献与项目的其余部分保持一致，可以使用此文件。要查看该文件，请参阅仓库根目录中的 .editorconfig。

接下来

• 了解 编写新主题。
• 了解 使用页面模板。
• 了解 自定义 Hugo shortcodes。
• 了解 创建拉取请求。