Information in this document may be out of date

This document has an older update date than the original, so the information it contains may be out of date. If you're able to read English, see the English version for the most up-to-date information: Custom Hugo Shortcodes

定制 Hugo 短代码

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

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

功能状态

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

功能状态示例

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

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

会转换为:

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

state 的可选值如下:

  • alpha
  • beta
  • deprecated
  • stable

功能状态代码

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

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

会转换为:

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

特性门控介绍

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

特性门控 Demo 演示

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

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

渲染到:

DryRun:

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

词汇

有两种词汇表提示:glossary_tooltipglossary_definition

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

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

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

词汇演示

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

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

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

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

呈现为:

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

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

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

呈现为:

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

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

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

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

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

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

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

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

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

表格标题

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

下面是一个例子:

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

所渲染的表格如下:

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

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

<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="tab_with_code" >}}
{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}
{{< /tabs >}}

会转换为:


echo "This is tab 1."


println "This is tab 2."

标签页演示:内联 Markdown 和 HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
这是**一些 markdown。**
{{< note >}}
它甚至可以包含短代码。
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>纯 HTML</h3>
	<p>这是一些 <i>纯</i> HTML。</p>
</div>
{{< /tab >}}
{{< /tabs >}}

会转换为:

这是一些 markdown。

纯 HTML

这是一些 HTML。

标签页演示:文件嵌套

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

会转换为:

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

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

  {
    "apiVersion": "v1",
    "kind": "PodTemplate",
    "metadata": {
      "name": "nginx"
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "nginx"
        },
        "generateName": "nginx-"
      },
      "spec": {
         "containers": [{
           "name": "nginx",
           "image": "dockerfile/nginx",
           "ports": [{"containerPort": 80}]
         }]
      }
    }
  }

源代码文件

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

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

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

输出是:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 4 # 将副本数从 2 更新为 4
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.16.1
        ports:
        - containerPort: 80

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

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

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

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

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

第三方内容标记

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

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

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

列表

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

{{% thirdparty-content %}}

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

项目

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

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

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

版本号信息

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

{{< param "version" >}}

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

转换为:

v1.29

{{< latest-version >}}

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

转换为:

v1.29

{{< latest-semver >}}

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

转换为:

1.29

{{< 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.29.md

接下来

最后修改 January 21, 2024 at 9:36 PM PST: [zh-cn] sync contribute/style/* (c5641f18a1)