自定义 Hugo Shortcodes

本页面介绍了可用于 Kubernetes Markdown 文档中的自定义 Hugo 短代码。

在 Hugo 文档 中了解更多关于短代码的内容。

功能状态

在本站点的 Markdown 页面（.md 文件）中，您可以添加短代码来显示所记录功能的版本和状态。

功能状态演示

下面是功能状态片段的演示，它将该功能显示为最新 Kubernetes 版本中的稳定状态。

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

渲染结果

state 的有效值为

• alpha
• beta（测试版）
• deprecated（弃用）
• stable（稳定）

功能状态代码

显示的 Kubernetes 版本默认为页面或站点的版本。您可以通过传递 for_k8s_version 短代码参数来更改功能状态版本。例如

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

渲染结果

从描述文件检索功能状态

要动态确定功能状态，请使用 feature_gate_name 短代码参数。功能状态详细信息将从位于 content/en/docs/reference/command-line-tools-reference/feature-gates/ 的对应功能门控描述文件中提取。例如

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

渲染结果

功能门控描述

在本站点的 Markdown 页面（.md 文件）中，您可以添加短代码来显示短代码的描述。

功能门控描述演示

下面是功能状态片段的演示，它将该功能显示为最新 Kubernetes 版本中的稳定状态。

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

渲染结果

DryRun：启用服务端 空运行（Dry Run） 请求，以便在不提交的情况下测试验证、合并和变更。

词汇表

有两个术语表短代码：glossary_tooltip 和 glossary_definition。

您可以通过引用来使用术语表词汇，系统会自动更新内容并将其替换为 术语表 中的相关链接。当鼠标悬停在术语上时，术语条目会显示为工具提示。术语也会显示为链接。

除了带有工具提示的引用外，您还可以在页面内容中复用术语表中的定义。

术语表条目的原始数据存储在 术语表目录 中，每个术语都有一个内容文件。

术语表演示

例如，Markdown 中的以下引用会渲染为带有工具提示的 集群 (cluster)

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

这是一个简短的术语表定义

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

渲染结果为

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

您也可以包含完整定义

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

渲染结果为

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

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

API 参考链接

您可以使用 api-reference 短代码链接到 Kubernetes API 参考页面，例如链接到 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 参数来更改链接文本，例如链接到页面的 环境变量 (Environment Variables) 部分

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

表格标题

您可以通过添加表格标题使表格更易于屏幕阅读器使用。要为表格添加 标题，请使用 table 短代码包裹表格，并通过 caption 参数指定标题。

示例：

{{< table caption="Configuration parameters" >}}
Parameter | Description | Default
:---------|:------------|:-------
`timeout` | The timeout for requests | `30s`
`logLevel` | The log level for log output | `INFO`
{{< /table >}}

渲染后的表格如下所示

如果您检查表格的 HTML，您应该会在 <table> 元素开始后立即看到此元素

<caption style="display: none;">Configuration parameters</caption>

标签页

在本站点的 Markdown 页面（.md 文件）中，您可以添加标签页组来展示给定解决方案的多种形式。

tabs 短代码采用以下参数

• name：标签上显示的名称。
• codelang：如果您向 tab 短代码提供内部内容，您可以告诉 Hugo 使用什么代码语言进行高亮显示。
• include：要在标签中包含的文件。如果标签位于 Hugo 叶子包 (leaf bundle) 中，则该文件（可以是 Hugo 支持的任何 MIME 类型）将在包本身中查找。如果不是，则需要包含的内容页面将相对于当前页面进行查找。请注意，使用 include 时，您没有任何短代码内部内容，必须使用自闭合语法。例如，{{< tab name="Content File #1" include="example1" />}}。语言需要在 codelang 下指定，或者根据文件名获取语言。非内容文件默认进行代码高亮显示。
• 如果您的内部内容是 markdown，则必须使用 % 分隔符来包围标签。例如，{{% tab name="Tab 1" %}}这是 **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 >}}

渲染结果

• 标签 1
• 标签 2

echo "This is tab 1."

println "This is tab 2."

标签页演示：内联 Markdown 和 HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}
It can even contain shortcodes.
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>Plain HTML</h3>
	<p>This is some <i>plain</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}

渲染结果

• Markdown
• 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 >}}

渲染结果

• 内容文件 #1
• 内容文件 #2
• JSON 文件

  {
    "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 %}} 短代码将文件内容嵌入到代码块中，以允许用户下载或将其内容复制到剪贴板。当示例文件的内容是通用的且可重用的，并且您希望用户亲自尝试时，会使用此短代码。

此短代码有两个命名参数：language 和 file。强制参数 file 用于指定要显示文件的路径。可选参数 language 用于指定文件的编程语言。如果未提供 language 参数，短代码将尝试根据文件扩展名猜测语言。

例如

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

输出如下：

application/deployment-scale.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 4 # Update the replicas from 2 to 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 %}}（而不是 {{% codenew %}} 或 {{% code %}}）。

第三方内容标记

运行 Kubernetes 需要第三方软件。例如：您通常需要在集群中添加 DNS 服务器，以便名称解析能够正常工作。

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

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

列表

对于多个第三方项目的列表，请添加

{{% thirdparty-content %}}

就在包含所有项目的章节标题下方。

条目

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

添加短代码

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

在该项目之前，或在该特定项目的标题下方。

详情

您可以使用短代码渲染 <details> HTML 元素

{{< details summary="More about widgets" >}}
The frobnicator extension API implements _widgets_ using example running text.

Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur,
adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et
dolore magnam aliquam quaerat voluptatem.
{{< /details >}}

渲染结果为

版本字符串

要生成包含在文档中的版本字符串，您可以选择多个版本短代码。每个版本短代码都会显示从站点配置文件 hugo.toml 中发现的版本参数值派生的版本字符串。最常用的两个版本参数是 latest 和 version。

{{< param "version" >}}

{{< param "version" >}} 短代码从 version 站点参数生成当前 Kubernetes 文档的版本值。param 短代码接受一个站点参数名称，在本例中为：version。

渲染结果

{{< latest-version >}}

{{< latest-version >}} 短代码返回 latest 站点参数的值。latest 站点参数在发布新版文档时更新。此参数并不总是与文档集中的 version 值匹配。

渲染结果

{{< latest-semver >}}

{{< latest-semver >}} 短代码生成 latest 的值，但不带“v”前缀。

渲染结果

{{< version-check >}}

{{< version-check >}} 短代码检查页面参数 min-kubernetes-server-version 是否存在，然后使用该值与 version 进行比较。

渲染结果

要检查版本，请输入 kubectl version。

{{< latest-release-notes >}}

{{< latest-release-notes >}} 短代码从 latest 生成版本字符串并删除“v”前缀。该短代码会打印带有修改后版本字符串的发行说明 CHANGELOG 页面的新 URL。

渲染结果

接下来

• 了解关于 Hugo 的信息。
• 了解关于 编写新主题 的信息。
• 了解关于 页面内容类型 的信息。
• 了解关于 开启拉取请求 (PR) 的信息。
• 了解关于 高级贡献 的信息。