定制 Hugo 短代码

本页面将介绍定制 Hugo 短代码，可以用于 Kubernetes markdown 文档书写。

关于短代码的更多信息可参见 Hugo 文档。

功能状态

在本站的 markdown 页面中，你可以加入短代码来展示所描述的功能特性的版本和状态。

功能状态示例

下面是一个功能状态代码段的演示，表明这个功能已经在 Kubernetes v1.10 时就已经稳定了。

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

会转换为：

state 的可选值如下：

• alpha
• beta
• deprecated
• stable

功能状态代码

所显示的 Kubernetes 默认为该页或站点版本。 可以通过修改 for_k8s_version 短代码参数来调整要显示的版本。

{{< feature-state for_k8s_version="v1.11" state="stable" >}}

会转换为：

Alpha 功能

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

会转换为：

Beta 功能

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

会转换为：

稳定功能

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

会转换为：

废弃功能

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

会转换为：

词汇

你可以通过加入术语词汇的短代码，来自动更新和替换相应链接中的内容 （我们的词汇库） 这样，在浏览在线文档，鼠标移到术语上时，术语解释就会显示在提示框中。

词汇术语的原始数据保存在 https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary，每个内容文件对应相应的术语解释。

词汇演示

例如，下面的代码在 markdown 中将会转换为 cluster， 然后在提示框中显示。

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

表格标题

通过添加表格标题，你可以让表格能够被屏幕阅读器读取。 要向表格添加标题（Caption）， 可用 table 短代码包围表格定义，并使用 caption 参数给出表格标题。

说明： 表格标题对屏幕阅读器是可见的，但在标准 HTML 中查看时是不可见的。

下面是一个例子：

{{< table caption="配置参数" >}}
参数      | 描述        | 默认值
:---------|:------------|:-------
`timeout` | 请求的超时时长 | `30s`
`logLevel` | 日志输出的级别 | `INFO`
{{< /table >}}

所渲染的表格如下：

如果你查看表格的 HTML 输出结果，你会看到 <table> 元素 后面紧接着下面的元素：

<caption style="display: none;">配置参数</caption>

标签页

在本站的 markdown 页面（.md 文件）中，你可以加入一个标签页集来显示 某解决方案的不同形式。

标签页的短代码包含以下参数：

• name： 标签页上显示的名字。
• codelang: 如果要在 tab 短代码中加入内部内容，需要告知 Hugo 使用的是什么代码语言，方便代码高亮。
• include: 标签页中所要包含的文件。如果标签页是在 Hugo 的 叶子包中定义， Hugo 会在包内查找文件（可以是 Hugo 所支持的任何 MIME 类型文件）。 否则，Hugo 会在当前路径的相对路径下查找所要包含的内容页面。 注意，在 include 页面中不能包含短代码内容，必须要使用自结束（self-closing）语法。 非内容文件将会被代码高亮。 如果没有在 codelang 进行声明的话，Hugo 会根据文件名推测所用的语言。

• 如果内部内容是 Markdown，你必须要使用 % 分隔符来包装标签页。 例如，{{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}。
• 可以在标签页集中混合使用上面的各种变形。

下面是标签页短代码的示例。

说明： 内容页面下的 tabs 定义中的标签页 name 必须是唯一的。

标签页演示：代码高亮

{{< 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 >}}

会转换为：

• Tab 1
• Tab 2

echo "This is tab 1."

println "This is tab 2."

标签页演示：内联 Markdown 和 HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
这是 **一些 markdown 。**
{{< note >}}它甚至可以包含短代码。{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>纯 HTML</h3>
	<p>这是一些 <i>纯</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 >}}

会转换为：

• Content File #1
• Content File #2
• JSON File

  {
    "apiVersion": "v1",
    "kind": "PodTemplate",
    "metadata": {
      "name": "nginx"
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "nginx"
        },
        "generateName": "nginx-"
      },
      "spec": {
         "containers": [{
           "name": "nginx",
           "image": "dockerfile/nginx",
           "ports": [{"containerPort": 80}]
         }]
      }
    }
  }

接下来

• 了解 Hugo。
• 了解撰写新的话题。
• 了解使用页面内容类型。
• 了解发起 PR。
• 了解高级贡献。