Icons

Icons appear in the sidebar (next to pages and groups), in components like Cards, and in the navbar.

Setting the icon library

123{
  "icons": { "library": "lucide" }
}

Supported libraries:

Library	Description
`fontawesome`	Font Awesome free set (default)
`lucide`	Clean, consistent icons
`tabler`	Accepted by config, but not rendered yet

Prefixed icon names

Use prefixed icon names so the source library is explicit. This also lets you mix icons from different libraries in the same project:

12345678910// Lucide icons (recommended)
"icon": "lucide:rocket"
"icon": "lucide:shield"

// Font Awesome icons
"icon": "fontawesome:brands:github"
"icon": "fontawesome:solid:compass"

// Plain names resolve against the configured library
"icon": "rocket"  // resolves to lucide:rocket if "icons.library": "lucide"

Using icons in frontmatter

Set an icon on any page via frontmatter:

1234---
title: Authentication
icon: lucide:lock
---

The icon name is resolved against the configured library if no prefix is given.

Groups and anchors accept an icon field:

12345{
  "group": "Security",
  "icon": "lucide:shield",
  "pages": ["security/overview"]
}

Icon object form

For more control, use the object form to specify a library or style per icon. Font Awesome currently resolves the solid, regular, and brands styles:

1234567{
  "icon": {
    "name": "github",
    "library": "fontawesome",
    "style": "brands"
  }
}

Finding icon names

To browse all available icon names, fetch the schema JSONs:

12345# All lucide icon names
curl -s https://holocron.so/schemas/lucide-icons.json | jq '.enum[:10]'

# All fontawesome icon names
curl -s https://holocron.so/schemas/fontawesome-icons.json | jq '.enum[:10]'

Icon consistency

When adding icons, apply them consistently across all siblings at the same level. Inconsistent icon usage looks unfinished and breaks visual rhythm.

Tabs: if one tab has an icon, every tab must have an icon.
Groups: if one sidebar group has an icon, every sibling group in the same tab should too.
Anchors: if one anchor has an icon, all anchors must.
Pages: if one page in a group has a frontmatter icon, all pages in that group should.
Cards: if one <Card> in a <CardGroup> has an icon prop, every card in that group must.

If a group has an icon, avoid using the same icon on the first page in that group. It looks like a duplicate in the navigation tree.

Build-time atlas

Holocron collects all referenced icon names at build time and generates an atlas. Only the icons you actually use are included in the client bundle.