编写新主题

本页面介绍如何为 Kubernetes 文档创建新主题。

准备工作

按照“提交 PR”中的说明，为 Kubernetes 文档创建一个仓库的 fork。

选择页面类型

在准备编写新主题时，请考虑哪种页面类型最适合您的内容。

创建新页面

为每个新页面使用内容类型。文档网站提供模板或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/

在 front matter 中添加主题标题

在您的主题中，在front matter中放置一个title字段。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 文件，该 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

有关使用此技术的某个主题的示例，请参阅“运行单个实例的无状态应用程序”。

向主题添加图像

将图像文件放在/images目录中。首选的图像格式是 SVG。

下一步

• 了解如何使用页面内容类型。
• 了解如何创建拉取请求。