example.qmd

---
title: Iconify Quarto Extension
subtitle: "Quarto Extension"
author:
  - name: "Mickaël CANOUIL, _Ph.D._"
    orcid: "0000-0002-3396-4549"
    url: "https://mickael.canouil.fr"
format:
  html:
    output-file: index
    toc: true
    reference-location: margin
    code-overflow: wrap
    code-tools: true
  typst:
    output-file: iconify-typst
    papersize: a4
    margin:
      x: 2.5cm
      y: 2.5cm
format-links:
  - html
  - typst
extensions:
  iconify:
    style: "color: #b22222;"
---

This extension provides support to free and open source icons provided by [Iconify](https://icon-sets.iconify.design/).

Icons render in HTML-based documents and in Typst output (where the SVG is retrieved from the Iconify API and cached locally).

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/>

## Installation

```sh
quarto add mcanouil/quarto-iconify@4.0.0
```

This will install the extension under the `_extensions` subdirectory.

If you're using version control, you will want to check in this directory.

## Usage

To embed an icon, use the `{{{< iconify >}}}` shortcode.

For convenience, a special `{{{< quarto >}}}` shortcode is also available to quickly insert the Quarto logo with preset styling.

- Mandatory `<icon>`:

  ```markdown
  {{{< iconify <icon> >}}}
  ```

  ```markdown
  {{{< iconify <set:icon> >}}}
  ```

### Iconify Attributes

Iconify API provides additional attributes: <https://docs.iconify.design/iconify-icon/>.

Currently, this extension supports the following attributes:

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

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

#### Available Attributes

- `set`: The icon set to use. Default is `octicon` (source: <https://github.com/microsoft/fluentui-emoji>).

- `size`: Sets both width and height. When `size` is defined, `width` and `height` are ignored. See [Sizing Icons](#sizing-icons) for available size options.

- `width` and `height`: Set icon dimensions whilst keeping aspect ratio. Not used if `size` is defined.

- `flip`: Flip the icon horizontally, vertically, or both.

- `rotate`: Rotate the icon by a specified angle (e.g., `90deg`, `180deg`).

- `title`: Tooltip text for the icon. Default: `Icon <icon> from <set> Iconify.design set.`.

- `label` (i.e., `aria-label`): Accessibility label for screen readers. Default: `Icon <icon> from <set> Iconify.design set.`.

- `inline`: Boolean attribute (`true` or `false`). When `true`, the icon is displayed inline with text. Default is `true`.

- `mode`: Rendering mode. Can be `"svg"` (default), `"style"`, `"bg"`, or `"mask"`. See [Iconify renderings mode](https://iconify.design/docs/iconify-icon/modes.html) for more details.

- `style`: CSS style string to apply custom styling to the icon.

#### Setting Default Values

You can define default values for most attributes in the YAML header using the nested structure under `extensions.iconify`:

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

:::: {.callout-note}

The attributes `icon`, `title`, and `label` must be defined in the shortcode itself and cannot have default values in the YAML header.

:::

:::: {.callout-warning}

The top-level `iconify:` configuration is deprecated but still supported for backward compatibility.
A warning will be displayed when using the deprecated format.
Please migrate to the new nested structure shown above.

:::

### 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 fluent-emoji:exploding-head size=42px >}}}`.

- Relative sizing: `{{{< iconify fluent-emoji: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 fluent-emoji: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 fluent-emoji: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 whilst keeping aspect ratio.

  :::: {.callout-note}

  `width` and `height` are not set if `size` was defined.

  :::

## Examples

The following table demonstrates various ways to use the iconify shortcode, including the special `{{{< quarto >}}}` shortcode for the Quarto logo:

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

### Fallback

The `fallback` attribute shows text or an emoji when the icon cannot be loaded (unknown name, offline, or CDN unreachable).

| Shortcode                                                                 | Icon                                                                  |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `{{{< iconify fluent-emoji no-such-icon-9999 fallback="🤯" >}}}`          | {{< iconify fluent-emoji no-such-icon-9999 fallback="🤯" >}}          |
| `{{{< iconify fluent-emoji also-missing fallback=":exploding-head:" >}}}` | {{< iconify fluent-emoji also-missing fallback=":exploding-head:" >}} |
| `{{{< iconify fluent-emoji exploding-head fallback="(missing)" >}}}`      | {{< iconify fluent-emoji exploding-head fallback="(missing)" >}}      |