# Icons

Add icons anywhere — inline text, buttons, cards, headings, and links. UI icons come from [Lucide](https://lucide.dev/icons/) (1900+ icons) and brand logos from [Simple Icons](https://simpleicons.org/) (3400+ icons). All icons are inlined as SVG at build time — only icons you actually use are included in the output.

## Inline icons

Write `icon:name` anywhere in your markdown. The icon renders inline at the same size as the surrounding text and inherits its color.

```markdown
## icon:rocket Getting Started

This feature includes icon:shield-check end-to-end encryption.

- icon:check Fast builds
- icon:check Live reload
- icon:check Zero config
```

## icon:rocket Getting Started (live example)

This feature includes icon:shield-check end-to-end encryption.

- icon:check Fast builds
- icon:check Live reload
- icon:check Zero config

## Inline icon modifiers

Add `+size:N` and `+color:value` after any inline icon to control its pixel size and color. Modifiers can be combined in any order.

```markdown
icon:star +size:28

icon:heart +color:red

icon:rocket +size:32 +color:blue

icon:shield-check +color:accent

icon:zap +size:24 +color:#f59e0b
```

icon:star +size:28

icon:heart +color:red

icon:rocket +size:32 +color:blue

icon:shield-check +color:accent

icon:zap +size:24 +color:#f59e0b

### Size

`+size:N` sets the icon width and height in pixels. Without it, the icon matches the surrounding text size (1em).

```markdown
icon:circle +size:16 icon:circle +size:24 icon:circle +size:32 icon:circle +size:48
```

icon:circle +size:16 icon:circle +size:24 icon:circle +size:32 icon:circle +size:48

### Color

`+color:value` sets the icon color. Accepts any [named palette color](/docs/colors), a hex code, or the special keyword `accent`.

| Value | What it does |
|---|---|
| `+color:blue` | Named palette color |
| `+color:#ef4444` | Hex color |
| `+color:accent` | Theme accent color — adapts to light, dark, and paper modes |

```markdown
icon:heart +color:rose icon:heart +color:emerald icon:heart +color:accent icon:heart +color:#8b5cf6
```

icon:heart +color:rose icon:heart +color:emerald icon:heart +color:accent icon:heart +color:#8b5cf6

Without `+color:`, inline icons inherit `currentColor` from the surrounding text or link.

## Icons in links

Icons inside links inherit the link's accent color:

```markdown
[icon:external-link Open documentation](/docs)
[icon:book-open Read the guide](/docs/getting-started)
```

[icon:external-link Open documentation](/docs)
[icon:book-open Read the guide](/docs/getting-started)

## Button icons

Add `+icon:name` to any `button:` line. The icon appears to the left of the label by default. Use `+icon-right:name` for right placement.

```markdown
button: Get Started: /docs/getting-started +icon:rocket
button: Learn More: /docs +icon-right:arrow-right +outline
```

button: Get Started: none +icon:rocket
button: Learn More: none +icon-right:arrow-right +outline

Icons combine with all button modifiers — `+outline`, `+big`, `+color:`:

button: Download: none +icon:download +big
button: Settings: none +icon:settings +outline +color:violet
button: Home: none +icon:home +color:emerald
button: Accent: none +icon:zap +color:accent

| Modifier | Position |
|---|---|
| `+icon:name` | Left of label (default) |
| `+icon-left:name` | Left of label (explicit) |
| `+icon-right:name` | Right of label |

Icons scale with button size and inherit button text color automatically — white on filled buttons, accent on outline.

See [Buttons & Links](/docs/buttons-and-links#button-icons) for full button documentation.

## Card icons

Use `card-icon:` instead of `card-image:` to display an icon above the card content. Add `+color:name` or `+color:#hex` to override the default accent color.

```markdown
card: Analytics
card-icon: bar-chart-2
card-text: Track your site performance.
card-link: Learn more: /features

card: Security
card-icon: shield-check +color:emerald
card-text: Enterprise-grade security.
card-link: Learn more: /features

card: Global CDN
card-icon: globe +color:accent
card-text: Edge delivery worldwide.
card-link: Learn more: /features
```

card: Analytics
card-icon: bar-chart-2
card-text: Track your site performance.
card-link: Learn more: /features

card: Security
card-icon: shield-check +color:emerald
card-text: Enterprise-grade security.
card-link: Learn more: /features

card: Global CDN
card-icon: globe +color:accent
card-text: Edge delivery worldwide.
card-link: Learn more: /features

`card-icon:` and `card-image:` are mutually exclusive — if both are present, the icon takes precedence. See [Cards](/docs/cards#cards-with-icons) for full card documentation.

## Brand icons

Brand logos from [Simple Icons](https://simpleicons.org/) work with the same `icon:name` syntax. Use the kebab-case slug from simpleicons.org.

```markdown
Built with icon:github GitHub and deployed on icon:cloudflare Cloudflare.

button: View on GitHub: /repo +icon:github
button: Open in Figma: /design +icon:figma +outline
```

Built with icon:github GitHub and deployed on icon:cloudflare Cloudflare.

button: View on GitHub: none +icon:github
button: Open in Figma: none +icon:figma +outline

| Icon | Name |
|---|---|
| icon:github | `github` |
| icon:figma | `figma` |
| icon:stripe | `stripe` |
| icon:cloudflare | `cloudflare` |
| icon:npm | `npm` |
| icon:docker | `docker` |
| icon:vercel | `vercel` |
| icon:netlify | `netlify` |
| icon:linear | `linear` |

Browse all 3400+ brand icons at [simpleicons.org](https://simpleicons.org/).

### Name collisions

About 30 names exist in both Lucide and Simple Icons (e.g., `apple`, `x`, `bluetooth`). Lucide wins by default — `icon:apple` gives you the Lucide apple icon. To force the brand logo, prefix with `brand-`:

```markdown
icon:apple Lucide apple vs icon:brand-apple Apple Inc. logo
```

icon:apple Lucide apple vs icon:brand-apple Apple Inc. logo

The `brand-` prefix is only needed for these collision cases. Most brand names (like `github`, `figma`, `stripe`) don't collide and work directly.

## How it works

Icons are resolved from `lucide-static` and `simple-icons` at build time. When the build encounters an icon name, it checks Lucide first, then Simple Icons. The matching SVG is read from disk, normalized, and inlined directly into the HTML output. A per-build cache ensures each icon is read only once.

- No external requests — icons are local files
- No icon fonts or CSS imports — pure inline SVG
- Only referenced icons appear in output — zero waste
- Icons use `currentColor` so they inherit text, link, and button colors automatically

## Finding icon names

**UI icons** — browse at [lucide.dev/icons](https://lucide.dev/icons/). Use the kebab-case name shown on each icon page.

| Icon | Name |
|---|---|
| icon:arrow-right | `arrow-right` |
| icon:check | `check` |
| icon:home | `home` |
| icon:rocket | `rocket` |
| icon:shield-check | `shield-check` |
| icon:settings | `settings` |
| icon:mail | `mail` |
| icon:globe | `globe` |
| icon:download | `download` |
| icon:book-open | `book-open` |

**Brand icons** — browse at [simpleicons.org](https://simpleicons.org/). Use the slug shown on each icon page.

If an icon name doesn't match either library, the build prints a warning and the text is left unchanged.

## Syntax reference

| Context | Syntax | Sizing | Color |
|---|---|---|---|
| Inline text | `icon:name` | 1em (text size) | Inherits `currentColor` |
| Inline + modifiers | `icon:name +size:N +color:val` | Explicit px | Named, hex, or `accent` |
| Links | `icon:name` inside `[...]()` | 1em (text size) | Link accent color |
| Buttons | `+icon:name` modifier | Scales with button | Button text color |
| Cards | `card-icon: name` | 48px | Accent (override with `+color:`) |

The `+color:accent` keyword works on inline icons, buttons, and card icons. It outputs the theme's accent color as a CSS variable, so it adapts automatically when the user switches between light, dark, and paper modes.