Icons

Make your docs easier to scan by adding icons to cards, sidebar navigation, and your site logo. Lumina includes all 1900+ Lucide icons — rendered as inline SVG at build time with zero runtime cost.

Tip

Not sure what’s available? The Icon Browser page has an interactive browser — search by name and click any icon to copy it.

Card Icons

Add an :icon: option to any {card} or {grid-item-card} directive:

docs/index.md

:::{card} Getting Started
:icon: rocket

Install and configure Lumina in minutes.
:::

Result:

Getting Started

Install and configure Lumina in minutes.

Featured Style

For landing pages or feature showcases, the featured style places a larger icon in a tinted pill above the title:

docs/index.md

:::{card} Getting Started
:icon: rocket
:icon-style: featured

Install and configure Lumina in minutes.
:::

Result:

Getting Started

Install and configure Lumina in minutes.

Grid Cards

Both styles work with {grid-item-card}:

Guides

Step-by-step tutorials.

Reference

API documentation.

FAQ

Common questions.

Options Reference

Option	Values	Default	Description
:icon:	Any Lucide icon name	—	Icon to display on the card
:icon-style:	inline, featured	inline	inline places the icon next to the title. featured shows a larger icon in a tinted pill above it.

Cards without :icon: render exactly as before.

Sidebar Icons

Add an icon field to a page’s frontmatter to display it in the sidebar:

docs/getting-started/index.md

---
icon: rocket
---
# Getting Started

The icon appears next to the page title in the sidebar. Pages without an icon field are unaffected — no empty space, no layout shift.

Tip

Sidebar icons work best on top-level section pages. Adding icons to every nested page creates visual clutter.

Logo Icon

Use a Lucide icon as your site logo instead of a custom image:

conf.py

html_theme_options = {
    "logo_icon": "hexagon",
}

The icon renders in your accent color and adapts to both light and dark mode automatically.

logo_icon is only used when no image logo is configured. If you set html_logo, light_logo, or dark_logo, those take precedence.

Finding Icon Names

Use the Icon Browser to search all 1900+ icons and click to copy names.

Icon names use kebab-case — the same format shown on lucide.dev/icons:

Example	Name
Rocket	rocket
Book Open	book-open
Circle Help	circle-help
Hexagon	hexagon
Sparkles	sparkles

If you use an icon name that doesn’t exist, the build continues without errors — the icon is silently omitted.