Custom Hugo Shortcodes
7 minute read
This page explains the custom Hugo shortcodes that can be used in United Manufacturing Hub Markdown documentation.
Read more about shortcodes in the Hugo documentation.
Code example
You can use the codenew
shortcode to display code examples in your documentation.
This is especially useful for code snippets that you want to reuse in multiple places.
After you add a new file with a code snippet in the examples
directory, you can
reference it in your documentation using the codenew
shortcode with the file
parameter set to the path to the file, relative to the examples
directory.
A Copy button is automatically added to the code snippet. When the user clicks the button, the code is copied to the clipboard.
Here’s an example:
{{< codenew file="helm/install-umh.sh" >}}
The rendered shortcode looks like this:
helm install united-manufacturing-hub united-manufacturing-hub -n united-manufacturing-hub
Heading
You can use the heading
shortcode to use localized strings as headings in your
documentation. The available headings are described in the content types
page.
For example, to create a whatsnext heading, add the heading shortcode with the “whatsnext” string:
## {{% heading "whatsnext" %}}
Include
You can use the include
shortcode to include a file in your documentation.
This is especially useful for including markdown files that you want to reuse in
multiple places.
After you add a new file in the includes
directory, you can reference it in your
documentation using the include
shortcode with the first parameter set to the
path to the file, relative to the includes
directory.
Here’s an example:
{{< include "pod-logs.md" >}}
Mermaid
You can use the mermaid
shortcode to display Mermaid diagrams in your documentation.
You can find more information in the diagram guide.
Here’s an example:
{{< mermaid >}}
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
{{< /mermaid >}}
The rendered shortcode looks like this:
Notice
You can use the notice
shortcode to display a notice in your documentation.
There are four types of notices: note
, warning
, info
, and tip
.
Here’s an example:
{{< notice note >}}
This is a note.
{{< /notice >}}
{{< notice warning >}}
This is a warning.
{{< /notice >}}
{{< notice info >}}
This is an info.
{{< /notice >}}
{{< notice tip >}}
This is a tip.
{{< /notice >}}
The rendered shortcode looks like this:
Resource
You can use the resource
shortcode to display a resource in your documentation.
The resource
shortcode takes these parameters:
name
: The name of the resource.type
: The type of the resource.
This is useful for displaying resources which name might change over time, like a pod name.
Here’s an example:
{{< resource type="pod" name="database" >}}
The rendered shortcode looks like this: united-manufacturing-hub-timescaledb-0
The resources are defined in the i18n/en.toml
file. You can add a new resource
by adding a new entry like [resource_<type>_<name>]
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.
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.
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:
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:
This is some markdown.
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.
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}]
}]
}
}
}
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
.
Renders to:
0.9.13{{< 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:
v0.9.13{{< latest-semver >}}
The {{< latest-semver >}}
shortcode generates the value of latest
without the “v” prefix.
Renders to:
0.9.13{{< 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 United Manufacturing Hub version, open UMHLens / OpenLens and go to Helm > Releases. The version is listed in the Version column.{{< 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:
TODO: changelog url0.9.13.mdWhat’s next
- Learn about Hugo.
- Learn about writing a new topic.
- Learn about page content types.
- Learn about opening a pull request.