本页面将介绍 Hugo 自定义短代码,可以用于 Kubernetes Markdown 文档书写。
关于短代码的更多信息可参见 Hugo 文档。
功能状态 {#feature-state}
在本站的 Markdown 页面(.md 文件)中,你可以加入短代码来展示所描述的功能特性的版本和状态。
功能状态示例 {#feature-state-demo}
下面是一个功能状态代码段的演示,表明这个功能已经在最新版 Kubernetes 中稳定了。
会转换为:
state 的可选值如下:
- alpha
- beta
- deprecated
- stable
功能状态代码 {#feature-state-code}
所显示的 Kubernetes 默认为该页或站点版本。 修改 <code>for_k8s_version</code> 短代码参数可以调整要显示的版本。例如:
会转换为:
从描述文件中检索特征状态
要动态确定特性的状态,请使用 feature_gate_name 短代码参数,此参数将从
content/en/docs/reference/command-line-tools-reference/feature-gates/
中相应的特性门控描述文件中提取特性的详细状态信息。
例如:
会转换为:
特性门控介绍
在此站点上的 Markdown 页面(.md 文件)中,你可以添加短代码来显示短代码的描述。
特性门控 Demo 演示
下面是特性状态片段的 Demo,它显示该特性在最新的 Kubernetes 版本中处于稳定状态。
会转换为:
词汇 {#glossary}
有两种词汇表提示:glossary_tooltip 和 glossary_definition。
你可以通过加入术语词汇的短代码,来自动更新和替换相应链接中的内容 (我们的词汇库) 在浏览在线文档时,术语会显示为超链接的样式,当鼠标移到术语上时,其解释就会显示在提示框中。
除了包含工具提示外,你还可以重用页面内容中词汇表中的定义。
词汇术语的原始数据保存在词汇目录, 每个内容文件对应相应的术语解释。
词汇演示 {#glossary-demo}
例如下面的代码在 Markdown 中将会转换为 ,然后在提示框中显示。
这是一个简短的词汇表定义:
呈现为:
你也可以包括完整的定义:
呈现为:
链接至 API 参考 {#links-to-api-reference}
你可以使用 api-reference 短代码链接到 Kubernetes API 参考页面,例如:
参考文件:
本语句中 page 参数的内容是 API 参考页面的 URL 后缀。
你可以通过指定 anchor 参数链接到页面中的特定位置,例如到
参考,或页面的
部分:
你可以通过指定 text 参数来更改链接的文本,
例如通过链接到页面的部分:
表格标题 {#table-captions}
通过添加表格标题,你可以让表格能够被屏幕阅读器读取。
要向表格添加标题(Caption),
可用 table 短代码包围表格定义,并使用 caption 参数给出表格标题。
表格标题对屏幕阅读器是可见的,但在标准 HTML 中查看时是不可见的。
下面是一个例子:
参数 | 描述 | 默认值
:---------|:------------|:-------
`timeout` | 请求的超时时长 | `30s`
`logLevel` | 日志输出的级别 | `INFO`
所渲染的表格如下:
| 参数 | 描述 | 默认值 |
|---|---|---|
timeout |
请求的超时时长 | 30s |
logLevel |
日志输出的级别 | INFO |
如果你查看表格的 HTML 输出结果,你会看到 <table>
元素后面紧接着下面的元素:
<caption style="display: none;">配置参数</caption>
标签页 {#tabs}
在本站的 Markdown 页面(.md 文件)中,你可以加入一个标签页集来显示某解决方案的不同形式。
tabs 短代码包含以下参数:
-
name:标签页上显示的名字。 -
codelang:如果要在tab短代码中加入内部内容,需要告知 Hugo 使用的是什么代码语言,方便代码高亮。 -
include:标签页中所要包含的文件。如果标签页是在 Hugo 的 叶子包中定义, Hugo 会在包内查找文件(可以是 Hugo 所支持的任何 MIME 类型文件)。 否则,Hugo 会在当前路径的相对路径下查找所要包含的内容页面。 注意,在include页面中不能包含短代码内容,必须要使用自结束(self-closing)语法。 例如 ``。 如果没有在codelang进行声明的话,Hugo 会根据文件名推测所用的语言。 默认情况下,非内容文件将会被代码高亮。 -
如果内部内容是 Markdown,你必须要使用
%分隔符来包装标签页。 例如,This is **markdown**。 -
可以在标签页集中混合使用上面的各种变形。
下面是标签页短代码的示例。
内容页面下的 tabs 定义中的标签页 name 必须是唯一的。
标签页演示:代码高亮
echo "This is tab 1."
println "This is tab 2."
会转换为:
echo "This is tab A."
// 如果你未设置标签名,则网站提供一个名称。 println "This tab has a default name";
标签页演示:内联 Markdown 和 HTML
这是**一些 markdown。**
它甚至可以包含短代码。
<div>
<h3>纯 HTML</h3>
<p>这是一些 <i>纯</i> HTML。</p>
</div>
会转换为:
这是一些 markdown。
它甚至可以包含短代码。
<div> <h3>
纯 HTML </h3> <p>
这是一些 <i>纯</i> HTML。 </p> </div>
标签页演示:文件嵌套
会转换为:
源代码文件 {#source-code-files}
你可以使用 `` 短代码将文件内容嵌入代码块中, 以允许用户下载或复制其内容到他们的剪贴板。 当示例文件的内容是通用的、可复用的,并且希望用户自己尝试使用示例文件时, 可以使用此短代码。
这个短代码有两个命名参数:language 和 file,
必选参数 file 用于指定要显示的文件的路径,
可选参数 language 用于指定文件的编程语言。
如果未提供 language 参数,短代码将尝试根据文件扩展名推测编程语言。
例如:
输出是:
添加新的示例文件(例如 YAML 文件)时,在 <LANG>/examples/
子目录之一中创建该文件,其中 <LANG> 是页面的语言。
在你的页面的 Markdown 文本中,使用 code 短代码:
其中 <RELATIVE-PATH> 是要包含的示例文件的路径,相对于 examples 目录。
以下短代码引用位于 /content/en/examples/configmap/configmaps.yaml 的 YAML 文件。
传统的 短代码将被替换为。
在新文档中使用 ``。
第三方内容标记 {#third-party-content-marker}
运行 Kubernetes 需要第三方软件。例如:你通常需要将 DNS 服务器添加到集群中, 以便名称解析工作。
当我们链接到第三方软件或以其他方式提及它时, 我们会遵循内容指南并标记这些第三方项目。
使用这些短代码会向使用它们的任何文档页面添加免责声明。
列表 {#third-party-content-list}
对于有关几个第三方项目的列表,请添加:
在包含所有项目的段落标题正下方。
项目 {#third-party-content-item}
如果你有一个列表,其中大多数项目引用项目内软件(例如:Kubernetes 本身,以及单独的 Descheduler 组件),那么可以使用不同的形式。
添加短代码:
在项目之前,或在特定项目的段落下方添加此短代码。
详细信息 {#details}
你可以使用短代码呈现 <details> HTML 元素:
frobnicator 扩展 API 使用示例运行文本实现 **widgets**。
没有哪个人会因为痛苦本身就是令人愉悦的,而选择痛苦,
尽管他们有时因为追求某种快乐而不得不承受痛苦。
但这并不是说他们喜欢痛苦本身,而是因为通过忍受痛苦,他们可以得到更大的快乐。
渲染结果如下:
frobnicator 扩展 API 使用示例运行文本实现 widgets。
没有哪个人会因为痛苦本身就是令人愉悦的,而选择痛苦, 尽管他们有时因为追求某种快乐而不得不承受痛苦。 但这并不是说他们喜欢痛苦本身,而是因为通过忍受痛苦,他们可以得到更大的快乐。
谨慎使用此短代码;通常最好将所有文本直接显示给读者。
版本号信息 {#version-strings}
要在文档中生成版本号信息,可以从以下几种短代码中选择。每个短代码可以基于站点配置文件
hugo.toml 中的版本参数生成一个版本号取值。最常用的参数为 latest 和 version。
``
`` 短代码可以基于站点参数 version 生成 Kubernetes
文档的当前版本号取值。短代码 param 允许传入一个站点参数名称,在这里是 version。
在先前已经发布的文档中,latest 和 version 参数值并不完全等价。新版本文档发布后,参数
latest 会增加,而 version 则保持不变。例如,在上一版本的文档中使用 version 会得到
v1.19,而使用 latest 则会得到 v1.20。
转换为:
``
`` 返回站点参数 latest 的取值。每当新版本文档发布时,该参数均会被更新。
因此,参数 latest 与 version 并不总是相同。
转换为:
``
`` 短代码可以生成站点参数 latest 不含前缀
v 的版本号取值。
转换为:
``
`` 会检查是否设置了页面参数 min-kubernetes-server-version
并将其与 version 进行比较。
转换为:
``
`` 短代码基于站点参数 latest 生成不含前缀 v
的版本号取值,并输出该版本更新日志的超链接地址。
转换为:
来源:Kubernetes 文档贡献者 · 作者与贡献记录 · CC BY 4.0。离线整理了版式、链接和媒体显示。
