Contribute to Kubernetes docs

Edit This Page

Custom Hugo Shortcodes

This page explains the custom Hugo shortcodes that can be used in Kubernetes markdown documentation.

Read more about shortcodes in the Hugo documentation.

Feature state

In a markdown page (.md file) on this site, you can add a shortcode to display version and state of the documented feature.

Feature state demo

Below is a demo of the feature state snippet, which displays the feature as stable in Kubernetes version 1.10.

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

Will render to:

FEATURE STATE: Kubernetes v1.10 stable
This feature is stable, meaning:

  • The version name is vX where X is an integer.
  • Stable versions of features will appear in released software for many subsequent versions.

The valid values for state are:

Feature state code

Below is the template code for each available feature state.

The displayed Kubernetes version defaults to that of the page or the site. This can be changed by passing the for_k8s_version shortcode parameter.

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

Renders to:

FEATURE STATE: Kubernetes v1.10 stable
This feature is stable, meaning:

  • The version name is vX where X is an integer.
  • Stable versions of features will appear in released software for many subsequent versions.

Alpha feature

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

Renders to:

FEATURE STATE: Kubernetes v1.12 alpha
This feature is currently in a alpha state, meaning:

  • The version names contain alpha (e.g. v1alpha1).
  • Might be buggy. Enabling the feature may expose bugs. Disabled by default.
  • Support for feature may be dropped at any time without notice.
  • The API may change in incompatible ways in a later software release without notice.
  • Recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support.

Beta feature

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

Renders to:

FEATURE STATE: Kubernetes v1.12 beta
This feature is currently in a beta state, meaning:

  • The version names contain beta (e.g. v2beta3).
  • Code is well tested. Enabling the feature is considered safe. Enabled by default.
  • Support for the overall feature will not be dropped, though details may change.
  • The schema and/or semantics of objects may change in incompatible ways in a subsequent beta or stable release. When this happens, we will provide instructions for migrating to the next version. This may require deleting, editing, and re-creating API objects. The editing process may require some thought. This may require downtime for applications that rely on the feature.
  • Recommended for only non-business-critical uses because of potential for incompatible changes in subsequent releases. If you have multiple clusters that can be upgraded independently, you may be able to relax this restriction.
  • Please do try our beta features and give feedback on them! After they exit beta, it may not be practical for us to make more changes.

Stable feature

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

Renders to:

FEATURE STATE: Kubernetes v1.12 stable
This feature is stable, meaning:

  • The version name is vX where X is an integer.
  • Stable versions of features will appear in released software for many subsequent versions.

Deprecated feature

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

Renders to:

FEATURE STATE: Kubernetes v1.12 deprecated
This feature is deprecated. For more information on this state, see the Kubernetes Deprecation Policy.

Glossary

You can reference glossary terms with an inclusion that will automatically update and replace content with the relevant links from our glossary. When the term is moused-over by someone using the online documentation, the glossary entry will display a tooltip.

The raw data for glossary terms is stored at https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary, with a content file for each glossary term.

Glossary Demo

For example, the following include within the markdown will render to clusterA set of machines, called nodes, that run containerized applications managed by Kubernetes. with a tooltip:

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

Tabs

In a markdown page (.md file) on this site, you can add a tab set to display multiple flavors of a given solution.

The tabs shortcode takes these parameters:

Below is a demo of the tabs shortcode.

The tab name in a tabs definition must be unique within a content page.

Tabs demo: Code highlighting

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

Will be rendered as:


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

Will be rendered as:

This is some markdown.

Note: It can even contain shortcodes.

Plain HTML

This is some plain HTML.

Tabs demo: File include

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

Will be rendered as:

This is an example content file inside the includes leaf bundle.

Note: Included content files can also contain shortcodes.

This is another example content file inside the includes leaf bundle.

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

What's next