编写新主题

本页介绍如何为 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/

将主题标题添加到 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 文件，该文件依赖于特定的 FlexVolume 实现。
• 该代码是一个不完整的示例，因为其目的是突出显示较大文件的一部分。 例如，在描述自定义 RoleBinding 的方法时，你可以直接在主题文件中提供一个简短的代码片段。
• 由于其他原因，该代码不适合用户尝试。 例如，在描述如何使用 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

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

向主题添加图片

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

下一步

• 了解有关使用页面内容类型的信息。
• 了解有关创建拉取请求的信息。