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" >}}
Renders to:
Kubernetes v1.10
stable
- 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:
Kubernetes v1.10
stable
- 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:
Kubernetes v1.18
alpha
- 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:
Kubernetes v1.18
beta
- 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:
Kubernetes v1.18
stable
- 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:
Kubernetes v1.18
deprecated
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:
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 thetab
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 theinclude
, 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 undercodelang
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 atabs
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:
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:
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:
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.