Markdown & MDX

Content pages can be authored in Markdown (.md) or MDX (.mdx) — Markdown with embedded JSX components. Both compile to static HTML at build time.

Frontmatter

Each content page starts with YAML frontmatter:

--- # Content starts here

Key	Purpose
title	Page title (used in the sidebar and <title>)
order	Sort order within a directory (default 999)
sidebar	Sidebar section override, or [...] JSON for a fully custom sidebar
keywords	Explicit search keywords for the search index

Markdown features

The markdown renderer supports:

• GFM — tables, task lists, autolinks, strikethrough
• Heading anchors — every heading gets an id for deep-linking and TOC
• Admonitions

• Syntax highlighting — fenced code blocks are highlighted at build time:

export default function Hello() { return <h1>Hello, MDX!</h1>; }

• Math — optional KaTeX-style math (math: true in the markdown config).

MDX

MDX lets you embed JSX directly in your content. The docs plugin re-inserts JSX blocks back into the rendered HTML, so components can be used inline:

# A page with a component Here is a callout rendered from JSX: <div class="callout"> <strong>Heads up!</strong> You can mix Markdown and JSX in one file. </div>

MDX files can also import components:

Configuration

markdown: { gfm: true, headingAnchors: true, admonitions: true, codeHighlight: true, math: false, }

How it works

1. The markdown source is parsed with frontmatter extracted.
2. Markdown is rendered to HTML; JSX blocks are preserved as segments.
3. The docs plugin (or a .mdx page) re-inserts the JSX segments and compiles the result through the normal TSX pipeline.