Examples

Every option, rendered.

Each badge option shown as source alongside the badge this site renders from it.

Every badge below is rendered by the extension as this page is built.

The badges come from extensions.badge in this site’s _quarto.yml:

extensions:
  badge:
    - key: stable
      colour: springgreen
    - key: beta
      colour: gold
    - key: experimental
      class: bg-info
    - key: deprecated
      class: bg-warning
      href: https://github.com/mcanouil/quarto-badge/releases/tag/{{value}}
    - key: release
      colour: dodgerblue
      icon: tag
      href: https://github.com/mcanouil/quarto-badge/releases/tag/{{value}}
      target: _blank
      title: "Open release {{value}} in a new tab"
    - key: note
      colour: hotpink
      title: "Notes for release {{value}}"

Colours

colour takes any CSS colour and is applied as an inline background.

The `stable` and `beta` keys, set with the named colours `springgreen` and `gold`.
Source	Renders as
`{{< badge stable 2.5.0 >}}`	2.5.0
`{{< badge beta 2.6.0-beta1 >}}`	2.6.0-beta1

Classes

class styles the badge from CSS instead, which is how the Bootstrap background helpers are used.

The `deprecated` key, styled with `bg-warning`.
Source	Renders as
`{{< badge deprecated 1.0.0 >}}`	1.0.0

Links

href wraps the badge in an anchor, and {value} is replaced by the shortcode’s second argument. The badge above links to https://github.com/mcanouil/quarto-badge/releases/tag/1.0.0.

Icons, tooltips, and link targets

icon, title, and target combine on a single badge.

The `release` key adds a Bootstrap `tag` icon, a tooltip, and `target: _blank`; the `note` key carries a tooltip alone. Hover either one to read it.
Source	Renders as
`{{< badge release 2.5.0 >}}`	2.5.0
`{{< badge note 2.5.0 >}}`	2.5.0

Badges in headings

A badge renders inside a heading, which is where a version or status label usually belongs.

2.5.0 A stable feature

Written as ### {{< badge stable 2.5.0 >}} A stable feature {#a-stable-feature}.

The explicit identifier is worth setting. Quarto derives a heading’s automatic identifier before it expands shortcodes, so a heading left to itself gets a long hexadecimal identifier standing for the badge.

Caution

A badge with an href breaks the table of contents link of the heading it sits in. The heading above uses stable, which has no link, for that reason.

Document-level overrides

This page’s front matter carries a badge-overrides block:

badge-overrides:
  - key: experimental
    colour: hotpink
    class: ""
  - key: doc-only
    colour: teal
    icon: stars

The first entry replaces the project-level experimental badge, which is styled bg-info everywhere else on this site. It clears the class with class: "" because a Bootstrap background utility declares !important and would otherwise beat the inline colour. The second entry defines a badge that exists on this page only.

An overridden badge and a badge defined by the override alone.
Source	Renders as
`{{< badge experimental alpha >}}`	alpha
`{{< badge doc-only preview >}}`	preview

Source

The repository ships a short, standalone starting point you can copy: example.qmd.