为 Kubernetes 文档做贡献

Edit This Page

定制 Hugo 短代码

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

更多关于短代码参见 Hugo 文档

功能状态

本站上面的 markdown 页面,你可以加入短代码来展示已经文档介绍的功能的版本和状态(state)。

功能状态演示

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

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

会转换为:

FEATURE STATE: Kubernetes v1.10 稳定
该功能是“稳定的”,意味着:

  • 版本名是 vX,其中 X 是整数。
  • 该功能将出现在多个后续释出的软件稳定版中。

state的可选值如下:

  • alpha
  • beta
  • deprecated
  • stable

功能状态代码

下面是为每个现有的功能状态的模板代码。

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

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

会转换为:

FEATURE STATE: Kubernetes v1.10 稳定
该功能是“稳定的”,意味着:

  • 版本名是 vX,其中 X 是整数。
  • 该功能将出现在多个后续释出的软件稳定版中。

Alpha 功能

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

会转换为:

FEATURE STATE: Kubernetes v1.17 alpha
该功能目前处于 alpha 状态,意味着:

  • 版本名称包含 alpha(例如 v1alpha1)。
  • 可能存在问题,启用该功能可能会暴露 bug。默认情况下被禁用。
  • 对该功能的支持可能在任何时候被取消,而不另行通知。
  • API 可能会在以后的软件版本中以不兼容的方式被更改,而不另行通知。
  • 建议仅在短期测试集群中使用该功能,这是因为使用该功能会增加出现 bug 的风险,而且缺乏长期支持。

Beta 功能

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

会转换为:

FEATURE STATE: Kubernetes v1.17 beta
该功能目前处于 beta 状态,意味着:

  • 版本名称包含 beta (例如 v2beta3)。
  • 代码经过了充分测试,启用该功能被认为是安全的。默认情况下被启用。
  • 对整体功能的支持在未来不会被移除,尽管细节上可能会做更改。
  • 在后续的 beta 或稳定版本中,对象的模式、语义可能以不兼容的方式发生变化。当这种情况发生时,我们将提供迁移到下一个版本的说明。这可能需要删除、编辑和重建 API 对象,编辑过程可能需要一些思考。这可能导致依赖该功能的应用程序停机一段时间。
  • 建议仅在非业务关键场景使用该功能,因为在后续版本中可能会发生不兼容的更改。如果您有多个可以独立升级的集群,那么您可能可以放松这个限制。
  • 请尝试使用我们的 beta 版功能,并给出反馈!在它们退出 beta 测试阶段之后,我们将很难去做更多的更改。

稳定功能

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

会转换为:

FEATURE STATE: Kubernetes v1.17 稳定
该功能是“稳定的”,意味着:

  • 版本名是 vX,其中 X 是整数。
  • 该功能将出现在多个后续释出的软件稳定版中。

废弃功能

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

会转换为:

FEATURE STATE: Kubernetes v1.17 废弃
该功能已被*弃用*。有关此状态的更多信息,请参见Kubernetes 弃用策略

词汇

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

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

词汇演示

例如,下面的代码在 markdown 中将会转换为 <a class='glossary-tooltip' href='/zh/docs/reference/glossary/?all=true#term-cluster' target='_blank'>cluster<span class='tooltip-text'>集群由一组被称作节点的机器组成。这些节点上运行 Kubernetes 所管理的容器化应用。集群具有至少一个工作节点和至少一个主节点。</span> </a>,然后在提示框中显示。

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

标签页

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

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

  • name: 标签页上的名字。
  • codelang: 如果要在tab短代码中加入内部内容,需要告知 Hugo 使用的是什么代码语言,方便代码高亮。
  • include: 标签页中所要包含的文件。如果标签页是在 Hugo 的页面包(leaf bundle)中,文件(可以是 Hugo 所支持的 MIME 类型文件)将会在包中查找。如果不是,所要包含的内容页面将会在当前路径的相关路径下查找。注意,在include属性部分,不能加入短代码内部内容,必须要使用自结束(self-closing)的语法。 非内容文件将会被代码高亮。如果没有在codelang进行声明的话,所用的代码语言将会来自文件名。
  • 如果内部内容是 markdown, 你必须要使用 % 分隔符来包装标签页,例如,{{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}
  • 可以在标签页集中混合使用上面的各种变形。

下面是演示标签页短代码。

注意: The tab name in a tabs definition must be unique within a content page. 一个内容页面下的,标签页定义中的标签页 必须是唯一的。

标签页演示:代码高亮

{{< 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."

Tabs demo: Inline Markdown and HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}**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 >}}

会转换为:

This is some markdown.

注意: Note: It can even contain shortcodes.

Plain HTML

This is some plain 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}]
         }]
      }
    }
  }

接下来

反馈