Page Configuration via Frontmatter

How to control layout, sidebar, navigation, table of contents, draft mode, and feature flags — all from your MDX frontmatter.

Frontmatter as Configuration

Frontmatter isn't just for metadata and SEO. It's also a per-page configuration system. You can control layout, navigation, UI components, and feature flags right inside each MDX document — no external config files needed.

This is powerful because the configuration lives next to the content. You can see exactly how a page behaves by reading its frontmatter. No jumping between files.

yaml example

Layout Selection

The layout field picks which template wraps your content. Different page types get different visual structures, but they all go through the same content pipeline.

yaml example

---
# Layout options (defined by your application)
layout: "docs"          # Documentation with sidebar
# layout: "blog"       # Blog post with author info, date
# layout: "landing"    # Full-width, no chrome
# layout: "tutorial"   # Step-by-step with progress
# layout: "reference"  # API reference with type tables
# layout: "minimal"    # Content only, no nav/footer
# layout: "fullscreen" # Presentation-style
---

Implementing Layout Selection

Here's how you'd wire up layout switching in different frameworks.

Next.js (App Router):

Example

// app/docs/[...slug]/page.tsx import DocsLayout from '@/layouts/DocsLayout'; import BlogLayout from '@/layouts/BlogLayout'; import LandingLayout from '@/layouts/LandingLayout'; const layouts = { docs: DocsLayout, blog: BlogLayout, landing: LandingLayout, default: DocsLayout, }; export default async function Page({ params }) { const post = await getPost(params.slug); const LayoutComponent = layouts[post.frontmatter.layout] || layouts.default; return ( <LayoutComponent frontmatter={post.frontmatter}> <post.Content /> </LayoutComponent> ); }

Docusaurus:

yaml example

---
# Docusaurus built-in layout options
sidebar_class_name: "custom-sidebar"
hide_title: false
hide_table_of_contents: false
# Custom page class for CSS targeting
custom_edit_url: "https://github.com/org/repo/edit/main/docs/page.mdx"
---

Gatsby:

Example

// gatsby-node.js exports.createPages = async ({ graphql, actions }) => { const posts = await graphql(` query { allMdx { nodes { frontmatter { layout slug } internal { contentFilePath } } } } `); posts.data.allMdx.nodes.forEach(node => { const layout = node.frontmatter.layout || 'default'; const template = path.resolve(`./src/templates/${layout}.tsx`); actions.createPage({ path: node.frontmatter.slug, component: `${template}?__contentFilePath=${node.internal.contentFilePath}`, }); }); };

You can control sidebar visibility, position, grouping, and ordering from each document's frontmatter. No central sidebar config file needed.

yaml example

---
sidebar:
  # Display in sidebar? (false to hide from nav while keeping page accessible)
  visible: true
  
  # Sidebar label (shorter than page title)
  label: "Auth Setup"
  
  # Position within its group (lower = higher)
  order: 3
  
  # Sidebar group/category
  group: "Getting Started"
  
  # Group order (for sorting groups themselves)
  groupOrder: 1
  
  # Sidebar position on page
  position: "left"          # "left", "right", "none"
  
  # Collapsible section behavior
  collapsed: false          # Start collapsed?
  collapsible: true         # Can it be collapsed?
  
  # Icon for visual distinction
  icon: "🔐"
  
  # Badge for status indicators
  badge:
    text: "New"
    color: "green"
---

Here's how you'd read all the sidebar frontmatter and build a grouped, sorted navigation:

Example

// lib/sidebar.ts import { allDocs } from 'contentlayer/generated'; interface SidebarItem { title: string; href: string; order: number; icon?: string; badge?: { text: string; color: string }; } interface SidebarGroup { name: string; order: number; items: SidebarItem[]; } export function buildSidebar(): SidebarGroup[] { const groups: Record<string, SidebarGroup> = {}; allDocs .filter(doc => doc.sidebar?.visible !== false && !doc.draft) .forEach(doc => { const groupName = doc.sidebar?.group || "Uncategorized"; if (!groups[groupName]) { groups[groupName] = { name: groupName, order: doc.sidebar?.groupOrder || 99, items: [], }; } groups[groupName].items.push({ title: doc.sidebar?.label || doc.title, href: doc.url, order: doc.sidebar?.order || 99, icon: doc.sidebar?.icon, badge: doc.sidebar?.badge, }); }); return Object.values(groups) .sort((a, b) => a.order - b.order) .map(group => ({ ...group, items: group.items.sort((a, b) => a.order - b.order), })); }

