Iconify Extension for Quarto

This extension provides support to free and open source icons provided by Iconify.
Icons can be used only in HTML-based documents.

Installing

quarto add mcanouil/quarto-iconify

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

Using

To embed an icon, use the {{< iconify >}} shortcode. For example:

{{< iconify copilot-24 >}}
{{< iconify fluent-emoji exploding-head >}}
{{< iconify fluent-emoji:exploding-head >}}
{{< iconify copilot-24 size=2xl >}}
{{< iconify copilot-24 size=5x rotate=180deg >}}
{{< iconify copilot-24 size=Huge >}}
{{< iconify fluent-emoji-high-contrast 1st-place-medal >}}
{{< iconify twemoji 1st-place-medal >}}
{{< iconify line-md loading-alt-loop >}}
{{< iconify fa6-brands apple width=50px height=10px rotate=90deg flip=vertical >}}
{{< iconify simple-icons:quarto style="color:#74aadb;" >}}

This extension includes support for thousands of icons (including animated icons). You can browse all of the available sets of icons here:

https://icon-sets.iconify.design/

Iconify Attributes

Iconify API provides additional attributes: https://docs.iconify.design/iconify-icon/.
Currently, this extension supports: <set>¹, size², width², height², flip, rotate, title³, label³ (i.e., aria-label), inline⁴, mode⁵, and style⁶.

{{< iconify <set=...> <icon> <size=...> <width=...> <height=...> <flip=...> <rotate=...> <title=...> <label=...> <inline=...> <mode=...> <style=...> >}}
{{< iconify <set:icon> <size=...> <width=...> <height=...> <flip=...> <rotate=...> <title=...> <label=...> <inline=...> <mode=...> <style=...> >}}

Defining default values for attributes⁷:

iconify:
  set: "octicon"
  size: "Huge"
  width: "1em"
  height: "1em"
  flip: "horizontal"
  rotate: "90deg"
  inline: true
  mode: "svg"
  style: "color: #b22222;"

Sizing Icons

This extension provides relative, literal, and LaTeX-style sizing for icons.
When the size is invalid, no size changes are made.

• CSS-style sizing: {{< iconify exploding-head size=42px >}}.

• Relative sizing: {{< iconify exploding-head size=2xl >}}.

  Relative Sizing	Font Size	Equivalent in Pixels
  2xs	0.625em	10px
  xs	0.75em	12px
  sm	0.875em	14px
  lg	1.25em	20px
  xl	1.5em	24px
  2xl	2em	32px

• Literal sizing: {{< iconify exploding-head size=5x >}}.

  Literal Sizing	Font Size
  1x	1em
  2x	2em
  3x	3em
  4x	4em
  5x	5em
  6x	6em
  7x	7em
  8x	8em
  9x	9em
  10x	10em

• LaTeX-style sizing: {{< iconify exploding-head size=Huge >}}.

  Sizing Command	Font Size (HTML)
  tiny (= \tiny)	0.5em
  scriptsize (= \scriptsize)	0.7em
  footnotesize (= \footnotesize)	0.8em
  small (= \small)	0.9em
  normalsize (= \normalsize)	1em
  large (= \large)	1.25em
  Large (= \Large)	1.5em
  LARGE (= \LARGE)	1.75em
  huge (= \huge)	2em
  Huge (= \Huge)	2.5em

• width or height can be set to define icon's property while keeping aspect ratio.
  Note: width and height are not set if size was defined.

Example

Here is the source code for a minimal example: example.qmd.

This is the output of example.qmd for HTML.

---

Iconify by Vjacheslav Trushkin under MIT License.

Footnotes

1. The default icon set is octicon (source: https://github.com/microsoft/fluentui-emoji). ↩

2. If <size=...> is defined, <width=...> and <height=...> are not used. ↩ ↩² ↩³

3. title and label takes the following default value: Icon <icon> from <set> Iconify.design set.. ↩ ↩²

4. inline is a boolean attribute that can be set to true or false. Default is true. ↩

5. mode is a string attribute that can be set to "svg", "style", "bg", and "mask". Default is "svg". See Iconify renderings mode for more details. ↩

6. style is a string attribute expected to be a CSS style. ↩

7. The default values can be defined in the YAML header of the document. icon, title, and label have to be defined in the shortcode. ↩