Creating Custom Shortcodes

Relevant source files

The following files were used as context for generating this wiki page: - [agent.yml](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/agent.yml) - [content/contribute/components/call-outs.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/components/call-outs.md) - [content/contribute/components/badges.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/components/badges.md) - [CONTRIBUTING.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/CONTRIBUTING.md) - [content/contribute/guides.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/guides.md) - [content/contribute/style/formatting.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/style/formatting.md)

The Docker documentation website is built using the Hugo static site generator. A key feature of this architecture is the use of Hugo shortcodes to embed rich, reusable components directly into Markdown content. These components include elements like tabs, accordions, callouts, and badges, ensuring a consistent look and feel across the documentation.

This page outlines the conventions for using existing shortcodes and provides an overview of the available components based on the project's contribution guidelines. While the creation of new shortcode logic (Go templates in layouts/shortcodes/) is not detailed, this guide covers how to correctly implement the existing shortcodes within your documentation contributions.

Sources: agent.yml:29-34, CONTRIBUTING.md:13-15

Shortcode Usage and Syntax

Shortcodes are invoked within Markdown files using a specific syntax. The project's contribution workflow enforces the correct usage to ensure proper rendering.

Invocation Syntax

All shortcodes must be called using the {{< shortcode >}} syntax. The use of {{% shortcode %}} is incorrect and will cause build issues. The "editor" agent in the automated workflow is responsible for verifying and fixing this syntax.

• Correct: {{< shortcode >}}
• Incorrect: {{% shortcode %}}

Sources: agent.yml:181-182

Shortcode Processing Flow

The following diagram illustrates how a shortcode in a Markdown file is processed by Hugo during the site build.

This diagram shows the process from a content author adding a shortcode to a Markdown file to the final rendered HTML on the website.

Sources: CONTRIBUTING.md:13-15, agent.yml:29-34

Available Shortcode Components

The documentation provides several pre-built shortcodes for common UI patterns.

Summary Bar

The summary-bar shortcode is used to display a feature's required subscription, version, or intended audience. It pulls data from the /data/summary.yaml file based on the feature_name parameter.

Usage:

{{< summary-bar feature_name="PKG installer" >}}

Configuration Attributes:

The summary-bar relies on attributes defined in /data/summary.yaml.

Attribute	Description	Possible Values
subscription	Notes the subscription required to use the feature.	All, Personal, Pro, Team, Business
availability	Notes the product development stage of the feature.	Experimental, Beta, Early Access, GA, Retired
requires	Notes 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:9-22

Badges

The badge shortcode is used to create small, colored labels to highlight content status, such as "new" or "deprecated". Badges can be used inline within text or in the page's front matter to appear in the sidebar.

Usage:

• Inline Badge:

  {{< badge color=amber text="amber badge" >}}
  

• Linked Badge:

  [{{< badge color="blue" text="badge with a link" >}}](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/../_index.md)
  

• Sidebar Badge (in Front Matter):

  ---
  title: Page title
  params:
    sidebar:
      badge:
        color: gray
        text: Deprecated
  ---
  

Parameters & Guidelines:

Parameter	Description
color	Sets the background color of the badge. Possible values: blue, amber, red, green, violet, gray.
text	The text displayed inside the badge.

Usage guidelines recommend using specific colors for different content statuses:

• Violet: New early access or experimental content.
• Blue: Beta content.
• Green: New GA or non-product content (e.g., guides).
• Gray: Deprecated content.

Sources: content/contribute/components/badges.md:9-37

Callouts

While not a shortcode, standard callouts for notes, tips, and warnings use a GitHub-flavored Markdown syntax that is processed by the build system. The "editor" agent ensures this syntax is used correctly.

Syntax:

> [!NOTE]
> This is a note.

> [!IMPORTANT]
> This is important information.

> [!WARNING]
> This is a warning.

> [!CAUTION]
> This is a caution message.

Sources: agent.yml:179-180, content/contribute/components/call-outs.md:26-55

Other Shortcodes

The project utilizes other shortcodes for more complex layouts, though their specific parameters are not detailed in the contribution guides. Their existence is confirmed, and they are part of the rich component library.

• tabs
• accordion
• include

Sources: agent.yml:31-32, content/contribute/style/formatting.md:73-74

Contribution Workflow for Shortcodes

When contributing to the documentation, writers should focus on using the correct shortcodes for the desired UI component. The automated editing and validation process helps ensure syntactical correctness.

The following sequence diagram shows how an author's use of a shortcode is handled by the system's agents.

This diagram shows that the EditorAgent is responsible for verifying and correcting Hugo shortcode syntax before the final validation step.

Sources: agent.yml:165-190

Summary

Shortcodes are an integral part of the Docker documentation, enabling the creation of rich, consistent, and maintainable content. Contributors should familiarize themselves with the available components like summary-bar and badge and adhere to the specified {{< shortcode >}} syntax. The project's automated tooling, particularly the EditorAgent, assists in enforcing these standards, allowing writers to focus on creating high-quality technical content.

Sources: content/contribute/guides.md:9-11, CONTRIBUTING.md:13-15