Meta Loaders | Boltdocs

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

How It Works

Place a meta.json file in any folder inside docs/. Boltdocs scans for these files at build time and applies the metadata to that directory's sidebar group.

docs/
├── guides/
│   ├── meta.json          ← applies to all guides/ pages
│   ├── index.md
│   ├── installation.md
│   └── configuration.md
└── api/
    ├── _meta.json         ← also works with underscore prefix
    └── reference.md

meta.json Reference

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 desired order.
`icon`	`string`	Lucide icon name or raw 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`.

Examples

Basic Group Configuration

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

Collapsed by Default

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

Custom Ordering

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

Or use a numeric position:

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

Full Example

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

guides/meta.json:

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

api/meta.json:

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

Difference Between meta.json and _meta.json

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

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

Use whichever fits your workflow.

Precedence

Meta.json settings are applied in this order (later overrides earlier):

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

Debugging

If meta.json isn't taking effect:

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

Last updated on July 27, 2026

Was this page helpful?