Routing

LitMDX uses file-based routing. The path of each .mdx file inside docs/ becomes its URL route automatically — no configuration required.

Route mapping

index.mdx files always resolve to the parent directory route. docs/guide/index.mdx and docs/guide.mdx both map to /guide.

Multi-section mode

When docs/ contains a subdirectory named home/, LitMDX activates multi-section mode. Routes inside home/ are promoted to the root:

docs/
├── home/
│   ├── index.mdx          → /
│   └── about.mdx          → /about
├── guide/
│   └── getting-started.mdx → /guide/getting-started
└── reference/
    └── index.mdx          → /reference

This lets you organize a large site into independent sections, each with its own sidebar.

Section sidebars

In multi-section mode, the sidebar shows only the routes belonging to the active section. Navigating to /guide/... shows only guide pages; navigating to /reference/... shows only reference pages.

Navigation

LitMDX uses client-side navigation (History API). There are no full page reloads between routes. The URL changes and the new page component is lazy-loaded on demand.

Links in MDX that use standard Markdown syntax ([text](path)) work as regular anchor tags. Use the nav config for the top navigation bar, and use internal routes (to: '/path') for client-side navigation:

nav: [
  { label: 'Guide',     to: '/guide' },        // client-side
  { label: 'GitHub',    href: 'https://...' },  // external, new tab
]

404 handling

When a route is not found, LitMDX renders a built-in 404 page. After litmdx build, all known routes are emitted as static HTML files such as dist/guide/index.html, so direct URL access works without waiting for client-side routing.

For truly unknown paths, LitMDX still relies on the SPA runtime to show the built-in 404 page. If you want unknown URLs to resolve to the app instead of the host's own 404 page, keep a single-page-app fallback rule on your static host.

/* /index.html 200

{ "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }