Badge

Small, styled labels for versions and status, written as a shortcode.

What the badge extension is for, how to install it, and the smallest configuration that renders a badge.
Author

Mickaël CANOUIL, Ph.D.

Documentation carries a lot of small status signals: which release a feature landed in, what is still experimental, what is deprecated and kept only for compatibility. Written as prose they are easy to miss, and written as ad hoc HTML spans they drift apart the moment there is more than one page.

badge turns them into one configured vocabulary. Each kind of badge is defined once, under extensions.badge, and then written as {{< badge key value >}} wherever the label belongs, including inside a heading.

Installation

quarto add mcanouil/quarto-badge@2.6.1

This will install the extension under the _extensions subdirectory. If you are using version control, you will want to check in this directory.

Or install it from your editor with Quarto Wizard:

Visual Studio Code Positron VSCodium

Quick start

Define the badges once, in _quarto.yml for a whole project or in a document’s front matter for a single page:

extensions:
  badge:
    - key: stable
      colour: springgreen
    - key: experimental
      class: bg-info

Then write the shortcode wherever the label belongs:

Version {{< badge stable 2.5.0 >}}, beside a feature still marked {{< badge experimental alpha >}}.

Which renders as: Version 2.5.0, beside a feature still marked alpha.

The first argument is the key, which selects the configuration, and the second is the value shown inside the badge.

See the Reference for every option, and the Examples for each of them rendered.

Where it works

HTML output formats only. The shortcode contributes raw HTML, so in every other format the badge is dropped and the surrounding text is left intact.

Every user-supplied value is HTML-escaped before it is written to the document.

Back to top