定制 Hugo 短代码

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

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

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

会转换为：

特性状态： Kubernetes v1.26 [stable]

state 的可选值如下：

alpha
beta
deprecated
stable

功能状态代码

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

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

会转换为：

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

词汇

有两种词汇表提示：glossary_tooltip 和 glossary_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。在生产环境中，控制平面通常跨多台计算机运行，一个集群通常运行多个节点，提供容错性和高可用性。

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

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

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

你可以通过指定 text 参数来更改链接的文本，例如通过链接到页面的部分：

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

表格标题

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

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

下面是一个例子：

{{< table caption="配置参数" >}}
参数      | 描述        | 默认值
:---------|:------------|:-------
`logLevel` | 日志输出的级别 | `INFO`
{{< /table >}}

所渲染的表格如下：

如果你查看表格的 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 必须是唯一的。

标签页演示：代码高亮

{{< 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 >}}

会转换为：

Tab 2


echo "This is tab 1."

{{< 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

这是 一些 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 >}}

会转换为：

Content File #2

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

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

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

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

第三方内容标记

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

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

列表

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

{{% thirdparty-content %}}

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

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

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

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

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

`{{< param "version" >}}`

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

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

转换为：

v1.26

`{{< latest-version >}}`

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

转换为：

v1.26

`{{< latest-semver >}}`

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

转换为：

1.26

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

转换为：

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

`{{< latest-release-notes >}}`

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

转换为：

接下来

了解 Hugo。
了解。
了解使用页面内容类型。
了解。