Skip to content

Badge

Add a semantic status label beside a feature name, version, or table cell. Choose from five tones; custom colors are not supported.

A badge is an inline status label after a name, such as Beta, deprecated, v0.5, or needs a server. Use it for a status of one or two words. Choose a semantic tone. The theme selects colors with contrast in light and dark modes. If the status needs an explanation, procedure, or deadline, use prose or a callout.

Shortest form

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

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

Five tones

Use one of these five values. Custom colors are not supported.

Source
{{< 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

If you omit tone, the badge uses neutral. Other values warn and use neutral in ordinary previews. The warning identifies the source location and should be reviewed with the rendered fallback before publication.

Inside a sentence

A badge is an inline element after a name. It never occupies a separate line.

Source
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="opt-in" tone="info" >}}
uses its own site switch. Draw.io {{< badge text="needs a server" tone="warning" >}}
warns and remains off when no endpoint is configured.

With params.ui.image_zoom off by default enabled, block images that have alt text open full size. PlantUML opt-in uses its own site switch. Draw.io needs a server warns and remains off when no endpoint is configured.

Next to a heading

Never put a shortcode in a heading. Hugo builds the table of contents before it expands shortcodes. The badge displays in the heading, but an internal Hugo placeholder remains in the table of contents. Put the status in the first paragraph below the heading:

Source
### OpenAPI pages {#openapi-example}

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

OpenAPI pages

new in 0.5 The badge appears below the heading. The table of contents stays readable. The shared anchor link does not include the badge text.

In table cells

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

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

In lists and steps

Source
1. Install Hugo Extended {{< badge text="≥ 0.168.0" tone="info" >}}
1. Create a site from OINK Starter and change `baseURL` in `hugo.yaml`
1. `hugo server` to preview {{< badge text="port 1313" tone="neutral" >}}
{.steps}
  1. Install Hugo Extended ≥ 0.168.0
  2. Create a site from OINK Starter and change baseURL in hugo.yaml
  3. hugo server to preview port 1313

On cards

A card has its own badge parameter. This plain text appears to the right of the title. The card body can also contain badge shortcodes.

Source
{{< 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 >}}
Hugo Modulerecommended

One hugo mod get and you are done needs Go

Offline archive

Builds on a machine with no network manual upgrades

With link, the badge becomes an <a> element. Site paths, relative paths, http(s):, and mailto: are supported.

Source
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 invalid link warns and is removed, rendering a plain badge.

Output

Output Shape
HTML <span class="td-badge td-badge--<tone>">, or <a class="td-badge …"> when linked
Print Same as HTML, a static inline element
Markdown **Beta**, or [**Beta**](/…) when linked
RSS Same as print

Badges load no JavaScript. A badge is not a live region, so adding one does not produce a screen reader announcement.

Parameter reference

text , plain text , default—
Required, non-empty. What the reader sees
tone , enum , defaultneutral
neutral info success warning danger

Use named parameters only. There is no icon, class, color, outline, or size parameter. Invalid input warns and uses a safe fallback: unknown parameters are ignored, empty text renders nothing, invalid tone uses neutral, and unsafe links are removed.

Limits

  • Tone supplements the text. The text must state the status. {{< badge text="🔴" >}} gives a screen reader no meaning.
  • There is no icon parameter. If you need an icon, use cards or a callout.
  • Keep text short. Badges follow names without wrapping. Put text longer than a few words in the prose.
  • Use no more than three badges in one place. More badges make the associated name difficult to find.
  • Badges use only shortcodes. There is no native Markdown form. Plain Markdown readers show them as bold text.
  • 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