自定义 Hugo 短代码

本页面解释了可在 Kubernetes Markdown 文档中使用的自定义 Hugo 短代码。

在Hugo 文档中阅读有关短代码的更多信息。

特性状态

在本网站的 Markdown 页面（.md 文件）中，您可以添加一个短代码来显示文档化特性的版本和状态。

特性状态演示

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

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

渲染为

state 的有效值为

• alpha
• beta
• 已弃用
• 稳定

特性状态代码

显示的 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="内容文件 #1" include="example1" />}}。需要在 codelang 下指定语言，否则将根据文件名获取语言。默认情况下，非内容文件会进行代码高亮显示。
• 如果您的内部内容是 markdown，则必须使用 % 分隔符将选项卡括起来。例如，{{% tab name="选项卡 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" %}}

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

版本字符串

要生成要包含在文档中的版本字符串，您可以从多个版本短代码中进行选择。每个版本短代码都会显示一个版本字符串，该字符串是从站点配置文件 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。
• 了解 撰写新主题。
• 了解 页面内容类型。
• 了解 发起拉取请求。
• 了解 高级贡献。