Guide to Custom Shortcodes
Relevant source files
The following files were used as context for generating this wiki page:
The Docker documentation website is built with the Hugo static site generator, which utilizes custom "shortcodes" to render rich, reusable UI components. These shortcodes allow contributors to easily create complex elements like cards, tabs, badges, and summary bars without writing raw HTML, ensuring a consistent look and feel across the documentation. This guide provides an overview of the available shortcodes and instructions on how to implement them in Markdown content.
Sources: agent.yml:28-33, CONTRIBUTING.md:16-18
card and grid Shortcodes
The card and grid shortcodes are used to display content in a visually distinct card format. A single card can be used for emphasis, while the grid shortcode arranges multiple cards in a responsive grid layout.
Sources: content/contribute/components/cards.md:1-2
card Shortcode
The card shortcode creates a single card element. It is configured using several parameters passed directly into the shortcode.
Sources: content/contribute/components/cards.md:1-2
Parameters
| Parameter | Description |
|---|---|
title | The title of the card. |
icon | The Material Symbols icon slug to display on the card. |
image | A custom image to use instead of an icon (mutually exclusive with icon). |
link | An optional URL to make the entire card a clickable link. |
description | A description text, written in Markdown, that appears in the card body. |
A known limitation is that the description field cannot contain relative Markdown links (../other-file.md). Absolute URL paths (/section/page/) must be used instead.
Sources: content/contribute/components/cards.md:6-14, content/contribute/components/cards.md:16-24
Usage Example
{{</* card
title="Get your Docker on"
icon=favorite
link=https://docs.docker.com/
description="Build, share, and run your apps with Docker"
*/>}}
Sources: content/contribute/components/cards.md:31-36
grid Shortcode
The grid shortcode renders a responsive 3x3 grid of cards. Unlike the card shortcode, the grid shortcode itself takes no arguments. Instead, it sources its content from the page's front matter under the grid key.
Sources: content/contribute/components/cards.md:38-42, content/contribute/components/cards.md:49-51
Data Flow
The following diagram illustrates how the grid shortcode processes data from the front matter to render a grid of cards.
Usage Example
First, define the card data in the page's front matter:
# front matter section of a page
title: some page
grid:
- title: "Docker Engine"
description: Vrrrrooooommm
icon: "developer_board"
link: "/engine/"
- title: "Docker Build"
description: Clang bang
icon: "build"
link: "/build/"
Then, place the grid shortcode in the body of the Markdown file where the grid should appear:
{{</* grid */>}}
Sources: content/contribute/components/cards.md:44-47, content/contribute/components/cards.md:52-58
tabs Shortcode
The tabs component consists of a parent {{< tabs >}} shortcode that wraps one or more {{< tab >}} shortcodes. This is used to create tabbed content panes, which are useful for showing information for different operating systems or programming languages.
Sources: content/contribute/components/tabs.md:5-8
The diagram below shows the nested structure of the tabs component.
Parameters
{{< tabs >}}:group(optional): A string to identify a group of tab sections. All tab sections with the samegroupID will have their selected tab synchronized.
{{< tab >}}:name: The text to display on the tab label.
Sources: content/contribute/components/tabs.md:9-10, content/contribute/components/tabs.md:29-31
Usage Example
{{</* tabs */>}}
{{</* tab name="JavaScript" */>}}
```js
console.log("hello world")
{{</* /tab />}}
{{</ tab name="Go" */>}}
fmt.Println("hello world")
{{</* /tab />}}
{{</ /tabs */>}}
Sources: [content/contribute/components/tabs.md:20-33](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/components/tabs.md#L20-L33)
## `badge` Shortcode
Badges are small, colored labels used to indicate the status of content, such as "new", "beta", or "deprecated". They can be used inline within content or in the sidebar navigation.
Sources: [content/contribute/components/badges.md:19-20](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/components/badges.md#L19-L20)
### Inline Badges
Inline badges are created with the `badge` shortcode.
#### Parameters
| Parameter | Description |
| :--- | :--- |
| `color` | The color of the badge. Possible values: `blue`, `amber`, `red`, `green`, `violet`, `gray`. |
| `text` | The text to display inside the badge. |
Sources: [content/contribute/components/badges.md:30-32](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/components/badges.md#L30-L32)
#### Usage Guidelines
| Color | Recommended Use |
| :--- | :--- |
| `violet` | New early access or experimental content. |
| `blue` | Beta content. |
| `green` | New GA content or non-product content (e.g., guides). |
| `gray` | Deprecated content. |
Badges for new features should typically be removed after two months.
Sources: [content/contribute/components/badges.md:22-27](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/components/badges.md#L22-L27)
#### Usage Example
```go
{{</* badge color=blue text="blue badge" */>}}
[{{</* badge color="blue" text="badge with a link" */>}}](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/../_index.md)
Sources: content/contribute/components/badges.md:15-16, content/contribute/components/badges.md:30-32
Sidebar Badges
Badges can also be added to a page's entry in the sidebar navigation by defining it in the page's front matter.
Front Matter Configuration
---
title: Page title
params:
sidebar:
badge:
color: gray
text: Deprecated
---
Sources: content/contribute/components/badges.md:34-41
summary-bar Shortcode
The summary-bar shortcode is used to display a feature's requirements, such as the required subscription tier, product version, or if it is intended for administrators.
Sources: content/contribute/components/call-outs.md:6-7
Implementation Flow
Implementing a summary bar is a two-step process:
- Define the feature and its attributes in the
/data/summary.yamlfile. - Call the
summary-barshortcode in the Markdown file, referencing the feature by name.
The following diagram shows this process.
summary.yaml Attributes
The following attributes can be defined for each feature in /data/summary.yaml.
| Attribute | Description | Possible values |
|---|---|---|
subscription | The subscription required to use the feature. | All, Personal, Pro, Team, Business |
availability | The product development stage of the feature. | Experimental, Beta, Early Access, GA, Retired |
requires | The minimum version required for the feature. | A string describing the version. |
for | Notes if the feature is intended for IT Administrators. | Administrators |
Sources: content/contribute/components/call-outs.md:12-19
Usage Example
In /data/summary.yaml:
# (Example structure)
PKG installer:
subscription: "Business"
requires: "Docker Desktop 4.20"
In your markdown file:
{{</* summary-bar feature_name="PKG installer" */>}}
Sources: content/contribute/components/call-outs.md:23, content/contribute/components/call-outs.md:43-45
Conclusion
The custom Hugo shortcodes in the Docker documentation repository are essential tools for creating rich, structured, and consistent content. By using components like cards, tabs, badges, and summary bars, contributors can enhance the readability and user experience of the documentation. Adhering to the guidelines for these shortcodes ensures that all content maintains a high standard of quality and uniformity.
Sources: agent.yml:28-33, CONTRIBUTING.md:1-4