Icon

The built-in icon tag — drop a Font Awesome glyph or an SVG/image file inline in prose or a heading. It inherits the surrounding text's size and color, with optional color, size, scale, margin, and padding overrides.

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 class value, a bare icon name, or a path to an SVG/image file. Quote it:

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 when you’re ready, then star it on GitHub .

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

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

It sizes to the text

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

Ship faster

Built for teams

### 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:

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

Open the 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:

{% 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.

done, careful, bigger, 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:

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 up, or space it 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:

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

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.