自定义 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 中的以下包含将渲染为带工具提示的 集群

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

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

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

其渲染效果如下

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

您也可以包含完整的定义

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

其渲染效果如下

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

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

链接到 API 参考

您可以使用 api-reference 简码链接到 Kubernetes API 参考页面，例如链接到 Pod 参考

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

page 参数的内容是 API 参考页 URL 的后缀。

您可以通过指定 anchor 参数链接到页面中的特定位置，例如链接到 PodSpec 参考或页面中的 环境变量 部分

{{< 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="Environment Variable" >}}

表格标题

通过添加表格标题，可以使表格对屏幕阅读器更加友好。要为表格添加 caption，请将表格用 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 类型）将在 bundle 本身中查找。如果不是，则要包含的内容页面将在当前页面相对查找。请注意，使用 include 时，您没有简码的内部内容，并且必须使用自闭合语法。例如，{{< tab name="Content File #1" include="example1" />}}。语言需要在 codelang 下指定，或者根据文件名确定语言。非内容文件默认会进行代码高亮。
• 如果您的内部内容是 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 >}}

渲染效果

• 标签页 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" 前缀。简码打印一个新 URL 到发布说明 CHANGELOG 页面，其中包含修改后的版本字符串。

渲染效果

下一步

• 了解 Hugo。
• 了解 如何撰写新主题。
• 了解 页面内容类型。
• 了解 如何提交拉取请求。
• 了解 高级贡献。