Edit This Page

撰写新主题

本页面展示如何为 Kubernetes 文档库创建新主题。

• 准备开始
• 选择页面类型
• 选择标题和文件名
• 在页面头部添加主题标题
• 选择目录
• 将主题放在目录中
• 在主题中嵌入代码
• 引用来自其他文件的代码
• 显示如何从配置文件创建 API 对象
• 向主题添加镜像
• 接下来

准备开始

创建 Kubernetes 文档仓库的一个分支，如开始贡献中所述。

选择页面类型

当你准备写一个新的主题时，考虑一下最适合你的内容的页面类型：

为每个新页面使用模板。每种页面类型都有一个模板可以在编写主题时使用。使用模板有助于确保给定类型主题之间的一致性。

选择标题和文件名

选择一个标题，标题中包含了要通过搜索引擎要查找的关键字。创建一个文件名，使用标题中由连字符分隔的单词。例如，标题为使用 HTTP 代理访问 Kubernetes API 的主题的文件名为 http-proxy-access-api.md。你不需要在文件名中加上 “kubernetes”，因为 “kubernetes” 已经在主题的 URL 中了，例如：

   /docs/tasks/access-kubernetes-api/http-proxy-access-api/

在页面头部添加主题标题

在你的主题中，在页面头部设置一个 title 字段。页面头部是位于页面顶部三条虚线之间的 YAML 块。下面是一个例子：

---
title: 使用 HTTP 代理访问 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 的主题之前。

在主题中嵌入代码

如果你想在主题中包含一些代码，可以直接使用标记代码块语法将代码嵌入到文件中。建议用于以下情况（并非详尽列表）：

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

引用来自其他文件的代码

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

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

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

<RELPATH> 是要引用的文件的路径，相对于 examples 目录。以下 Hugo 短代码引用了位于 /content/en/examples/pods/storage/gce-volume.yaml 的 YAML 文件。

{{< codenew file="pods/storage/gce-volume.yaml" >}}

Note:

要展示上述示例中的原始 Hugo 短代码并避免 Hugo 对其进行解释，请直接在 < 字符之后和 > 字符之前使用 C 样式注释。请查看此页面的代码。

显示如何从配置文件创建 API 对象

如果需要演示如何基于配置文件创建 API 对象，请将配置文件放在 <LANG>/examples 下的某个子目录中。

在主题中展示以下命令：

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml

Note:

将新的 YAML 文件添加到 <LANG>/examples 目录时，请确保该文件也在 <LANG>/examples_test.go 文件中被引用。当提交拉取请求时，网站的 Travis CI 会自动运行此测试用例，以确保所有示例都通过测试。

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

向主题添加镜像

将镜像文件放入 /images 目录。首选的镜像格式是 SVG。

接下来

• 学习使用页面模板。
• 学习展示你的修改。
• 学习创建一个拉取请求。

反馈

此页是否对您有帮助？

Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it on Stack Overflow. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.