Meta Loaders

Control sidebar groups with meta.json or _meta.json — per-directory metadata for titles, icons, ordering, and collapse state.

Boltdocs automatically loads meta.json or _meta.json files from your docs directories to control sidebar group metadata without editing each individual page.

Property	Type	Description
`title`	`string`	Display name for this sidebar group.
`order`	`string[] \| number`	Explicit ordering — either a position number or an array of page slugs in the desired order.
`icon`	`string`	Lucide icon name or inline SVG string for the group icon.
`collapsible`	`boolean`	Whether users can collapse/expand this group. Default: `true`.
`collapsed`	`boolean`	Whether the group starts collapsed on page load. Default: `false`.

json

{
  "title": "Getting Started",
  "icon": "Rocket"
}

json

{
  "title": "Advanced Topics",
  "collapsed": true,
  "collapsible": true
}

json

{
  "title": "Guide",
  "order": ["installation", "configuration", "deployment"]
}

Or use a numeric position:

json

{
  "title": "Guide",
  "order": 2
}

text

docs/
├── (guides)/
│   ├── meta.json
│   ├── index.md
│   ├── installation.md
│   └── configuration.md
└── (api)/
    ├── meta.json
    └── reference.md

guides/meta.json:

json

{
  "title": "Guides",
  "icon": "BookOpen",
  "collapsible": true,
  "collapsed": false
}

api/meta.json:

json

{
  "title": "API Reference",
  "icon": "Code2",
  "collapsed": true
}

Both work identically. The underscore variant is useful when you want the file hidden from the docs but still loaded:

meta.json — Visible in some IDEs, may show up in file explorers
_meta.json — Excluded from routing like other underscore-prefixed paths

Use whichever fits your workflow best.

meta.json settings apply in this order (later ones override earlier ones):

theme.sidebarGroups in configuration (global)
meta.json / _meta.json in the folder
Frontmatter of the folder's index.md (e.g., groupTitle, groupPosition)

If meta.json isn't taking effect:

Verify the file is named exactly meta.json or _meta.json
Check that the JSON is valid (no trailing commas)
Make sure the file is inside a folder containing .md or .mdx files
Check the console for "[Boltdocs] Failed to read meta.json" warnings

Jesús Alcalá

Last updated on October 18, 2026

Meta Loaders

meta.json Reference

Examples

Basic Group Configuration

Collapsed by Default

Custom Ordering

Full Example

Difference Between meta.json and _meta.json

Precedence

Debugging

Was this page helpful?