编写新主题
此页面介绍如何为 Kubernetes 文档创建新主题。
开始之前
按照 打开一个 PR 中的说明，创建 Kubernetes 文档仓库的分支。
选择页面类型
在准备编写新主题时，请考虑最适合您内容的页面类型。
| 类型 | 描述 |
|---|---|
| 概念 | 概念页面解释了 Kubernetes 的某些方面。例如，概念页面可能会描述 Kubernetes Deployment 对象，并解释它在部署、缩放和更新应用程序时的作用。通常，概念页面不包含步骤序列，而是提供指向任务或教程的链接。有关概念主题的示例，请参见 节点。 |
| 任务 | 任务页面展示如何执行一项操作。目标是为读者提供一个步骤序列，他们可以在阅读页面时实际执行。任务页面可以很短，也可以很长，只要它专注于一个领域即可。在任务页面中，可以在要执行的步骤中混合简要说明，但如果需要提供冗长的说明，则应在概念主题中进行。相关任务和概念主题应相互链接。有关简短任务页面的示例，请参见 配置 Pod 以使用卷进行存储。有关较长任务页面的示例，请参见 配置存活探测和就绪探测 |
| 教程 | 教程页面展示如何完成将多个 Kubernetes 功能结合在一起的目标。教程可能会提供多个步骤序列，读者可以在阅读页面时实际执行。或者它可能会提供对相关代码片段的解释。例如，教程可以提供代码示例的演练。教程可以包含对正在结合在一起的 Kubernetes 功能的简要解释，但应链接到相关概念主题以详细解释各个功能。 |
创建新页面
为每个新编写的页面使用 内容类型。文档网站提供模板或 Hugo 原型 来创建新的内容页面。要创建新的页面类型，请使用要创建文件的路径运行 hugo new。例如
hugo new docs/concepts/my-first-concept.md
选择标题和文件名
选择包含您希望搜索引擎找到的关键词的标题。创建一个文件名，使用标题中的单词并用连字符隔开。例如，标题为 使用 HTTP 代理访问 Kubernetes API 的主题的文件名为 http-proxy-access-api.md。您无需在文件名中添加“kubernetes”，因为“kubernetes”已经位于主题的 URL 中，例如
/docs/tasks/extend-kubernetes/http-proxy-access-api/
将主题标题添加到前置内容
在主题中，将 title 字段放在 前置内容 中。前置内容是页面顶部三条破折号之间 YAML 块。下面是一个示例
---
title: Using an HTTP Proxy to Access the Kubernetes API
---
选择目录
根据页面类型，将您的新文件放在以下目录之一的子目录中
- /content/en/docs/tasks/
- /content/en/docs/tutorials/
- /content/en/docs/concepts/
您可以将文件放在现有子目录中，也可以创建新的子目录。
将您的主题放在目录中
目录使用文档源的目录结构动态构建。/content/en/docs/ 下的顶级目录创建顶级导航，每个子目录在目录中都有条目。
每个子目录都有一个文件 _index.md，它代表给定子目录内容的“首页”。_index.md 不需要模板。它可以包含有关子目录中主题的概述内容。
默认情况下，目录中的其他文件按字母顺序排序。这几乎从来不是最佳顺序。要控制子目录中主题的相对排序，请将 weight: 前置内容键设置为整数。通常，我们使用 10 的倍数来考虑以后添加主题。例如，权重为 10 的主题将排在权重为 20 的主题之前。
在主题中嵌入代码
如果您想在主题中包含一些代码，可以使用 markdown 代码块语法将代码直接嵌入到文件中。建议在以下情况下使用此方法（并非详尽无遗）：
- 代码显示命令（例如
kubectl get deploy mydeployment -o json | jq '.status'）的输出。 - 代码不够通用，用户无法尝试。例如，您可以嵌入创建 Pod 的 YAML 文件，该 Pod 依赖于特定的 FlexVolume 实现。
- 代码是一个不完整的示例，因为它的目的是突出显示较大文件的一部分。例如，在描述定制 RoleBinding 的方法时，您可以在主题文件中直接提供简短代码段。
- 代码由于其他原因不适合用户尝试。例如，在描述如何使用
kubectl edit命令向资源添加新属性时，您可以提供一个简短的示例，该示例仅包含要添加的属性。
从另一个文件包含代码
将代码包含在主题中的另一种方法是创建新的完整示例文件（或一组示例文件），然后从主题中引用该示例。当示例是通用的、可重用的，并且您希望读者自己尝试时，使用此方法包含示例 YAML 文件。
添加新的独立示例文件（例如 YAML 文件）时，将代码放在 <LANG>/examples/ 子目录中的一个目录中，其中 <LANG> 是主题的语言。在主题文件中，使用 code_sample 短代码
{{% code_sample file="<RELPATH>/my-example-yaml>" %}}
其中 <RELPATH> 是要包含的文件相对于 examples 目录的路径。以下 Hugo 短代码引用位于 /content/en/examples/pods/storage/gce-volume.yaml 的 YAML 文件。
{{% code_sample file="pods/storage/gce-volume.yaml" %}}
展示如何从配置文件创建 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 在提交 PR 时会自动运行此测试用例，以确保所有示例都通过测试。有关使用此技术的主题示例，请参见 运行单实例有状态应用程序。
向主题添加图片
将图片文件放在 /images 目录中。首选的图片格式是 SVG。
下一步
- 了解 如何使用页面内容类型。
- 了解 如何创建拉取请求。