撰写新主题

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

开始之前

开启 PR 中所述,fork Kubernetes 文档仓库。

选择页面类型

在准备撰写新主题时,考虑最适合你内容的页面类型。

选择页面类型的指南
类型描述
概念概念页面解释了 Kubernetes 的某个方面。例如,概念页面可能会描述 Kubernetes Deployment 对象,并解释它在部署、扩缩和更新期间作为应用所扮演的角色。通常,概念页面不包含步骤序列,而是提供任务或教程的链接。有关概念主题的示例,请参阅节点
任务任务页面展示如何完成单个操作。其目的是为读者提供一系列步骤,供他们在阅读页面时实际操作。任务页面可以短或长,只要它专注于一个领域即可。在任务页面中,可以将简要解释与要执行的步骤结合起来,但如果需要提供冗长的解释,则应在概念主题中进行。相关的任务和概念主题应相互链接。有关简短任务页面的示例,请参阅配置 Pod 使用 Volume 进行存储。有关较长任务页面的示例,请参阅配置存活和就绪探针
教程教程页面展示如何实现一个目标,该目标将多个 Kubernetes 功能组合在一起。教程可能提供读者在阅读页面时可以实际操作的多个步骤序列。或者它可能提供相关代码片段的解释。例如,教程可以提供代码示例的演练。教程可以包含对正在组合的 Kubernetes 功能的简要解释,但对于单个功能的深入解释,应链接到相关的概念主题。

创建新页面

为你撰写的每个新页面使用内容类型。文档站点提供了模板或Hugo Archetypes 来创建新的内容页面。要创建新类型的页面,请使用要创建的文件路径运行 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 中

在你的主题中,将 title 字段放入Front Matter 中。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 实现。
  • 代码是一个不完整的示例,因为其目的是突出显示更大文件的一部分。例如,在描述如何使用 kubectl edit 命令向资源添加新属性时,可以直接在主题文件中提供一个简短的代码片段。
  • 代码由于其他原因不适合用户直接尝试。例如,在描述如何使用 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。

下一步

最后修改于太平洋标准时间 2023 年 12 月 29 日晚上 9:47:修复过期链接/锚点 (bcc55ae7c9)