定制 Hugo 短代码

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

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

功能状态

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

功能状态示例

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

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

会转换为:

FEATURE STATE: Kubernetes v1.10 [stable]

state 的可选值如下:

  • alpha
  • beta
  • deprecated
  • stable

功能状态代码

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

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

会转换为:

FEATURE STATE: Kubernetes v1.11 [stable]

Alpha 功能

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

会转换为:

FEATURE STATE: Kubernetes v1.20 [alpha]

Beta 功能

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

会转换为:

FEATURE STATE: Kubernetes v1.20 [beta]

稳定功能

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

会转换为:

FEATURE STATE: Kubernetes v1.20 [stable]

废弃功能

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

会转换为:

FEATURE STATE: Kubernetes v1.20 [deprecated]

词汇

有两种词汇表提示。

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

除了包含工具提示外,你还可以重用页面内容中词汇表中的定义。

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

词汇演示

例如,下面的代码在 markdown 中将会转换为 [cluster](https://kubernetes.io/zh/docs/reference/glossary/?all=true#term-cluster "集群由一组被称作节点的机器组成。这些节点上运行 Kubernetes 所管理的容器化应用。集群具有至少一个工作节点。"), 然后在提示框中显示。

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

这是一个简短的词汇表定义:

  1. {{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}}

呈现为:

A cluster is 集群由一组被称作节点的机器组成。这些节点上运行 Kubernetes 所管理的容器化应用。集群具有至少一个工作节点。

你也可以包括完整的定义:

  1. {{< glossary_definition term_id="cluster" length="all" >}}

集群由一组被称作节点的机器组成。这些节点上运行 Kubernetes 所管理的容器化应用。集群具有至少一个工作节点。

工作节点托管作为应用负载的组件的 Pod 。控制平面管理集群中的工作节点和 Pod 。 为集群提供故障转移和高可用性,这些控制平面一般跨多主机运行,集群跨多个节点运行。

-->

呈现为:

集群由一组被称作节点的机器组成。这些节点上运行 Kubernetes 所管理的容器化应用。集群具有至少一个工作节点。

工作节点托管作为应用负载的组件的 Pod 。控制平面管理集群中的工作节点和 Pod 。 为集群提供故障转移和高可用性,这些控制平面一般跨多主机运行,集群跨多个节点运行。

表格标题

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

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

下面是一个例子:

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

  1. 所渲染的表格如下:
  2. 配置参数
  3. 参数
  4. 描述
  5. 默认值
  6. timeout
  7. 请求的超时时长
  8. 30s
  9. logLevel
  10. 日志输出的级别
  11. INFO
  12. <!--
  13. If you inspect the HTML for the table, you should see this element immediately after the opening `<table>` element:
  14. ```html
  15. <caption style="display: none;">Configuration parameters</caption>

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

  1. <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 必须是唯一的。

标签页演示:代码高亮

  1. {{< tabs name="tab_with_code" >}}
  2. {{{< tab name="Tab 1" codelang="bash" >}}
  3. echo "This is tab 1."
  4. {{< /tab >}}
  5. {{< tab name="Tab 2" codelang="go" >}}
  6. println "This is tab 2."
  7. {{< /tab >}}}
  8. {{< /tabs >}}

会转换为:

  1. echo "This is tab 1."
  1. println "This is tab 2."

标签页演示:内联 Markdown 和 HTML

  1. {{< tabs name="tab_with_md" >}}
  2. {{% tab name="Markdown" %}}
  3. 这是 **一些 markdown 。**
  4. {{< note >}}它甚至可以包含短代码。{{< /note >}}
  5. {{% /tab %}}
  6. {{< tab name="HTML" >}}
  7. <div>
  8. <h3> HTML</h3>
  9. <p>这是一些 <i>纯</i> HTML 。</p>
  10. </div>
  11. {{< /tab >}}
  12. {{< /tabs >}}

会转换为:

这是 一些 markdown 。

说明: 它甚至可以包含短代码。

纯 HTML

这是一些 HTML 。

标签页演示:文件嵌套

  1. {{< tabs name="tab_with_file_include" >}}
  2. {{< tab name="Content File #1" include="example1" />}}
  3. {{< tab name="Content File #2" include="example2" />}}
  4. {{< tab name="JSON File" include="podtemplate" />}}
  5. {{< /tabs >}}

会转换为:

这是一个内容文件示例,位于一个includes叶子包中。

说明: 被包含的内容文件也可以包含短代码。

这是另一个内容文件示例,位于一个includes叶子包中。

  1. {
  2. "apiVersion": "v1",
  3. "kind": "PodTemplate",
  4. "metadata": {
  5. "name": "nginx"
  6. },
  7. "template": {
  8. "metadata": {
  9. "labels": {
  10. "name": "nginx"
  11. },
  12. "generateName": "nginx-"
  13. },
  14. "spec": {
  15. "containers": [{
  16. "name": "nginx",
  17. "image": "dockerfile/nginx",
  18. "ports": [{"containerPort": 80}]
  19. }]
  20. }
  21. }
  22. }

接下来