定制 Hugo 短代码
本页面将介绍 Hugo 自定义短代码,可以用于 Kubernetes Markdown 文档书写。
关于短代码的更多信息可参见 Hugo 文档。
功能状态
在本站的 Markdown 页面(.md
文件)中,你可以加入短代码来展示所描述的功能特性的版本和状态。
功能状态示例
下面是一个功能状态代码段的演示,表明这个功能已经在最新版 Kubernetes 中稳定了。
{{< feature-state state="stable" >}}
会转换为:
特性状态: Kubernetes v1.29 [stable]
state
的可选值如下:
- alpha
- beta
- deprecated
- stable
功能状态代码
所显示的 Kubernetes 默认为该页或站点版本。 修改 for_k8s_version
短代码参数可以调整要显示的版本。例如:
{{< feature-state for_k8s_version="v1.10" state="beta" >}}
会转换为:
特性状态: Kubernetes v1.10 [beta]
词汇
有两种词汇表提示:glossary_tooltip
和 glossary_definition
。
你可以通过加入术语词汇的短代码,来自动更新和替换相应链接中的内容 (我们的词汇库) 在浏览在线文档时,术语会显示为超链接的样式,当鼠标移到术语上时,其解释就会显示在提示框中。
除了包含工具提示外,你还可以重用页面内容中词汇表中的定义。
词汇术语的原始数据保存在词汇目录, 每个内容文件对应相应的术语解释。
词汇演示
例如下面的代码在 Markdown 中将会转换为 cluster,然后在提示框中显示。
{{< glossary_tooltip text="cluster" term_id="cluster" >}}
这是一个简短的词汇表定义:
{{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}}
呈现为:
A cluster is 一组工作机器,称为节点, 会运行容器化应用程序。每个集群至少有一个工作节点。
你也可以包括完整的定义:
{{< glossary_definition term_id="cluster" length="all" >}}
呈现为:
一组工作机器,称为节点, 会运行容器化应用程序。每个集群至少有一个工作节点。
工作节点会托管 Pod,而 Pod 就是作为应用负载的组件。 控制平面管理集群中的工作节点和 Pod。 在生产环境中,控制平面通常跨多台计算机运行, 一个集群通常运行多个节点,提供容错性和高可用性。
链接至 API 参考
你可以使用 api-reference
短代码链接到 Kubernetes API 参考页面,例如: Pod 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="环境变量" >}}
表格标题
通过添加表格标题,你可以让表格能够被屏幕阅读器读取。 要向表格添加标题(Caption), 可用 table
短代码包围表格定义,并使用 caption
参数给出表格标题。
说明: 表格标题对屏幕阅读器是可见的,但在标准 HTML 中查看时是不可见的。
下面是一个例子:
{{< table caption="配置参数" >}}
参数 | 描述 | 默认值
:---------|:------------|:-------
`timeout` | 请求的超时时长 | `30s`
`logLevel` | 日志输出的级别 | `INFO`
{{< /table >}}
所渲染的表格如下:
参数 | 描述 | 默认值 |
---|---|---|
timeout | 请求的超时时长 | 30s |
logLevel | 日志输出的级别 | INFO |
如果你查看表格的 HTML 输出结果,你会看到 <table>
元素 后面紧接着下面的元素:
<caption style="display: none;">配置参数</caption>
标签页
在本站的 Markdown 页面(.md
文件)中,你可以加入一个标签页集来显示 某解决方案的不同形式。
标签页的短代码包含以下参数:
name
: 标签页上显示的名字。codelang
: 如果要在tab
短代码中加入内部内容,需要告知 Hugo 使用的是什么代码语言,方便代码高亮。include
: 标签页中所要包含的文件。如果标签页是在 Hugo 的 叶子包中定义, Hugo 会在包内查找文件(可以是 Hugo 所支持的任何 MIME 类型文件)。 否则,Hugo 会在当前路径的相对路径下查找所要包含的内容页面。 注意,在include
页面中不能包含短代码内容,必须要使用自结束(self-closing)语法。 例如{{< tab name="Content File #1" include="example1" />}}
。 如果没有在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 >}}
会转换为:
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
这是一些 纯 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 >}}
会转换为:
这是一个内容文件示例,位于一个includes叶子包中。
说明: 被包含的内容文件也可以包含短代码。
这是另一个内容文件示例,位于一个includes叶子包中。
{
"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 # 将副本数从 2 更新为 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 %}}
。
第三方内容标记
运行 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
则保持不变。例如,在上一版本的文档中使用 version
会得到 v1.19
,而使用 latest
则会得到 v1.20
。
转换为:
v1.29
{{< latest-version >}}
{{< latest-version >}}
返回站点参数 latest
的取值。每当新版本文档发布时,该参数均会被更新。 因此,参数 latest
与 version
并不总是相同。
转换为:
v1.29
{{< latest-semver >}}
{{< latest-semver >}}
短代码可以生成站点参数 latest
不含前缀 v
的版本号取值。
转换为:
1.29
{{< version-check >}}
{{< version-check >}}
会检查是否设置了页面参数 min-kubernetes-server-version
并将其与 version
进行比较。
转换为:
要获知版本信息,请输入 kubectl version
.
{{< latest-release-notes >}}
{{< latest-release-notes >}}
短代码基于站点参数 latest
生成不含前缀 v
的版本号取值,并输出该版本更新日志的超链接地址。
转换为:
https://git.k8s.io/kubernetes/CHANGELOG/CHANGELOG-1.29.md