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 the latest Kubernetes version.

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

Renders to:

FEATURE STATE: Kubernetes v1.21 [stable]

The valid values for state are:

  • alpha
  • beta
  • deprecated
  • stable

Feature state code

The displayed Kubernetes version defaults to that of the page or the site. You can change the feature state version by passing the for_k8s_version shortcode parameter. For example:

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

Renders to:

FEATURE STATE: Kubernetes v1.10 [beta]

Glossary

There are two glossary shortcodes: glossary_tooltip and glossary_definition.

You can reference glossary terms with an inclusion that automatically updates and replaces content with the relevant links from our glossary. When the glossary term is moused-over, the glossary entry displays a tooltip. The glossary term also displays as a link.

As well as inclusions with tooltips, you can reuse the definitions from the glossary in page content.

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 renders to cluster with a tooltip:

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

Here’s a short glossary definition:

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

which renders as:

A cluster is a set of worker machines, called nodes, that run containerized applications. Every cluster has at least one worker node.

You can also include a full definition:

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

which renders as:

A set of worker machines, called nodes, that run containerized applications. Every cluster has at least one worker node.

The worker node(s) host the Pods that are the components of the application workload. The control plane manages the worker nodes and the Pods in the cluster. In production environments, the control plane usually runs across multiple computers and a cluster usually runs multiple nodes, providing fault-tolerance and high availability.

Table captions

You can make tables more accessible to screen readers by adding a table caption. To add a caption to a table, enclose the table with a table shortcode and specify the caption with the caption parameter.

Note: Table captions are visible to screen readers but invisible when viewed in standard HTML.

Here’s an example:

  1. {{< table caption="Configuration parameters" >}}
  2. Parameter | Description | Default
  3. :---------|:------------|:-------
  4. `timeout` | The timeout for requests | `30s`
  5. `logLevel` | The log level for log output | `INFO`
  6. {{< /table >}}

The rendered table looks like this:

Configuration parameters
ParameterDescriptionDefault
timeoutThe timeout for requests30s
logLevelThe log level for log outputINFO

If you inspect the HTML for the table, you should see this element immediately after the opening <table> element:

  1. <caption style="display: none;">Configuration parameters</caption>

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:

  • name: The name as shown on the tab.
  • codelang: If you provide inner content to the tab shortcode, you can tell Hugo what code language to use for highlighting.
  • include: The file to include in the tab. If the tab lives in a Hugo leaf bundle, the file — which can be any MIME type supported by Hugo — is looked up in the bundle itself. If not, the content page that needs to be included is looked up relative to the current page. Note that with the include, you do not have any shortcode inner content and must use the self-closing syntax. For example, {{< tab name="Content File #1" include="example1" />}}. The language needs to be specified under codelang or the language is taken based on the file name. Non-content files are code-highlighted by default.
  • If your inner content is markdown, you must use the %-delimiter to surround the tab. For example, {{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}
  • You can combine the variations mentioned above inside a tab set.

Below is a demo of the tabs shortcode.

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

Tabs demo: Code highlighting

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

Renders to:

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

Tabs demo: Inline Markdown and HTML

  1. {{< tabs name="tab_with_md" >}}
  2. {{% tab name="Markdown" %}}
  3. This is **some markdown.**
  4. {{< note >}}
  5. It can even contain shortcodes.
  6. {{< /note >}}
  7. {{% /tab %}}
  8. {{< tab name="HTML" >}}
  9. <div>
  10.     <h3>Plain HTML</h3>
  11.     <p>This is some <i>plain</i> HTML.</p>
  12. </div>
  13. {{< /tab >}}
  14. {{< /tabs >}}

Renders to:

This is some markdown.

Note: It can even contain shortcodes.

Plain HTML

This is some plain HTML.

Tabs demo: File include

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

Renders to:

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.

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

Version strings

To generate a version string for inclusion in the documentation, you can choose from several version shortcodes. Each version shortcode displays a version string derived from the value of a version parameter found in the site configuration file, config.toml. The two most commonly used version parameters are latest and version.

{{< param "version" >}}

The {{< param "version" >}} shortcode generates the value of the current version of the Kubernetes documentation from the version site parameter. The param shortcode accepts the name of one site parameter, in this case: version.

Note: In previously released documentation, latest and version parameter values are not equivalent. After a new version is released, latest is incremented and the value of version for the documentation set remains unchanged. For example, a previously released version of the documentation displays version as v1.19 and latest as v1.20.

Renders to:

v1.21

{{< latest-version >}}

The {{< latest-version >}} shortcode returns the value of the latest site parameter. The latest site parameter is updated when a new version of the documentation is released. This parameter does not always match the value of version in a documentation set.

Renders to:

v1.21

{{< latest-semver >}}

The {{< latest-semver >}} shortcode generates the value of latest without the “v” prefix.

Renders to:

1.21

{{< version-check >}}

The {{< version-check >}} shortcode checks if the min-kubernetes-server-version page parameter is present and then uses this value to compare to version.

Renders to:

To check the version, enter kubectl version.

{{< latest-release-notes >}}

The {{< latest-release-notes >}} shortcode generates a version string from latest and removes the “v” prefix. The shortcode prints a new URL for the release note CHANGELOG page with the modified version string.

Renders to:

https://git.k8s.io/kubernetes/CHANGELOG/CHANGELOG-1.21.md

What’s next