Examples

Icons, and the attributes that shape them.

Iconify icons drawn by the extension, one section per attribute, with the shortcode alongside each.

Every icon below is drawn by the extension as this page renders. The site sets octicon as its default set.

Naming an icon

The two syntaxes, and icons from three sets.
Source Renders as
{{< iconify octicon:rocket-16 >}}

{{< iconify octicon rocket-16 >}}

{{< iconify mdi:home >}}

{{< iconify simple-icons:quarto >}}

Size

Keywords, multiples, CSS values, and explicit dimensions.
Source Renders as
{{< iconify mdi:home >}}

{{< iconify mdi:home size=2x >}}

{{< iconify mdi:home size=3em >}}

{{< iconify mdi:home width=48 height=48 >}}

Rotation and flipping

Rotating and flipping.
Source Renders as
{{< iconify mdi:arrow-up size=2x >}}

{{< iconify mdi:arrow-up size=2x rotate=90deg >}}

{{< iconify mdi:arrow-up size=2x flip=vertical >}}

Style

style takes any inline CSS, which is how an icon is coloured in HTML:

Colouring an icon in HTML.
Source Renders as
{{< iconify mdi:heart size=2x style="color: firebrick;" >}}

The color attribute is for Typst output, where the colour is baked into the retrieved SVG.

Accessibility

An icon is announced by default, so label every icon that carries meaning and hide every icon that does not.

{{< iconify octicon:alert-16 label="Warning" title="Warning" >}}

carries an aria-label and a tooltip reading Warning.

Left unset, both fall back to a generated string naming the set and the file:

What a screen reader reads out, with a label, without one, and hidden.
Source Announced as
{{< iconify octicon:alert-16 >}} Icon alert-16 from octicon Iconify.design set.
{{< iconify octicon:alert-16 label="Warning" >}} Warning
{{< iconify octicon:alert-16 aria-hidden='true' >}} Nothing. The icon is skipped.

An icon beside its own label

An icon inside a link that already has visible text says nothing the text does not. Labelled, it is announced twice over and pops a tooltip; hidden, the link reads as written:

[{{< iconify octicon:heart-fill-16 aria-hidden='true' >}} Sponsor](https://github.com/sponsors/mcanouil)

Sponsor

The accessible name of the surrounding link.
Source Link announced as
[{{< iconify octicon:heart-fill-16 label="Heart" >}} Sponsor](…) Heart Sponsor
[{{< iconify octicon:heart-fill-16 aria-hidden='true' >}} Sponsor](…) Sponsor

The Quarto icon

quarto is a second shortcode, drawing simple-icons:quarto in the Quarto blue:

The quarto shortcode, which takes the same attributes as iconify.
Source Renders as
{{< quarto >}}

{{< quarto size=2x >}}

Defaults

Set them once and drop them from every shortcode:

extensions:
  iconify:
    set: octicon
    size: 1.2em
    inline: true

With a default set, {{< iconify rocket-16 >}} is enough: .

When an icon cannot be loaded

extensions:
  iconify:
    fallback: "•"

The fallback is shown when the name is wrong, the CDN is unreachable, or the reader is offline.

Preloading avoids the question entirely, and needs the filter as well as the shortcode:

filters:
  - iconify
extensions:
  iconify:
    preload:
      - icons/octicon.json

Source

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

Back to top