自定义 Hugo Shortcodes

本页介绍 Kubernetes Markdown 文档中可以使用的自定义 Hugo shortcodes。

在 Hugo 文档中阅读有关 shortcodes 的更多信息。

特性状态

在此站点的 Markdown 页面 (.md 文件) 中，可以添加 shortcode 以显示文档化特性的版本和状态。

特性状态演示

下面是特性状态代码段的演示，它将该特性显示为最新 Kubernetes 版本中的稳定版。

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

渲染为

state 的有效值为

• alpha
• beta
• deprecated
• stable

特性状态代码

显示的 Kubernetes 版本默认为页面或站点的版本。你可以通过传递 for_k8s_version shortcode 参数来更改特性状态版本。例如

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

渲染为

从描述文件检索特性状态

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

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

渲染为

特性门控描述

在此站点的 Markdown 页面 (.md 文件) 中，你可以添加 shortcode 以显示 shortcode 的描述。

特性门控描述演示

下面是特性状态代码段的演示，它将该特性显示为最新 Kubernetes 版本中的稳定版。

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

渲染为

DryRun：启用服务器端 dry run 请求，以便可以在不提交的情况下测试验证、合并和突变。

词汇表

有两个词汇表 shortcodes: 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 shortcode 链接到 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 参数来更改链接的文本，例如通过链接到页面的 环境变量 部分

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

表格标题

你可以通过添加表格标题使表格更易于屏幕阅读器访问。要向表格添加标题，请使用 table shortcode 将表格括起来，并使用 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 shortcode 采用以下参数

• name: 标签上显示的名称。
• codelang: 如果你为 tab shortcode 提供内部内容，则可以告诉 Hugo 要使用哪种代码语言进行突出显示。
• include: 要包含在标签页中的文件。如果标签页位于 Hugo 叶子包 中，则在该包本身中查找文件（可以是 Hugo 支持的任何 MIME 类型）。否则，相对于当前页面查找需要包含的内容页面。请注意，使用 include 时，你没有任何 shortcode 内部内容，并且必须使用自闭合语法。例如，{{< tab name="Content File #1" include="example1" />}}。需要在 codelang 下指定语言，否则根据文件名采用语言。默认情况下，非内容文件会进行代码突出显示。
• 如果你的内部内容是 markdown，则必须使用 %-分隔符将标签页括起来。例如，{{% tab name="Tab 1" %}}这是 **markdown**{{% /tab %}}
• 你可以在标签页集中组合上面提到的变体。

下面是 tabs shortcode 的演示。

标签页演示：代码突出显示

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

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

例如

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

{{% 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 >}} 短代码生成不带 "v" 前缀的 latest 值。

渲染为

{{< version-check >}}

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

渲染为

{{< latest-release-notes >}}

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

渲染为

下一步

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