撰写新主题

    如中所述，创建 Kubernetes 文档库的派生副本。

    选择页面类型

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

    为每个新页面选择其内容类型。 文档站提供了模板或 来创建新的内容页面。 要创建新类型的页面，请使用要创建的文件的路径，运行 命令。例如：

    选择标题和文件名

    选择一个标题，确保其中包含希望搜索引擎发现的关键字。 确定文件名时请使用标题中的单词，由连字符分隔。 例如，标题为 的主题的文件名为 http-proxy-access-api.md。 你不需要在文件名中加上 “kubernetes”，因为 “kubernetes” 已经在主题的 URL 中了， 例如：

    1.    /docs/tasks/extend-kubernetes/http-proxy-access-api/

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

    选择目录

    根据页面类型，将新文件放入其中一个子目录中：

    • /content/en/docs/tasks/
    • /content/en/docs/tutorials/

    将主题放在目录中

    目录是使用文档源的目录结构动态构建的。 /content/en/docs/ 下的顶层目录用于创建顶层导航条目， 这些目录和它们的子目录在网站目录中都有对应条目。

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

    默认情况下，目录中的其他文件按字母顺序排序。这一般不是最好的顺序。 要控制子目录中主题的相对排序，请将页面头部的键 weight: 设置为整数值。 通常我们使用 10 的倍数，添加后续主题时 weight 值递增。 例如， 为 10 的主题将位于 weight 为 20 的主题之前。

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

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

    引用来自其他文件的代码

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

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

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

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

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

    在主题中展示以下命令：

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

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

    有关使用此技术的主题的示例，请参见 。

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

    接下来