定制 Hugo 短代码

本页面将介绍 Hugo 自定义短代码,可以用于 Kubernetes Markdown 文档书写。

关于短代码的更多信息可参见 Hugo 文档

功能状态

在本站的 Markdown 页面(.md 文件)中,你可以加入短代码来展示所描述的功能特性的版本和状态。

功能状态示例

下面是一个功能状态代码段的演示,表明这个功能已经在最新版 Kubernetes 中稳定了。

  1. {{< feature-state state="stable" >}}

会转换为:

特性状态: Kubernetes v1.30 [stable]

state 的可选值如下:

  • alpha
  • beta
  • deprecated
  • stable

功能状态代码

所显示的 Kubernetes 默认为该页或站点版本。 修改 for_k8s_version 短代码参数可以调整要显示的版本。例如:

  1. {{< feature-state for_k8s_version="v1.10" state="beta" >}}

会转换为:

特性状态: Kubernetes v1.10 [beta]

从描述文件中检索特征状态

要动态确定特性的状态,请使用 feature_gate_name 短代码参数,此参数将从 content/en/docs/reference/command-line-tools-reference/feature-gates/ 中相应的特性门控描述文件中提取特性的详细状态信息。

例如:

  1. {{< feature-state feature_gate_name="NodeSwap" >}}

会转换为:

特性状态: Kubernetes v1.28 [beta]

特性门控介绍

在此站点上的 Markdown 页面(.md 文件)中,你可以添加短代码来显示短代码的描述。

特性门控 Demo 演示

下面是特性状态片段的 Demo,它显示该特性在最新的 Kubernetes 版本中处于稳定状态。

  1. {{< feature-gate-description name="DryRun" >}}

渲染到:

DryRun:

启用在服务器端对请求进行 试运行(Dry Run), 以便在不提交的情况下测试验证、合并和变更。

词汇

有两种词汇表提示:glossary_tooltipglossary_definition

你可以通过加入术语词汇的短代码,来自动更新和替换相应链接中的内容 (我们的词汇库) 在浏览在线文档时,术语会显示为超链接的样式,当鼠标移到术语上时,其解释就会显示在提示框中。

除了包含工具提示外,你还可以重用页面内容中词汇表中的定义。

词汇术语的原始数据保存在词汇目录, 每个内容文件对应相应的术语解释。

词汇演示

例如下面的代码在 Markdown 中将会转换为 cluster,然后在提示框中显示。

  1. {{< glossary_tooltip text="cluster" term_id="cluster" >}}

这是一个简短的词汇表定义:

  1. {{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}}

呈现为:

A cluster is 一组工作机器,称为节点, 会运行容器化应用程序。每个集群至少有一个工作节点。

你也可以包括完整的定义:

  1. {{< glossary_definition term_id="cluster" length="all" >}}

呈现为:

一组工作机器,称为节点, 会运行容器化应用程序。每个集群至少有一个工作节点。

工作节点会托管 Pod,而 Pod 就是作为应用负载的组件。 控制平面管理集群中的工作节点和 Pod。 在生产环境中,控制平面通常跨多台计算机运行, 一个集群通常运行多个节点,提供容错性和高可用性。

链接至 API 参考

你可以使用 api-reference 短代码链接到 Kubernetes API 参考页面,例如: Pod Pod 参考文件:

  1. {{< api-reference page="workload-resources/pod-v1" >}}

本语句中 page 参数的内容是 API 参考页面的 URL 后缀。

你可以通过指定 anchor 参数链接到页面中的特定位置,例如到 PodSpec 参考,或页面的 environment-variables 部分:

  1. {{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}}
  2. {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}

你可以通过指定 text 参数来更改链接的文本, 例如通过链接到页面的 环境变量部分:

  1. {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="环境变量" >}}

表格标题

通过添加表格标题,你可以让表格能够被屏幕阅读器读取。 要向表格添加标题(Caption), 可用 table 短代码包围表格定义,并使用 caption 参数给出表格标题。

说明: 表格标题对屏幕阅读器是可见的,但在标准 HTML 中查看时是不可见的。

