Badge
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
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.
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.
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:
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”.
| Component | Form | Status |
|---|---|---|
| Callouts | > [!NOTE] |
stable |
| Galleries | ```gallery fence |
stable |
| PlantUML | ```plantuml fence |
opt-in |
The image shortcode |
— | removed |
In lists and steps
- Install Hugo Extended ≥ 0.168.0
- Create a site from OINK Starter and change
baseURLinhugo.yaml hugo serverto 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.
One hugo mod get and you are done needs Go
Builds on a machine with no network manual upgrades
Clickable badges
With link, the badge becomes an <a> element. Site paths, relative paths, http(s):, and mailto: are supported.
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 |
| 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
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.
Related
- Cards —
cardhas abadgeparameter of its own - File trees —
toneuses the same vocabulary - Keys — the other inline shortcode
- Callouts — when the status needs explaining