yaml example

---
# Docusaurus-specific sidebar fields
sidebar_position: 3
sidebar_label: "Authentication"
sidebar_class_name: "sidebar-auth"
sidebar_custom_props:
  icon: "🔐"
  description: "Learn how to authenticate API requests"
---

Control how pages show up in nav menus, breadcrumbs, and prev/next pagination.

yaml example

---
# Explicit ordering
nav:
  order: 5                    # Position in nav menu
  weight: 5                   # Alternative naming convention
  
  # Breadcrumb path
  breadcrumb:
    - label: "Documentation"
      href: "/docs"
    - label: "API Reference"
      href: "/docs/api"
    - label: "Authentication"
  
  # Previous/Next links (manual override)
  prev:
    title: "Getting Started"
    href: "/docs/api/getting-started"
  next:
    title: "Endpoints"
    href: "/docs/api/endpoints"
  
  # Navigation menu visibility
  showInMainNav: true
  showInFooterNav: false
  
  # Dropdown grouping
  menuGroup: "API"
  menuGroupOrder: 2
---

This component uses explicit prev/next if defined, or auto-determines them from page order:

Example

// components/PrevNextNav.jsx export function PrevNextNav({ frontmatter, allPages }) { // Use explicit prev/next if defined const prev = frontmatter.nav?.prev; const next = frontmatter.nav?.next; // Otherwise, auto-determine from order const currentOrder = frontmatter.nav?.order || 0; const sorted = allPages .filter(p => !p.draft) .sort((a, b) => (a.nav?.order || 0) - (b.nav?.order || 0)); const currentIndex = sorted.findIndex(p => p.slug === frontmatter.slug); const autoPrev = currentIndex > 0 ? sorted[currentIndex - 1] : null; const autoNext = currentIndex < sorted.length - 1 ? sorted[currentIndex + 1] : null; return ( <nav className="prev-next"> {(prev || autoPrev) && ( <a href={prev?.href || autoPrev.url} className="prev"> ← {prev?.title || autoPrev.title} </a> )} {(next || autoNext) && ( <a href={next?.href || autoNext.url} className="next"> {next?.title || autoNext.title} → </a> )} </nav> ); }

Table of Contents Settings

Configure the auto-generated TOC on a per-page basis. Some pages need a deep TOC, others don't need one at all.

yaml example

---
toc:
  # Enable/disable TOC for this page
  enabled: true
  
  # Heading levels to include
  minDepth: 2            # Start at h2 (skip h1 title)
  maxDepth: 4            # Include h2, h3, h4
  
  # TOC position
  position: "right"      # "right", "inline", "floating", "none"
  
  # Behavior
  sticky: true           # Stick to viewport on scroll
  highlightActive: true  # Highlight current section
  collapsible: false     # Allow collapsing
  
  # Display
  title: "On This Page"  # Custom TOC heading
  ordered: false         # Use numbered list
  
  # Exclude specific headings
  exclude:
    - "References"
    - "Changelog"
---

Framework Implementations

Docusaurus:

yaml example

---
# Docusaurus TOC configuration
hide_table_of_contents: false
toc_min_heading_level: 2
toc_max_heading_level: 4
---

Next.js (custom implementation):

Example

// components/TableOfContents.jsx export function TableOfContents({ headings, config }) { if (config?.enabled === false) return null; const minDepth = config?.minDepth || 2; const maxDepth = config?.maxDepth || 3; const filteredHeadings = headings.filter( h => h.depth >= minDepth && h.depth <= maxDepth ); return ( <aside className={`toc toc--${config?.position || 'right'}`}> <h4>{config?.title || "On This Page"}</h4> <ul> {filteredHeadings.map(heading => ( <li key={heading.id} className={`toc-item toc-item--depth-${heading.depth}`} > <a href={`#${heading.id}`}>{heading.text}</a> </li> ))} </ul> </aside> ); }

Pagination Configuration

Control how long content gets split across pages or how posts appear in series.

yaml example

