自定义 Hugo Shortcodes

本页介绍了可在 Kubernetes Markdown 文档中使用的自定义 Hugo Shortcodes。

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

特性状态

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

特性状态示例

下面是特性状态代码片段的示例，它显示该特性在最新的 Kubernetes 版本中处于 stable 状态。

{{< 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 Gate 描述文件提取。例如：

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

渲染结果

Feature Gate 描述

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

Feature Gate 描述示例

下面是特性状态代码片段的示例，它显示该特性在最新的 Kubernetes 版本中处于 stable 状态。

{{< 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 的叶子包 (leaf bundle) 中，则会在该包中查找该文件（可以是 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 目录。以下 Shortcode 引用了位于 /content/en/examples/configmap/configmaps.yaml 的 YAML 文件。

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

遗留的 {{% codenew %}} Shortcode 正在被 {{% code_sample %}} 替换。在新文档中请使用 {{% code_sample %}} (而不是 {{% codenew %}} 或 {{% code %}})。

第三方内容标记

运行 Kubernetes 需要第三方软件。例如：你通常需要为集群添加一个 DNS 服务器，以便名称解析正常工作。

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

使用这些 Shortcodes 会在使用它们的任何文档页面中添加免责声明。

列表

对于多个第三方项的列表，

{{% thirdparty-content %}}

在包含所有项的节的标题正下方添加。

项目

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

添加 Shortcode

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

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

详情

你可以使用 Shortcode 渲染 <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 >}}

渲染结果为

版本字符串

要生成包含在文档中的版本字符串，你可以从多个版本 Shortcodes 中选择。每个版本 Shortcode 显示一个版本字符串，该字符串派生自网站配置文件 hugo.toml 中的版本参数值。两个最常用的版本参数是 latest 和 version。

{{< param "version" >}}

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

渲染结果

{{< latest-version >}}

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

渲染结果

{{< latest-semver >}}

{{< latest-semver >}} Shortcode 生成不带 "v" 前缀的 latest 值。

渲染结果

{{< version-check >}}

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

渲染结果

要检查版本，输入 kubectl version。

{{< latest-release-notes >}}

{{< latest-release-notes >}} Shortcode 从 latest 生成版本字符串并移除 "v" 前缀。该 Shortcode 会打印包含修改后版本字符串的发布说明 CHANGELOG 页面的新 URL。

渲染结果

接下来

• 了解 Hugo。
• 了解撰写新主题。
• 了解页面内容类型。
• 了解开启 Pull Request。
• 了解高级贡献。