# Icon

A **built-in** inline tag for dropping an icon *inside* text — a sentence, a list item, or a
heading. Unlike the `icon:` front matter (which decorates a page or a nav entry),
`{% icon %}` goes anywhere in your Markdown and **inherits the surrounding
text's size and color**, so it always matches its context. It renders as plain inline HTML —
no JavaScript.

## Usage

The first argument is the icon — a [Font Awesome](https://fontawesome.com/icons) class value,
a bare icon name, or a path to an SVG/image file. Quote it:


```aardvark
Launch it {% icon "fa-solid fa-rocket" %} when you're ready, then star it {% icon "fa-solid fa-star" %} on GitHub {% icon "fab fa-github" %}.
```


renders, live:

Launch it <i class="aardvark-icon fa-solid fa-rocket" aria-hidden="true"></i> when you're ready, then star it <i class="aardvark-icon fa-solid fa-star" aria-hidden="true"></i> on GitHub <i class="aardvark-icon fab fa-github" aria-hidden="true"></i>.

A **bare name** is shorthand — it expands to the solid style (`rocket` → `fa-solid fa-rocket`):


```aardvark
{% icon "rocket" %} {% icon "heart" %} {% icon "bell" %} {% icon "gear" %}
```


<i class="aardvark-icon fa-solid fa-rocket" aria-hidden="true"></i> <i class="aardvark-icon fa-solid fa-heart" aria-hidden="true"></i> <i class="aardvark-icon fa-solid fa-bell" aria-hidden="true"></i> <i class="aardvark-icon fa-solid fa-gear" aria-hidden="true"></i>

## It sizes to the text

Because the icon is `1em`, it grows with whatever it sits in — including headings:

### Ship faster <i class="aardvark-icon fa-solid fa-rocket" aria-hidden="true"></i>

#### Built for teams <i class="aardvark-icon fa-solid fa-users" aria-hidden="true"></i>


```aardvark
### Ship faster {% icon "fa-solid fa-rocket" %}
#### Built for teams {% icon "fa-solid fa-users" %}
```


## SVG and image files

Point the spec at a file ending in `.svg`, `.png`, `.webp`, … and the icon renders as an
inline `<img>` boxed to the text size:


```aardvark
Open the {% icon "/icons/folder.svg" %} folder to continue.
```


Open the <img class="aardvark-icon" src="/icons/folder.svg" alt="" aria-hidden="true" /> folder to continue.

Image files keep their own colors — the `color` override below applies to Font Awesome glyphs only.

## Color, size, and scale

`color` tints a Font Awesome glyph; `scale` multiplies the text size; `size` sets an explicit
CSS length:


```aardvark
{% icon "fa-solid fa-circle-check" color="green" %} done, {% icon "fa-solid fa-triangle-exclamation" color="#e8590c" %} careful, {% icon "fa-solid fa-star" scale=1.5 %} bigger, {% icon "fa-solid fa-star" size="2rem" %} biggest.
```


<i class="aardvark-icon fa-solid fa-circle-check" style="color:green" aria-hidden="true"></i> done, <i class="aardvark-icon fa-solid fa-triangle-exclamation" style="color:#e8590c" aria-hidden="true"></i> careful, <i class="aardvark-icon fa-solid fa-star" style="--aardvark-icon-size:1.5em" aria-hidden="true"></i> bigger, <i class="aardvark-icon fa-solid fa-star" style="--aardvark-icon-size:2rem" aria-hidden="true"></i> biggest.

## Margin and padding

Sometimes a particular glyph sits a hair high or low for your text, or you want a little space
around an icon. `margin` and `padding` take **1–4 numbers** in the usual CSS shorthand order
(`top right bottom left`) and render as **pixels**. A negative `margin` shifts the icon — up,
down, left, or right:


```aardvark
Nudge it {% icon "fa-solid fa-star" margin="-2 0 0 0" %} up, or space it {% icon "fa-solid fa-star" padding="0 8" %} out.
```


Nudge it <i class="aardvark-icon fa-solid fa-star" style="margin:-2px 0px 0px 0px" aria-hidden="true"></i> up, or space it <i class="aardvark-icon fa-solid fa-star" style="padding:0px 8px" aria-hidden="true"></i> out.

The shorthand follows CSS: one number sets all four sides, two are vertical then horizontal,
three are top / horizontal / bottom, and four are top / right / bottom / left. Values are plain
numbers in pixels — `margin=2`, `margin="0 4"`, `margin="0 4 -2 0"`.

One wrinkle for **image icons**: a Font Awesome glyph grows to fit its `padding`, but an image
(`<img>`) icon sits in a fixed `1em` box, so `padding` insets the image *within* that box rather
than adding space around it. Use `margin` when you want outer space around an image icon —
`margin` always adds outer space, for both icon kinds.

## Accessibility

`label` exists for one reason: **screen-reader accessibility**. Icons are decorative by default
(`aria-hidden`), so assistive tech skips them and the surrounding text carries the meaning. But when
an icon stands alone and *is* the meaning — a lone GitHub glyph used as a link, say — a screen-reader
user would hear nothing. Give it an accessible name with `label` (it sets `aria-label`, or `alt` for
an image icon) so the icon is announced:


```aardvark
{% icon "fab fa-github" label="View on GitHub" %}
```


<i class="aardvark-icon fab fa-github" role="img" aria-label="View on GitHub"></i>

## Options

| Param | Effect |
| --- | --- |
| *(first arg)* | The icon: a Font Awesome class (`fa-solid fa-rocket`, `fab fa-github`), a bare name (`rocket` → `fa-solid fa-rocket`), or a path to an image file (`/icons/folder.svg`). Must be quoted. |
| `color` | Tints a Font Awesome glyph (any CSS color). Image files keep their own colors. |
| `scale` | Multiply the text size — `scale=1.5` is 1.5× the surrounding text. |
| `size` | An explicit CSS length (`size="20px"`, `size="1.5rem"`); a bare number is read as `em`. Wins over `scale`. |
| `margin` | 1–4 numbers (pixels), CSS shorthand order (`top right bottom left`). Negatives shift the icon — e.g. `margin="-2 0 0 0"` nudges it up. |
| `padding` | 1–4 numbers (pixels), CSS shorthand order. Opens space around a Font Awesome glyph; on an image icon (fixed `1em` box) it insets the image instead — use `margin` for outer space there. E.g. `padding="0 8"`. |
| `label` | Accessible name for a *meaningful standalone* icon — sets `aria-label` (or `alt` for images) so a screen reader announces it. Omit it for decorative icons, which are the default and hidden from assistive tech. |

Font Awesome glyphs need the Font Awesome stylesheet — set `theme.fontawesome: true` in
`aardvark.config.yaml` (this site does). A bare `fa-rocket` (an icon class with no style class
like `fa-solid`) won't render — use the full `fa-solid fa-rocket` or the bare `rocket`
shorthand. SVG and image-file icons need no setup. Keep `{% icon %}` on
the same line as adjacent text: an icon alone on its own line is treated as a block, not an
inline glyph.