Frontmatter
Complete reference for every frontmatter field Boltdocs recognizes, including routing, sidebar, SEO, and display metadata.
Frontmatter is a YAML block at the top of any .md or .mdx file, enclosed by triple dashes (---). Boltdocs reads it to control routing, sidebar display, SEO, and page metadata.
# Getting Started
Your page content starts here...
Complete Reference
| Property | Type | Default | Description |
|---|---|---|---|
title | string | File name | The page title shown in the sidebar, browser tab, and OG tags. If omitted, Boltdocs uses the file name (with the numeric prefix stripped). |
description | string | First paragraph | A short description for SEO meta tags and search result snippets. Max 500 characters. |
permalink | string | — | Overrides the auto-generated URL for this page (e.g., '/docs/my-custom-path'). |
sidebarPosition | number | — | Explicit position of this page within its sidebar group. Lower numbers come first. |
sidebarLabel | string | title | A shorter label to show in the sidebar instead of the full page title. |
sidebarHidden | boolean | false | Hides this page from the sidebar while keeping it accessible via its URL. |
hidden | boolean | false | Alias of sidebarHidden. |
order | number | — | Alternative ordering field. Behaves the same as sidebarPosition. |
badge | string | BadgeConfig | — | A badge shown next to the page title in the sidebar. See BadgeConfig below. |
icon | string | — | A Lucide icon name (e.g., 'Rocket') or inline SVG string shown next to the page title. |
date | string | Date | — | Page publication date. Used in blog-style docs or changelogs. |
lastUpdated | string | Date | — | Timestamp shown in the "Last updated" footer. |
category | string | — | Free-form category label (max 50 characters). |
groupTitle | string | Folder name | On an index.md file, overrides the sidebar group title for the containing folder. |
groupPosition | number | — | On an index.md file, sets the ordering position of the entire group in the sidebar. |
seo | Record<string, any> | — | Custom Open Graph and meta tag overrides. See seo below. |
BadgeConfig
The badge field accepts either a simple string or an object with an optional expiration date. When an expiration is set and the date has passed, Boltdocs automatically hides the badge.
| Property | Type | Description |
|---|---|---|
text | string | The badge label (e.g., 'New', 'Beta', 'Deprecated'). Max 50 characters. |
expires | string | An ISO 8601 date string. After this date, the badge is no longer displayed. |
Examples:
---
# Simple string badge
badge: New
# Badge with expiration date
badge:
text: Beta
expires: '2026-12-31'
---
seo Field
Overrides or extends the auto-generated SEO meta tags for a specific page:
---
seo:
og:image: /assets/my-custom-og-image.png
og:type: article
twitter:card: summary_large_image
---
Any keys you provide here are merged over Boltdocs' default generated tags.
Permalink Override
Use permalink to decouple a page's URL from its file location. This is useful for migrating content without breaking existing links:
---
title: Legacy Setup Guide
permalink: /docs/setup
---
The file can live anywhere in docs/, but it will always be served at /docs/setup.
If two pages share the same permalink, the last one processed wins and a warning is printed to the console. Always make sure permalinks are unique.
Custom Frontmatter and useMdxComponents
You're not limited to the built-in frontmatter properties. You can add arbitrary custom keys to any page's frontmatter block to attach extra metadata (e.g., authors, versions, or status tags):
---
title: Advanced Guide
author: "Jane Doe"
version: "v2.1.0"
---
To render these custom fields using custom UI components, you can register components prefixed with Frontmatter_ inside your docs/mdx-components.tsx file.
Step 1: Register Custom Frontmatter Components
Export your formatting components by prefixing their names with Frontmatter_:
// Mapped component for the 'author' frontmatter key
function Frontmatter_author({ value }: { value: string }) {
return (
<div className="flex items-center gap-2 mt-2">
<span className="text-xs font-semibold text-zinc-500">Author:</span>
<span className="text-sm text-zinc-900 dark:text-zinc-100">{value}</span>
</div>
)
}
// Mapped component for the 'version' frontmatter key
function Frontmatter_version({ value }: { value: string }) {
return (
<span className="inline-block bg-primary-500/10 text-primary-500 text-xs px-2 py-0.5 rounded-full">
Added in {value}
</span>
)
}
export default {
Frontmatter_author,
Frontmatter_version,
}
Step 2: Fetch and Render via the Hook
In your layout or custom components, you can call the useMdxComponents hook to get your frontmatter registry. Boltdocs automatically strips the Frontmatter_ prefix and places these components in a nested Frontmatter namespace:
import { useMdxComponents, useRoutes } from 'boltdocs/client'
export default function CustomLayout({ children }) {
const { currentRoute } = useRoutes()
const components = useMdxComponents()
// Extract the custom frontmatter data from the current route
const author = currentRoute?.frontmatter?.author
const version = currentRoute?.frontmatter?.version
// Get the mapped formatter components
const AuthorFormatter = components.Frontmatter?.author
const VersionFormatter = components.Frontmatter?.version
return (
<div>
<header>
{AuthorFormatter && author && <AuthorFormatter value={author} />}
{VersionFormatter && version && <VersionFormatter value={version} />}
</header>
<main>{children}</main>
</div>
)
}
