撰写新主题
本页介绍如何为 Kubernetes 文档创建一个新主题。
开始之前
如开启 PR 中所述，fork Kubernetes 文档仓库。
选择页面类型
在准备撰写新主题时，考虑最适合你内容的页面类型。
| 类型 | 描述 |
|---|---|
| 概念 | 概念页面解释了 Kubernetes 的某个方面。例如，概念页面可能会描述 Kubernetes Deployment 对象，并解释它在部署、扩缩和更新期间作为应用所扮演的角色。通常，概念页面不包含步骤序列，而是提供任务或教程的链接。有关概念主题的示例，请参阅节点。 |
| 任务 | 任务页面展示如何完成单个操作。其目的是为读者提供一系列步骤，供他们在阅读页面时实际操作。任务页面可以短或长，只要它专注于一个领域即可。在任务页面中，可以将简要解释与要执行的步骤结合起来，但如果需要提供冗长的解释，则应在概念主题中进行。相关的任务和概念主题应相互链接。有关简短任务页面的示例，请参阅配置 Pod 使用 Volume 进行存储。有关较长任务页面的示例，请参阅配置存活和就绪探针 |
| 教程 | 教程页面展示如何实现一个目标，该目标将多个 Kubernetes 功能组合在一起。教程可能提供读者在阅读页面时可以实际操作的多个步骤序列。或者它可能提供相关代码片段的解释。例如，教程可以提供代码示例的演练。教程可以包含对正在组合的 Kubernetes 功能的简要解释，但对于单个功能的深入解释，应链接到相关的概念主题。 |
创建新页面
为你撰写的每个新页面使用内容类型。文档站点提供了模板或Hugo Archetypes 来创建新的内容页面。要创建新类型的页面，请使用要创建的文件路径运行 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/
将主题标题添加到 Front Matter 中
在你的主题中，将 title 字段放入Front Matter 中。Front Matter 是页面顶部三重短划线之间的 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: Front Matter 键设置为整数。通常，我们使用 10 的倍数，以便以后可以添加主题。例如，权重为 10 的主题将排在权重为 20 的主题之前。
在你的主题中嵌入代码
如果你想在主题中包含一些代码，可以使用 Markdown 代码块语法直接将代码嵌入文件中。建议在以下情况下使用此方法（非穷举列表）：
- 代码显示了命令的输出，例如
kubectl get deploy mydeployment -o json | jq '.status'。 - 代码不够通用，用户无法直接尝试。例如，你可以嵌入创建 Pod 的 YAML 文件，该文件依赖于特定的 FlexVolume 实现。
- 代码是一个不完整的示例，因为其目的是突出显示更大文件的一部分。例如，在描述如何使用
kubectl edit命令向资源添加新属性时，可以直接在主题文件中提供一个简短的代码片段。 - 代码由于其他原因不适合用户直接尝试。例如，在描述如何使用
kubectl edit命令向资源添加新属性时，可以提供一个只包含要添加属性的简短示例。
包含来自另一个文件的代码
在主题中包含代码的另一种方法是创建新的、完整的示例文件（或一组示例文件），然后从主题中引用该示例。当示例是通用的、可重用的，并且希望读者自己尝试时，可以使用此方法包含示例 YAML 文件。
添加新的独立示例文件（例如 YAML 文件）时，请将代码放在 <LANG>/examples/ 子目录之一中，其中 <LANG> 是主题的语言。在主题文件中，使用 code_sample Shortcode：
{{% code_sample file="<RELPATH>/my-example-yaml>" %}}
其中 <RELPATH> 是要包含的文件相对于 examples 目录的路径。以下 Hugo Shortcode 引用位于 /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。
下一步
- 了解如何使用页面内容类型。
- 了解如何创建拉取请求。