自定义 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：启用服务器端 干运行 请求，以便可以在不提交的情况下测试验证、合并和变异。

词汇表

有两个词汇表短代码：glossary_tooltip 和 glossary_definition。

您可以使用包含项来引用词汇表术语，包含项会自动更新并用我们 词汇表 中的相关链接替换内容。当鼠标悬停在词汇表术语上时，词汇表条目会显示一个工具提示。词汇表术语还会显示为链接。

除了带有工具提示的包含项外，您还可以在页面内容中重复使用词汇表中的定义。

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

词汇表演示

例如，Markdown 中的以下包含项将渲染为 集群，并带有工具提示

{{< 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 参考或页面的 环境变量 部分的链接

{{< 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 短代码将表格括起来，并使用 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 叶捆绑包 中，则该文件（可以是 Hugo 支持的任何 MIME 类型）将在捆绑包本身中查找。如果不是，则需要包含的内容页面将相对于当前页面查找。请注意，使用 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" %}}

项目。

版本字符串

要生成要包含在文档中的版本字符串，您可以从多个版本短代码中进行选择。每个版本短代码都会显示一个版本字符串，该字符串来自在站点配置文件 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 进行比较。

渲染为

{{< latest-release-notes >}}

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

渲染为

下一步

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