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
Glossary
Table captions
Tabs
What's next

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

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.

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. 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 state="alpha" >}}

Renders to:

FEATURE STATE: Kubernetes v1.17 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 state="beta" >}}

Renders to:

FEATURE STATE: Kubernetes v1.17 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 state="stable" >}}

Renders to:

FEATURE STATE: Kubernetes v1.17 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 state="deprecated" >}}

Renders to:

FEATURE STATE: Kubernetes v1.17 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 automatically updates and replaces content with the relevant links from our glossary. When the term is moused-over by someone using the online documentation, the glossary entry displays 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 renders to clusterA set of worker machines, called nodes, that run containerized applications. Every cluster has at least one worker node. with a tooltip:

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

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:

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

The rendered table looks like this:

Configuration parameters
Parameter	Description	Default
`timeout`	The timeout for requests	`30s`
`logLevel`	The log level for log output	`INFO`

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

<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

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

Renders to:

Tab 1
Tab 2


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

Renders to:

Markdown
HTML

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

Renders to:

Content File #1
Content File #2
JSON File

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

Learn about Hugo.
Learn about writing a new topic.
Learn about using page templates.
Learn about staging your changes
Learn about creating a pull request.

Feedback

Was this page helpful?

Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it on Stack Overflow. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.

Contribute to Kubernetes docs

Kubernetes v1.17 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.

Custom Hugo Shortcodes

Feature state

Feature state demo

Feature state code

Alpha feature

Beta feature

Stable feature

Deprecated feature

Glossary

Glossary Demo

Table captions

Tabs

Tabs demo: Code highlighting

Tabs demo: Inline Markdown and HTML

Plain HTML

Tabs demo: File include

What's next

Feedback