Badge

A badge is an inline status label that sits right after a name: Beta, deprecated, v0.5, needs a server. It suits a status of one or two words. The author picks a semantic tone and the theme picks the colour, with contrast guaranteed in light and dark. When the status needs an explanation, a procedure or a deadline, use prose or a callout.

Shortest form

{{< badge text="Beta" tone="warning" >}}

text is the only required parameter and must be a non-empty string.

Five tones

These five values, and no custom colours.

{{< badge text="Default" >}}
{{< badge text="Info" tone="info" >}}
{{< badge text="Supported" tone="success" >}}
{{< badge text="Experimental" tone="warning" >}}
{{< badge text="Deprecated" tone="danger" >}}

Default Info Supported Experimental Deprecated

Without tone the badge is neutral. Any other value fails the build, and the error names the source location.

Inside a sentence

A badge is an inline element that follows a name; it never takes its own line.

With `params.ui.image_zoom` {{< badge text="off by default" tone="neutral" >}} enabled,
block images that have alt text open full size. PlantUML {{< badge text="needs a server" tone="warning" >}}
and Draw.io {{< badge text="needs a server" tone="warning" >}} fail the build when no endpoint is
configured, rather than reaching for a public service.

With params.ui.image_zoom off by default enabled, block images that have alt text open full size. PlantUML needs a server and Draw.io needs a server fail the build when no endpoint is configured, rather than reaching for a public service.

Next to a heading

Never put a shortcode in a heading. Hugo builds the table of contents before it expands shortcodes, so the badge renders correctly on the heading while the table of contents is left with an internal Hugo placeholder. Put the status in the first paragraph under the heading instead:

### OpenAPI pages {#openapi-example}

{{< badge text="new in 0.5" tone="success" >}} This section covers…

OpenAPI pages

new in 0.5 The badge sits just under the heading, the table of contents stays clean, and sharing the anchor link does not drag the badge text along.

In table cells

Badges make a comparison table easier to scan than a column of “yes” and “no”.

| Component | Form | Status |
| --- | --- | --- |
| Callouts | `> [!NOTE]` | {{< badge text="stable" tone="success" >}} |
| Galleries | ` ```gallery ` fence | {{< badge text="stable" tone="success" >}} |
| PlantUML | ` ```plantuml ` fence | {{< badge text="needs a server" tone="warning" >}} |
| The `image` shortcode | — | {{< badge text="removed" tone="danger" >}} |

In lists and steps

1. Install Hugo Extended {{< badge text="≥ 0.160.1" tone="info" >}}
1. Clone the documentation site and change `baseURL` in `hugo.yml`
1. `hugo server` to preview {{< badge text="port 1313" tone="neutral" >}}
{.steps}

1. Install Hugo Extended ≥ 0.160.1
2. Clone the documentation site and change baseURL in hugo.yml
3. hugo server to preview port 1313

On cards

A card has its own badge parameter — plain text, fixed to the right of the title — and the card body can hold badge shortcodes.

{{< cards >}}
{{< card title="Hugo Module" icon="fa-brands fa-golang" badge="recommended" >}}
One `hugo mod get` and you are done {{< badge text="needs Go" tone="info" >}}
{{< /card >}}
{{< card title="Offline archive" icon="fa-solid fa-box-archive" >}}
Builds on a machine with no network {{< badge text="manual upgrades" tone="warning" >}}
{{< /card >}}
{{< /cards >}}

Clickable badges

With link the badge becomes an <a>: site paths, relative paths, http(s): and mailto: all work.

Current version {{< badge text="v0.5" tone="info" link="/blog/" >}};
for the upgrade steps see {{< badge text="Upgrading" tone="neutral" link="/docs/admin/upgrade/" >}}.

Current version v0.5; for the upgrade steps see Upgrading.

An illegal link — a scheme outside the allowlist — fails the build.

Output

No JavaScript. A badge is not a live region, so adding one does not announce anything to a screen reader.

Parameter reference

Named parameters only. There is no icon, class, color, outline or size parameter; an unknown parameter, an empty text, an invalid tone and an illegal link all fail the build.

Limits

• Colour is not the meaning: tone supplements the text, which has to say it. {{< badge text="🔴" >}} tells a screen reader nothing.
• No icon parameter: when you need an icon, use cards or a callout.
• Keep the text short: a badge follows a name without wrapping, so anything longer than a few words belongs in the prose.
• No more than three in one place: a row of badges drowns out the name it qualifies.
• Badges exist only as a shortcode — there is no native Markdown form — and in a plain Markdown reader they degrade to bold text.

Related

• Cards — card has a badge parameter of its own
• File trees — tone uses the same vocabulary
• Keys — the other inline shortcode
• Callouts — when the status needs explaining