下面是一个例子:

  1. {{< table caption="配置参数" >}}
  2. 参数 | 描述 | 默认值
  3. :---------|:------------|:-------
  4. `timeout` | 请求的超时时长 | `30s`
  5. `logLevel` | 日志输出的级别 | `INFO`
  6. {{< /table >}}

所渲染的表格如下:

配置参数
参数描述默认值
timeout请求的超时时长30s
logLevel日志输出的级别INFO

如果你查看表格的 HTML 输出结果,你会看到 <table> 元素后面紧接着下面的元素:

  1. <caption style="display: none;">配置参数</caption>

标签页

在本站的 Markdown 页面(.md 文件)中,你可以加入一个标签页集来显示 某解决方案的不同形式。

标签页的短代码包含以下参数:

  • name: 标签页上显示的名字。
  • codelang: 如果要在 tab 短代码中加入内部内容,需要告知 Hugo 使用的是什么代码语言,方便代码高亮。
  • include: 标签页中所要包含的文件。如果标签页是在 Hugo 的 叶子包中定义, Hugo 会在包内查找文件(可以是 Hugo 所支持的任何 MIME 类型文件)。 否则,Hugo 会在当前路径的相对路径下查找所要包含的内容页面。 注意,在 include 页面中不能包含短代码内容,必须要使用自结束(self-closing)语法。 例如 {{< tab name="Content File #1" include="example1" />}}。 如果没有在 codelang 进行声明的话,Hugo 会根据文件名推测所用的语言。 默认情况下,非内容文件将会被代码高亮。

  • 如果内部内容是 Markdown,你必须要使用 % 分隔符来包装标签页。 例如,{{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}

  • 可以在标签页集中混合使用上面的各种变形。

下面是标签页短代码的示例。

说明: 内容页面下的 tabs 定义中的标签页 name 必须是唯一的。

标签页演示:代码高亮

  1. {{< tabs name="tab_with_code" >}}
  2. {{< tab name="Tab 1" codelang="bash" >}}
  3. echo "This is tab 1."
  4. {{< /tab >}}
  5. {{< tab name="Tab 2" codelang="go" >}}
  6. println "This is tab 2."
  7. {{< /tab >}}
  8. {{< /tabs >}}

会转换为:

  1. echo "This is tab 1."
  1. println "This is tab 2."

标签页演示:内联 Markdown 和 HTML

  1. {{< tabs name="tab_with_md" >}}
  2. {{% tab name="Markdown" %}}
  3. 这是**一些 markdown。**
  4. {{< note >}}
  5. 它甚至可以包含短代码。
  6. {{< /note >}}
  7. {{% /tab %}}
  8. {{< tab name="HTML" >}}
  9. <div>
  10. <h3> HTML</h3>
  11. <p>这是一些 <i>纯</i> HTML。</p>
  12. </div>
  13. {{< /tab >}}
  14. {{< /tabs >}}

会转换为:

这是一些 markdown。

说明: 它甚至可以包含短代码。

纯 HTML

这是一些 HTML。

标签页演示:文件嵌套

  1. {{< tabs name="tab_with_file_include" >}}
  2. {{< tab name="Content File #1" include="example1" />}}
  3. {{< tab name="Content File #2" include="example2" />}}
  4. {{< tab name="JSON File" include="podtemplate" />}}
  5. {{< /tabs >}}

会转换为:

这是一个内容文件示例,位于一个includes叶子包中。

说明: 被包含的内容文件也可以包含短代码。

这是另一个内容文件示例,位于一个includes叶子包中。

  1. {
  2. "apiVersion": "v1",
  3. "kind": "PodTemplate",
  4. "metadata": {
  5. "name": "nginx"
  6. },
  7. "template": {
  8. "metadata": {
  9. "labels": {
  10. "name": "nginx"
  11. },
  12. "generateName": "nginx-"
  13. },
  14. "spec": {
  15. "containers": [{
  16. "name": "nginx",
  17. "image": "dockerfile/nginx",
  18. "ports": [{"containerPort": 80}]
  19. }]
  20. }
  21. }
  22. }

源代码文件

你可以使用 {{% code_sample %}} 短代码将文件内容嵌入代码块中, 以允许用户下载或复制其内容到他们的剪贴板。 当示例文件的内容是通用的、可复用的,并且希望用户自己尝试使用示例文件时, 可以使用此短代码。

这个短代码有两个命名参数:languagefile, 必选参数 file 用于指定要显示的文件的路径, 可选参数 language 用于指定文件的编程语言。 如果未提供 language 参数,短代码将尝试根据文件扩展名推测编程语言。

  1. {{% code_sample language="yaml" file="application/deployment-scale.yaml" %}}

输出是:

application/deployment-scale.yaml定制 Hugo 短代码 - 图1

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4. name: nginx-deployment
  5. spec:
  6. selector:
  7. matchLabels:
  8. app: nginx
  9. replicas: 4 # 将副本数从 2 更新为 4
  10. template:
  11. metadata:
  12. labels:
  13. app: nginx
  14. spec:
  15. containers:
  16. - name: nginx
  17. image: nginx:1.16.1
  18. ports:
  19. - containerPort: 80

添加新的示例文件(例如 YAML 文件)时,在 <LANG>/examples/ 子目录之一中创建该文件,其中 <LANG> 是页面的语言。 在你的页面的 Markdown 文本中,使用 code 短代码:

  1. {{% code_sample file="<RELATIVE-PATH>/example-yaml>" %}}

其中 <RELATIVE-PATH> 是要包含的示例文件的路径,相对于 examples 目录。 以下短代码引用位于 /content/en/examples/configmap/configmaps.yaml 的 YAML 文件。

  1. {{% code_sample file="configmap/configmaps.yaml" %}}

传统的 {{% codenew %}} 短代码将被替换为 {{% code_sample %}}。 在新文档中使用 {{% code_sample %}}

第三方内容标记

运行 Kubernetes 需要第三方软件。例如:你通常需要将 DNS 服务器 添加到集群中,以便名称解析工作。

当我们链接到第三方软件或以其他方式提及它时,我们会遵循内容指南 并标记这些第三方项目。

使用这些短代码会向使用它们的任何文档页面添加免责声明。

列表

对于有关几个第三方项目的列表,请添加:

  1. {{% thirdparty-content %}}

在包含所有项目的段落标题正下方。

项目

如果你有一个列表,其中大多数项目引用项目内软件(例如:Kubernetes 本身,以及单独的 Descheduler 组件),那么可以使用不同的形式。

在项目之前,或在特定项目的段落下方添加此短代码:

  1. {{% thirdparty-content single="true" %}}

版本号信息

要在文档中生成版本号信息,可以从以下几种短代码中选择。每个短代码可以基于站点配置文件 hugo.toml 中的版本参数生成一个版本号取值。最常用的参数为 latestversion

{{< param "version" >}}

{{< param "version" >}} 短代码可以基于站点参数 version 生成 Kubernetes 文档的当前版本号取值。短代码 param 允许传入一个站点参数名称,在这里是 version

说明: 在先前已经发布的文档中,latestversion 参数值并不完全等价。新版本文档发布后,参数 latest 会增加,而 version 则保持不变。例如,在上一版本的文档中使用 version 会得到 v1.19,而使用 latest 则会得到 v1.20

转换为:

v1.30

{{< latest-version >}}

{{< latest-version >}} 返回站点参数 latest 的取值。每当新版本文档发布时,该参数均会被更新。 因此,参数 latestversion 并不总是相同。

转换为:

v1.30

{{< latest-semver >}}

{{< latest-semver >}} 短代码可以生成站点参数 latest 不含前缀 v 的版本号取值。

转换为:

1.30

{{< version-check >}}

{{< version-check >}} 会检查是否设置了页面参数 min-kubernetes-server-version 并将其与 version 进行比较。

转换为:

要获知版本信息,请输入 kubectl version.

{{< latest-release-notes >}}

{{< latest-release-notes >}} 短代码基于站点参数 latest 生成不含前缀 v 的版本号取值,并输出该版本更新日志的超链接地址。

转换为:

https://git.k8s.io/kubernetes/CHANGELOG/CHANGELOG-1.30.md

接下来