---
pagination:
  # Enable pagination for long content
  enabled: true
  
  # Manual page breaks (split single MDX into multiple pages)
  splitAtHeadings: true
  maxSectionsPerPage: 5
  
  # Series pagination
  series: "React Fundamentals"
  seriesOrder: 3
  totalInSeries: 8
  
  # Content list pagination (for index pages)
  itemsPerPage: 10
  showPageNumbers: true
  infiniteScroll: false
---

Draft Mode

Control content visibility and preview capabilities right from frontmatter.

Example

--- # Basic draft flag draft: true # Advanced publishing workflow publishing: status: "review" # draft, review, approved, published, archived scheduledFor: "2024-02-01T09:00:00Z" expiresAt: "2024-12-31" reviewers: - "editor@team.com" - "tech-lead@team.com" approvedBy: null publishedAt: null # Preview settings preview: enabled: true password=[REDACTED_PASSWORD] # Optional password protection shareableLink: true # Generate preview URL expiresIn: "7d" # Preview link expiration ---

Draft Filtering in Build

Here's a real filtering function that handles drafts, scheduled posts, and expired content:

Example

// lib/content.ts export function getPublishedPosts(allPosts: Post[]) { const now = new Date(); return allPosts.filter(post => { // Exclude drafts if (post.draft) return false; // Exclude future-scheduled content if (post.publishing?.scheduledFor && new Date(post.publishing.scheduledFor) > now) { return false; } // Exclude expired content if (post.publishing?.expiresAt && new Date(post.publishing.expiresAt) < now) { return false; } // Only show approved content if (post.publishing?.status && post.publishing.status !== "published") { return false; } return true; }); } // In development, show drafts with visual indicator export function getAllPosts(includeDrafts = false) { if (includeDrafts || process.env.NODE_ENV === 'development') { return allPosts; // Show everything in dev } return getPublishedPosts(allPosts); }

Custom CSS and Classes

Need page-specific styles without touching global stylesheets? Frontmatter can handle that too.

yaml example

---
# Page-level CSS customization
style:
  # CSS class applied to page wrapper
  className: "api-docs dark-theme"
  
  # Custom CSS variables for this page
  variables:
    --accent-color: "#e63946"
    --content-max-width: "900px"
    --font-code: "JetBrains Mono"
  
  # Layout overrides
  fullWidth: true
  maxWidth: "1400px"
  contentPadding: "2rem"
  
  # Background
  backgroundColor: "#fafafa"
  backgroundImage: "/images/patterns/grid.svg"
  
  # Typography
  fontSize: "base"          # "sm", "base", "lg"
  lineHeight: "relaxed"     # "tight", "normal", "relaxed"
  
# Body class (useful for CSS targeting)
bodyClass: "page-api-auth"

# Custom stylesheet import
customCSS: "/styles/api-docs.css"
---

Applying Custom Styles

Example

// layouts/PageLayout.jsx export default function PageLayout({ frontmatter, children }) { const style = frontmatter.style || {}; // Build CSS variables object const cssVariables = Object.entries(style.variables || {}).reduce( (vars, [key, value]) => ({ ...vars, [key]: value }), {} ); return ( <div className={`page-wrapper ${style.className || ''}`} style={{ ...cssVariables, maxWidth: style.maxWidth, padding: style.contentPadding, backgroundColor: style.backgroundColor, }} > {style.backgroundImage && ( <div className="page-bg" style={{ backgroundImage: `url(${style.backgroundImage})` }} /> )} <main className={style.fullWidth ? 'full-width' : 'contained'}> {children} </main> </div> ); }

Feature Flags Per Page

Turn interactive features on or off for individual pages. Great for A/B testing, progressive rollouts, or just disabling stuff that doesn't make sense on certain pages.

yaml example

---
features:
  # Interactive elements
  codePlayground: true       # Embedded code sandbox
  liveEditor: true           # Edit-in-place for code blocks
  copyButton: true           # Copy code button
  
  # UI components
  feedbackWidget: true       # "Was this helpful?" widget
  commentSection: false      # Reader comments
  shareButtons: true         # Social share buttons
  editOnGithub: true         # "Edit this page" link
  
  # Navigation
  breadcrumbs: true
  pageProgress: true         # Reading progress bar
  scrollToTop: true          # Scroll-to-top button
  
  # Experimental
  aiAssistant: false         # AI chat helper
  searchHighlight: true      # Highlight search terms
  readingMode: true          # Distraction-free toggle
  
  # Analytics
  trackScrollDepth: true
  trackTimeOnPage: true
  heatmapEnabled: false
  
  # Access control
  requireAuth: false
  premiumOnly: false
  membershipLevel: "free"    # "free", "pro", "enterprise"
