-
Notifications
You must be signed in to change notification settings - Fork 115
Shortcodes
Shortcodes are Hugo template fragments that let you embed reusable content or rendered widgets inside a Markdown page. The templates live in layouts/shortcodes/.
This page documents every shortcode in the site and how to call it.
Three call forms exist:
-
Bare —
{{< name arg="value" >}}— for shortcodes that have no inner content. -
Paired —
{{< name >}}content{{< /name >}}— for shortcodes that wrap content. -
Self-closing —
{{< name arg="value" />}}— explicit empty form. Hugo requires this whenever the template references.Innerbut you pass no inner content.
Use the bare form for attribute-only shortcodes; use the paired form only when the shortcode wraps content (note, opendetails, tabs).
- Create
layouts/shortcodes/<name>.html. - Read parameters with
{{ .Get "name" }}for named arguments,{{ .Get 0 }}for positional arguments, or{{ .Inner }}for wrapped content. - Call the shortcode from any file in
content/.
If your template uses .Inner, callers must close the tag (paired or self-closing). If it does not, the bare form works.
-
Callouts and notes —
alert,note,beta -
Media and embeds —
audio,rumble,openapi -
Layout and interactivity —
tabs,tab,opendetails,icon -
Reusable blurbs — eighteen
blurb/*fragments -
Package and image mappings — three
package-mappings/*tables
Renders a Bootstrap-styled callout with an icon. Use it for inline warnings, error messages, success confirmations, or info notes.
Parameters
| Name | Required | Default | Description |
|---|---|---|---|
context |
no | info |
One of info, success, warning, danger. Controls color and icon. |
text |
no | — | Alert text (supports Markdown). Use this or inner content. |
| (inner) | no | — | Markdown content if text is not set. |
Example
{{< alert context="danger" text="Error: failed to build layer image: initializing apk: failed to fixate apk world." />}}
Renders a Note: blockquote with Markdown support.
Parameters
| Name | Required | Description |
|---|---|---|
| (inner) | yes | Note content. Supports Markdown. |
Example
{{< note >}}
This presentation was recorded in November 2022. Some commands and configurations have changed since.
{{< /note >}}
Marks a feature as in beta. Use this on any page describing a beta-status Chainguard feature.
Parameters
| Name | Required | Default | Description |
|---|---|---|---|
feature |
no | This feature |
Name of the feature in beta. |
enroll |
no | — | Set to "true" to append: "Contact your Chainguard account team to enable it for your organization." |
access |
no | — | Free-text scope description. Appends: "Available to <value>." |
feedback |
no | — | Set to "true" to append: "Share feedback with your account team." |
Examples
{{< beta feature="The Guardener" >}}
{{< beta feature="Policy gates" enroll="true" >}}
{{< beta feature="Private APK Repositories" access="all Chainguard Containers customers" >}}
{{< beta feature="The Requests section" feedback="true" >}}
Notes
Use beta for product status callouts only — not for third-party "beta" mentions, version strings, or descriptions of beta behavior (rate limits, page tokens). For features that are nominally GA but still evolving, keep the word "beta" in the callout (legal carries the implication forward) and use the access parameter to clarify who can use it.
Embeds an HTML5 audio player with a caption.
Parameters
| Name | Required | Description |
|---|---|---|
src |
yes | URL or path to the audio file. |
caption |
no | Caption displayed below the player. |
Example
{{< audio src="tts-example.wav" caption="Output from the TTS script" >}}
Embeds an interactive image-comparison widget that contrasts two container images side by side.
Parameters
| Name | Required | Description |
|---|---|---|
title |
no | Title shown above the iframe. |
description |
no | Description shown above the iframe. |
left |
yes | Image identifier for the left side. |
right |
yes | Image identifier for the right side. |
Example
{{< rumble title="Nginx" description="Comparing the latest official Nginx image with cgr.dev/chainguard/nginx" left="nginx:latest" right="cgr.dev/chainguard/nginx:latest" >}}
The widget loads from /rumble/bar/ and requires the js/rumble/base.js module.
Embeds an OpenAPI specification viewer (Scalar UI) styled to fit Chainguard Academy.
Parameters
| Name | Required | Description |
|---|---|---|
spec-url |
yes | Path to the OpenAPI/Swagger JSON file. |
Example
{{< openapi spec-url="/api-v2beta1.json" >}}
Container for one or more tab shortcodes. Renders a horizontal tab strip.
Parameters
| Name | Required | Description |
|---|---|---|
| (inner) | yes | One or more nested {{< tab >}} calls. |
Example
{{< tabs >}}
{{< tab url="#overview" title="Overview" active="true" >}}
{{< tab url="#install" title="Install" >}}
{{< /tabs >}}
Single tab item. Only valid as a child of tabs.
Parameters
| Name | Required | Description |
|---|---|---|
url |
yes | Hyperlink target. |
title |
yes | Display text. |
active |
no | If set to any truthy value, marks the tab as active. |
See tabs above for the full example.
Renders a <details> element that starts in the expanded state.
Parameters
| Name | Position | Required | Description |
|---|---|---|---|
| Summary | 0 | yes | Clickable header text. |
| Attributes | 1 | no | Extra HTML attributes for the <details> element. |
| (inner) | — | yes | Body content. Supports Markdown. |
Example
{{< opendetails "What is Wolfi?" >}}
Wolfi is a community Linux undistro designed for containers, with first-class supply-chain security.
{{< /opendetails >}}
Renders a single Bootstrap Icon inline.
Parameters
| Position | Required | Description |
|---|---|---|
| 0 | yes | Bootstrap Icon name. Becomes bi-<name>. |
Example
See the {{< icon "play-circle-fill" >}} video walkthrough.
Icons are decorative by default (aria-hidden="true"). Do not rely on an icon alone to convey meaning. See Adding icons to a page for the full guide.
Blurbs are static or lightly parameterized snippets stored in layouts/shortcodes/blurb/. Call them with the subdirectory path:
{{< blurb/sbom >}}
Most blurbs take no parameters and exist to keep recurring explanations consistent across pages.
Explains cryptographic attestations and their role in associating SBOMs and SLSA provenance with container images. No parameters.
Explains CUDA setup requirements and links to cloud GPU options (Google Cloud Deep Learning VMs, AWS ML AMIs). No parameters.
Explains CVSS severity bands (Critical, High, Medium, Low) and links to the CVSS v4.0 user guide. No parameters.
Explains deep learning, neural networks, and applications such as speech-to-text and generative AI. No parameters.
One-sentence definition of distroless container images. No parameters.
Renders a table of domains to allowlist for Chainguard policy enforcement. Pulls data from site.Data.domains, so updates happen in the data file rather than in each page. No parameters.
Renders a list of IP addresses to allowlist. Pulls from site.Data.ips. No parameters.
Blockquote announcing the November 2024 free-tier changes for Chainguard Containers. No parameters.
One-sentence definition of Chainguard Containers (distroless, Wolfi-based, daily rebuilds). No parameters.
Section explaining how to extend Chainguard images. Promotes Custom Assembly over ad-hoc apk add.
| Name | Required | Description |
|---|---|---|
image |
yes | Image name (e.g., Python, Go, nginx) used to build documentation links. |
Example
{{< blurb/images-advanced image="Python" >}}
Multi-method install guide for Syft (shell script, Homebrew, container). Markdown source. No parameters.
Step-by-step instructions for generating a JFrog Artifactory access token and configuring docker login. No parameters.
Explains multi-stage Docker builds and the security benefits of -dev vs. production variants. No parameters.
Troubleshooting steps for enabling HTTP/2 in Zscaler decrypting proxy for use with chainctl. No parameters.
Short definition of SBOMs with a link to the longer write-up at /open-source/sbom/what-is-an-sbom/. No parameters.
Short definition of the SPDX file format. Markdown source. No parameters.
Promotes Custom Assembly over inline apk add for extending base images. No parameters.
One-sentence definition of Wolfi. No parameters.
These shortcodes render collapsible tables sourced from site.Data["package-mappings"]. They take no parameters.
Collapsible table mapping Debian package names to Chainguard/Wolfi equivalents.
{{< package-mappings/debian-packages >}}
Collapsible table mapping Fedora package names to Chainguard/Wolfi equivalents.
{{< package-mappings/fedora-packages >}}
Collapsible table mapping upstream container image names to Chainguard equivalents.
{{< package-mappings/image-mappings >}}
To update any of these tables, edit the corresponding YAML or JSON file under data/package-mappings/. The shortcode picks up changes on the next build.
If you have any questions or suggestions regarding our Style Guide, please create an issue and we will follow up accordingly.