编写新主题

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

开始之前

如发起 PR中所述，创建 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/zh-cn/docs/tasks/
• /content/zh-cn/docs/tutorials/
• /content/zh-cn/docs/concepts/

您可以将文件放在现有子目录中，也可以创建新的子目录。

将主题放置在目录中

目录是使用文档源的目录结构动态构建的。/content/zh-cn/docs/ 下的顶级目录创建顶级导航，每个子目录在目录中都有条目。

每个子目录都有一个文件 _index.md，它表示给定子目录内容的“主页”。_index.md 不需要模板。它可以包含有关子目录中主题的概述内容。

默认情况下，目录中的其他文件按字母顺序排序。这几乎从来都不是最佳顺序。要控制子目录中主题的相对排序，请将 weight: 前言键设置为整数。通常，我们使用 10 的倍数，以便在以后添加主题。例如，权重为 10 的主题将排在权重为 20 的主题之前。

在主题中嵌入代码

如果要在主题中包含一些代码，可以使用 Markdown 代码块语法直接在文件中嵌入代码。建议在以下情况下使用此方法（并非详尽无遗）

• 代码显示来自命令的输出，例如 kubectl get deploy mydeployment -o json | jq '.status'。
• 代码不够通用，用户无法试用。例如，您可以嵌入用于创建依赖于特定FlexVolume实现的 Pod 的 YAML 文件。
• 代码是一个不完整的示例，因为它的目的是突出显示较大文件的一部分。例如，在描述自定义RoleBinding的方法时，您可以在主题文件中直接提供一个简短的代码片段。
• 由于其他原因，该代码并非供用户试用。例如，在描述如何使用 kubectl edit 命令将新属性添加到资源时，您可以提供一个仅包含要添加的属性的简短示例。

包含来自另一个文件的代码

在主题中包含代码的另一种方法是创建一个新的、完整的示例文件（或一组示例文件），然后从主题中引用该示例。当示例是通用的和可重用的，并且您希望读者自己试用时，请使用此方法来包含示例 YAML 文件。

添加新的独立示例文件（例如 YAML 文件）时，请将代码放在 <LANG>/examples/ 子目录之一中，其中 <LANG> 是主题的语言。在主题文件中，使用 code_sample 短代码

{{% code_sample file="<RELPATH>/my-example-yaml>" %}}

其中 <RELPATH> 是要包含的文件的路径，相对于 examples 目录。以下 Hugo 短代码引用了位于 /content/zh-cn/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。

下一步

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