---

Conditional Feature Rendering

A simple FeatureGate component that checks frontmatter before rendering:

Example

// components/FeatureGate.jsx export function FeatureGate({ feature, frontmatter, children }) { const features = frontmatter.features || {}; const isEnabled = features[feature] ?? false; if (!isEnabled) return null; return <>{children}</>; } // Usage in layout function DocPage({ frontmatter, children }) { return ( <article> <FeatureGate feature="breadcrumbs" frontmatter={frontmatter}> <Breadcrumbs path={frontmatter.nav?.breadcrumb} /> </FeatureGate> <FeatureGate feature="pageProgress" frontmatter={frontmatter}> <ReadingProgressBar /> </FeatureGate> <div className="content">{children}</div> <FeatureGate feature="feedbackWidget" frontmatter={frontmatter}> <FeedbackWidget pageId={frontmatter.slug} /> </FeatureGate> <FeatureGate feature="commentSection" frontmatter={frontmatter}> <Comments slug={frontmatter.slug} /> </FeatureGate> <FeatureGate feature="shareButtons" frontmatter={frontmatter}> <ShareButtons title={frontmatter.title} /> </FeatureGate> </article> ); }

Complete Configuration Schema

Here's everything tied together in one Zod schema:

Example

import { z } from 'zod'; export const pageConfigSchema = z.object({ // Layout layout: z.enum(["docs", "blog", "landing", "tutorial", "reference", "minimal"]).default("docs"), fullWidth: z.boolean().default(false), // Sidebar sidebar: z.object({ visible: z.boolean().default(true), label: z.string().optional(), order: z.number().default(99), group: z.string().optional(), groupOrder: z.number().default(99), position: z.enum(["left", "right", "none"]).default("left"), collapsed: z.boolean().default(false), icon: z.string().optional(), badge: z.object({ text: z.string(), color: z.string(), }).optional(), }).optional(), // TOC toc: z.object({ enabled: z.boolean().default(true), minDepth: z.number().min(1).max(6).default(2), maxDepth: z.number().min(1).max(6).default(3), position: z.enum(["right", "inline", "floating", "none"]).default("right"), title: z.string().default("On This Page"), }).optional(), // Navigation nav: z.object({ order: z.number().optional(), prev: z.object({ title: z.string(), href: z.string() }).optional(), next: z.object({ title: z.string(), href: z.string() }).optional(), breadcrumb: z.array(z.string()).optional(), }).optional(), // Publishing draft: z.boolean().default(false), // Features features: z.record(z.boolean()).default({}), // Style style: z.object({ className: z.string().optional(), variables: z.record(z.string()).optional(), fullWidth: z.boolean().default(false), }).optional(), });

Best Practices

Set sensible defaults — Most pages should work with zero configuration. Only require fields when you truly need per-page values.

Use layout inheritance — Define base layouts with default settings, then let frontmatter override specific things.

Keep feature flags boolean — Simple on/off. If you need complex conditional logic, put it in code, not YAML.

Document your options — Maintain a reference page listing all config fields, valid values, and what they do.

Validate at build time — Catch invalid layout names, bad order values, and unsupported feature flags before you deploy.

Group related fields — Use nested objects (sidebar.*, toc.*, nav.*) instead of cluttering the top level with dozens of flat keys.

Support gradual adoption — Let pages work with zero config. Authors add fields as they need customization, not before.

Show active config in dev mode — Build a dev-only panel that displays the current page's resolved configuration. Makes debugging layout issues way easier.

Frontmatter as Configuration

This is powerful because the configuration lives next to the content. You can see exactly how a page behaves by reading its frontmatter. No jumping between files.

yaml example

Layout Selection

The layout field picks which template wraps your content. Different page types get different visual structures, but they all go through the same content pipeline.

yaml example

---
# Layout options (defined by your application)
layout: "docs"          # Documentation with sidebar
# layout: "blog"       # Blog post with author info, date
# layout: "landing"    # Full-width, no chrome
# layout: "tutorial"   # Step-by-step with progress
# layout: "reference"  # API reference with type tables
# layout: "minimal"    # Content only, no nav/footer
# layout: "fullscreen" # Presentation-style
---

Implementing Layout Selection

Here's how you'd wire up layout switching in different frameworks.

Next.js (App Router):

Example

Docusaurus:

yaml example

---
# Docusaurus built-in layout options
sidebar_class_name: "custom-sidebar"
hide_title: false
hide_table_of_contents: false
# Custom page class for CSS targeting
custom_edit_url: "https://github.com/org/repo/edit/main/docs/page.mdx"
---

Gatsby:

Example

You can control sidebar visibility, position, grouping, and ordering from each document's frontmatter. No central sidebar config file needed.

yaml example

---
sidebar:
  # Display in sidebar? (false to hide from nav while keeping page accessible)
  visible: true
  
  # Sidebar label (shorter than page title)
  label: "Auth Setup"
  
  # Position within its group (lower = higher)
  order: 3
  
  # Sidebar group/category
  group: "Getting Started"
  
  # Group order (for sorting groups themselves)
  groupOrder: 1
  
  # Sidebar position on page
  position: "left"          # "left", "right", "none"
  
  # Collapsible section behavior
  collapsed: false          # Start collapsed?
  collapsible: true         # Can it be collapsed?
  
  # Icon for visual distinction
  icon: "🔐"
  
  # Badge for status indicators
  badge:
    text: "New"
    color: "green"
---

Here's how you'd read all the sidebar frontmatter and build a grouped, sorted navigation:

Example

yaml example

---
# Docusaurus-specific sidebar fields
sidebar_position: 3
sidebar_label: "Authentication"
sidebar_class_name: "sidebar-auth"
sidebar_custom_props:
  icon: "🔐"
  description: "Learn how to authenticate API requests"
---

Control how pages show up in nav menus, breadcrumbs, and prev/next pagination.

yaml example

---
# Explicit ordering
nav:
  order: 5                    # Position in nav menu
  weight: 5                   # Alternative naming convention
  
  # Breadcrumb path
  breadcrumb:
    - label: "Documentation"
      href: "/docs"
    - label: "API Reference"
      href: "/docs/api"
    - label: "Authentication"
  
  # Previous/Next links (manual override)
  prev:
    title: "Getting Started"
    href: "/docs/api/getting-started"
  next:
    title: "Endpoints"
    href: "/docs/api/endpoints"
  
  # Navigation menu visibility
  showInMainNav: true
  showInFooterNav: false
  
  # Dropdown grouping
  menuGroup: "API"
  menuGroupOrder: 2
---

This component uses explicit prev/next if defined, or auto-determines them from page order:

Example

Table of Contents Settings

Configure the auto-generated TOC on a per-page basis. Some pages need a deep TOC, others don't need one at all.

yaml example

---
toc:
  # Enable/disable TOC for this page
  enabled: true
  
  # Heading levels to include
  minDepth: 2            # Start at h2 (skip h1 title)
  maxDepth: 4            # Include h2, h3, h4
  
  # TOC position
  position: "right"      # "right", "inline", "floating", "none"
  
  # Behavior
  sticky: true           # Stick to viewport on scroll
  highlightActive: true  # Highlight current section
  collapsible: false     # Allow collapsing
  
  # Display
  title: "On This Page"  # Custom TOC heading
  ordered: false         # Use numbered list
  
  # Exclude specific headings
  exclude:
    - "References"
    - "Changelog"
---

Framework Implementations

Docusaurus:

yaml example

---
# Docusaurus TOC configuration
hide_table_of_contents: false
toc_min_heading_level: 2
toc_max_heading_level: 4
---

Next.js (custom implementation):

Example

Pagination Configuration

Control how long content gets split across pages or how posts appear in series.

yaml example

---
pagination:
  # Enable pagination for long content
  enabled: true
  
  # Manual page breaks (split single MDX into multiple pages)
  splitAtHeadings: true
  maxSectionsPerPage: 5
  
  # Series pagination
  series: "React Fundamentals"
  seriesOrder: 3
  totalInSeries: 8
  
  # Content list pagination (for index pages)
  itemsPerPage: 10
  showPageNumbers: true
  infiniteScroll: false
---

Draft Mode

Control content visibility and preview capabilities right from frontmatter.

Example

Draft Filtering in Build

Here's a real filtering function that handles drafts, scheduled posts, and expired content:

Example

Custom CSS and Classes

Need page-specific styles without touching global stylesheets? Frontmatter can handle that too.

yaml example

---
# Page-level CSS customization
style:
  # CSS class applied to page wrapper
  className: "api-docs dark-theme"
  
  # Custom CSS variables for this page
  variables:
    --accent-color: "#e63946"
    --content-max-width: "900px"
    --font-code: "JetBrains Mono"
  
  # Layout overrides
  fullWidth: true
  maxWidth: "1400px"
  contentPadding: "2rem"
  
  # Background
  backgroundColor: "#fafafa"
  backgroundImage: "/images/patterns/grid.svg"
  
  # Typography
  fontSize: "base"          # "sm", "base", "lg"
  lineHeight: "relaxed"     # "tight", "normal", "relaxed"
  
# Body class (useful for CSS targeting)
bodyClass: "page-api-auth"

# Custom stylesheet import
customCSS: "/styles/api-docs.css"
---

Applying Custom Styles

Example

Feature Flags Per Page

Turn interactive features on or off for individual pages. Great for A/B testing, progressive rollouts, or just disabling stuff that doesn't make sense on certain pages.

yaml example

---
features:
  # Interactive elements
  codePlayground: true       # Embedded code sandbox
  liveEditor: true           # Edit-in-place for code blocks
  copyButton: true           # Copy code button
  
  # UI components
  feedbackWidget: true       # "Was this helpful?" widget
  commentSection: false      # Reader comments
  shareButtons: true         # Social share buttons
  editOnGithub: true         # "Edit this page" link
  
  # Navigation
  breadcrumbs: true
  pageProgress: true         # Reading progress bar
  scrollToTop: true          # Scroll-to-top button
  
  # Experimental
  aiAssistant: false         # AI chat helper
  searchHighlight: true      # Highlight search terms
  readingMode: true          # Distraction-free toggle
  
  # Analytics
  trackScrollDepth: true
  trackTimeOnPage: true
  heatmapEnabled: false
  
  # Access control
  requireAuth: false
  premiumOnly: false
  membershipLevel: "free"    # "free", "pro", "enterprise"
---

Conditional Feature Rendering

A simple FeatureGate component that checks frontmatter before rendering:

Example

Complete Configuration Schema

Here's everything tied together in one Zod schema:

Example

Best Practices

Set sensible defaults — Most pages should work with zero configuration. Only require fields when you truly need per-page values.

Use layout inheritance — Define base layouts with default settings, then let frontmatter override specific things.

Keep feature flags boolean — Simple on/off. If you need complex conditional logic, put it in code, not YAML.

Document your options — Maintain a reference page listing all config fields, valid values, and what they do.

Validate at build time — Catch invalid layout names, bad order values, and unsupported feature flags before you deploy.

Group related fields — Use nested objects (sidebar.*, toc.*, nav.*) instead of cluttering the top level with dozens of flat keys.

Support gradual adoption — Let pages work with zero config. Authors add fields as they need customization, not before.

Show active config in dev mode — Build a dev-only panel that displays the current page's resolved configuration. Makes debugging layout issues way easier.

Page Configuration via Frontmatter

Frontmatter as Configuration

Layout Selection

Implementing Layout Selection

Sidebar Configuration

Building a Dynamic Sidebar

Docusaurus Sidebar Configuration

Navigation Order

Sequential Navigation Component

Table of Contents Settings

Framework Implementations

Draft Mode

Draft Filtering in Build

Custom CSS and Classes

Applying Custom Styles

Feature Flags Per Page

Conditional Feature Rendering

Complete Configuration Schema

Best Practices

Continue learning this concept

Page Configuration via Frontmatter

Frontmatter as Configuration

Layout Selection

Implementing Layout Selection

Sidebar Configuration

Building a Dynamic Sidebar

Docusaurus Sidebar Configuration

Navigation Order

Sequential Navigation Component

Table of Contents Settings

Framework Implementations

Draft Mode

Draft Filtering in Build

Custom CSS and Classes

Applying Custom Styles

Feature Flags Per Page

Conditional Feature Rendering

Complete Configuration Schema

Best Practices

Continue learning this concept