Frontmatter

Each .mdx file can include a YAML block at the top called frontmatter to customize sidebar behavior and site metadata.

Syntax

---
title: My page
description: Description for SEO and tooltip text
image: https://example.com/og-image.png
noindex: false
schema_type: TechArticle
sidebar_position: 2
sidebar_label: Short label
---

# Content goes here

Available fields

Order pages in the sidebar

Use sidebar_position to control ordering. Lower values appear first:

---
title: Introduction
sidebar_position: 1
---

---
title: Installation
sidebar_position: 2
---

---
title: Configuration
sidebar_position: 3
---

Order groups in the sidebar

The sidebar_position in a folder's index.mdx controls where the group itself appears among its siblings. This applies at both nesting levels:

features/
├── index.mdx          ← sidebar_position: 2  (Features group is 2nd at the top level)
├── configuration.mdx
└── customization/
    └── index.mdx      ← sidebar_position: 4  (Customization sub-group is 4th inside Features)

---
title: Features
sidebar_position: 2    # position of the Features group in the top-level sidebar
---

---
title: Customization
sidebar_position: 4    # position of the Customization sub-group inside Features
---

The sidebar_position of a group's index.mdx controls the group's position in its parent — not the index page's position within the group. The index page is always pinned as the first item inside its own group, regardless of the value set.

Per-page SEO

Frontmatter title and description are reflected dynamically in <title> and og:description on every route change — no build step required:

---
title: API Reference
description: Complete API reference for the Acme SDK
---

The resulting <title> will be: API Reference | Acme SDK.

Per-page Open Graph image

Use image to override the global openGraph.image for a specific page. The value must be an absolute URL:

---
title: Changelog
description: What changed in each release
image: https://example.com/og-changelog.png
---

During litmdx build, this injects <meta property="og:image" content="..." /> into the prerendered HTML for that route only.

Prevent indexing

Use noindex to exclude a page from search engine results. Useful for internal drafts, changelogs, or pages not ready for public visibility:

---
title: Internal Draft
noindex: true
---

This injects <meta name="robots" content="noindex"> into the prerendered HTML for that route.

Structured data (Schema.org)

LitMDX auto-generates a JSON-LD block for every page that has a title. The block is emitted as <script type="application/ld+json"> at build time (SSG) and kept in sync on SPA navigation.

Default auto-generated output (requires only title):

{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "<title>",
  "description": "<description>"
}

Changing the @type with schema_type

Use schema_type to change the Schema.org type without writing the full object:

---
title: LitMDX — Open-Source MDX Documentation Framework
schema_type: WebPage
---

Common @type values for documentation sites:

Use a different sidebar label

When the page title is long, use sidebar_label to show a shorter version in the sidebar without affecting the <title>:

---
title: Installing LitMDX in an Existing Project
sidebar_label: Installation
sidebar_position: 1
---

Pages without sidebar_position are sorted alphabetically at the end.

Sidebar label priority: title → sidebar_label → formatted file name

Update the browser title

LitMDX uses the frontmatter title to update document.title on each navigation:

My page | Site name

If there is no title in frontmatter, LitMDX shows only the site title defined in litmdx.config.ts.

Collapse a sidebar group by default

Place sidebar_collapsed: true in the index.mdx of a folder to make its sidebar group start collapsed. The group still opens automatically when the user navigates to a page inside it.

---
title: Advanced
sidebar_position: 5
sidebar_collapsed: true
---

Hide a page from the sidebar

Set sidebar_hidden: true to remove a page from the sidebar tree entirely. The page still exists and is accessible by its direct URL — it simply has no sidebar entry.

---
title: Internal reference
sidebar_hidden: true
---

Groups where all child pages are hidden are removed from the sidebar automatically.

Complete example

---
title: API Reference
description: Complete documentation for LitMDX public APIs
image: https://example.com/og-api.png
noindex: false
# schema_type defaults to TechArticle — no need to set it for most pages
sidebar_position: 10
sidebar_label: API
sidebar_collapsed: false
sidebar_hidden: false
---

# API Reference

...