fumadocs

name

fumadocs

description

Authoritative guide for the Fumadocs documentation framework — Core (headless), MDX (content loader), and UI (Tailwind v4 layouts and components). Use when scaffolding a Fumadocs project, editing source.config.ts, wiring loader() and meta.json conventions, picking a search adapter, composing DocsLayout/Notebook/Flux/Home layouts, customising the MDX component map, integrating OpenAPI specs, generating OG images, exporting PDF/EPUB/RSS, or configuring i18n across Next.js, React Router, TanStack Start, and Waku adapters. Surfaces canonical install snippets per adapter, decision tables for entry modes and content sources, and the most common pitfalls (Tailwind v3 silent failure, ESM-only config, .source/ generation, layout/page import mismatch, slug collisions, edge runtime ban). Don't use for generic MDX/Markdown questions outside Fumadocs, for unrelated React framework setup, or for projects that don't use fumadocs-core/fumadocs-mdx/fumadocs-ui.

Fumadocs

Fumadocs is a docs framework for React: it sits inside Next.js / React Router / TanStack Start / Waku and combines three independently usable packages.

Package	Role	Skip when
fumadocs-core	Headless engine: loader(), page tree, MDX plugins, search adapters, i18n primitives	never (always required)
fumadocs-mdx	Content source: compiles content/**/*.mdx + meta.json into typed .source/ collections	replaced by @fumadocs/local-md, @fumadocs/mdx-remote, or a custom source
fumadocs-ui	Opinionated theme: RootProvider, layouts, MDX defaults, search dialog (Tailwind v4)	building a fully bespoke UI on top of fumadocs-core

Server-first via React Server Components. Static export is opt-in. Edge runtime is unsupported.

Procedures

Step 1: Identify the task class

Map the user's request to one of these classes, then load the matching reference:

Class	Trigger phrases	Reference
Bootstrap a project	"scaffold", "set up Fumadocs", "install in ", "create-fumadocs-app"	references/01-install-and-setup.md
Routing / file conventions	meta.json, pages directives, slug rules, root folders, page tree	references/02-source-and-page-tree.md
MDX configuration	source.config.ts, defineDocs, defineCollections, async / dynamic mode, plugin order, typegen	references/03-mdx-pipeline.md
UI layouts / components / MDX wiring	DocsLayout/Notebook/Flux/Home, RootProvider, mdx-components.tsx, theming, MDX overrides	references/04-ui-layouts-and-components.md
Search / i18n	adapter selection, search dialog, locale routing, middleware	references/05-search-and-i18n.md
OpenAPI / OG / AI / content sources / guides	<APIPage>, generateFiles, OG image route, llms.txt, Ask AI, local-md, mdx-remote, PDF/EPUB/RSS	references/06-integrations.md
Debugging an existing setup	"broken", "blank sidebar", "404", "build fails", "weird hydration"	references/07-pitfalls.md

If the task spans multiple classes, load the references in the order shown above (setup → tree → MDX → UI → search/i18n → integrations).

Step 2: Confirm the package surface in use

Before recommending code, check which Fumadocs surface the project actually uses. Read these files (paths are conventional, not absolute):

1. package.json — confirm fumadocs-core, fumadocs-mdx, fumadocs-ui versions and which adapter is installed (next, @react-router/..., @tanstack/react-start, waku).
2. source.config.ts (Fumadocs MDX) or lib/source.ts (low-level loader()) — determines whether the project uses the bundler-backed MDX path or a runtime source (local-md, mdx-remote, custom).
3. The catch-all docs route — Next: app/<segment>/[[...slug]]/page.tsx; React Router: routes/docs/$.tsx or route('docs/*', ...); TanStack Start: routes/docs/$.tsx; Waku: pages/docs/[...slugs].tsx.
4. The root layout / provider import path — fumadocs-ui/provider/{next,react-router,tanstack,waku} MUST match the framework.
5. Tailwind entry — confirm Tailwind 4, the colour preset (fumadocs-ui/css/<theme>.css) and fumadocs-ui/css/preset.css imports.

If any of these contradicts the user's request, surface the conflict before editing.

Step 3: Choose adapters and modes deterministically

Use these decision tables instead of guessing:

MDX entry mode (Fumadocs MDX → collections/{server,browser,dynamic})

Choose	When
server	RSC / SSR / SSG (default, fastest first paint)
browser	Client-routed apps (TanStack Start, React Router SPA mode) — only doc / docs collections
dynamic	Very large libraries (>500 MDX) where build time / memory dominates
direct import	One-off MDX as a page or React component (no loader() indirection)

Content source

Choose	When
Fumadocs MDX (default)	Bundler-backed, typegen, image optimization, full MDX import/export
@fumadocs/local-md	Runtime-only, Cloudflare Workers compat, no eval, no bundler step
@fumadocs/mdx-remote	Runtime compile from CMS / remote content (trusted input only)
custom (StaticSource / DynamicSource)	Hardcoded trees, generated content, multi-tenant per-permission sources

Search adapter

Choose	When
orama (default)	Self-hosted, free, typed schema, vector capable
flexsearch	Tiny / medium docs, zero infra, smaller bundle than Orama
algolia	Enterprise scale, polished relevance (free tier requires logo)
orama-cloud	Hosted Orama, scale without ops
mixedbread	Semantic / vector / natural-language queries
typesense	OSS scale + faceting (community adapter)
trieve	RAG / hybrid retrieval (community-maintained)
custom	Hand-roll a /static.json route from source.getPages().structuredData

Layout

Choose	When
fumadocs-ui/layouts/docs	Classic docs site with persistent sidebar
fumadocs-ui/layouts/notebook	Denser, app-shell feel; supports top-tab navigation
fumadocs-ui/layouts/flux	Aggressively minimal (client-only — no unserialisable RSC props)
fumadocs-ui/layouts/home	Marketing / landing pages that share docs chrome

When the layout changes, the per-doc page import must follow (fumadocs-ui/layouts/<layout>/page → DocsPage, DocsTitle, DocsBody).

Step 4: Wire source.config.ts, loader(), and mdx-components.tsx

These three files form the spine of any Fumadocs setup. Use the canonical templates (read first, then adapt):

1. Read assets/source-config-template.ts for the defineDocs + defineCollections + defineConfig shape, schema extension via pageSchema / metaSchema, and the recommended tsconfig alias collections/* → .source/*.
2. Read assets/source-template.ts for the loader({ source, baseUrl, url, slugs, icon, i18n, plugins }) shape and the typical lib/source.ts exports.
3. Read assets/mdx-components-template.tsx for the getMDXComponents pattern, the pre ref-strip workaround, and createRelativeLink(source, page) wiring.

If the project already has these files, prefer surgical edits over rewrites — collection-level mdxOptions wipes globals, so use applyMdxPreset(...) to keep the docs preset.

Step 5: Validate before claiming done

For any change that touches MDX content, source config, page conventions, or layouts:

1. Trigger source generation via the project's existing dev script (Fumadocs MDX writes .source/ on dev/build; otherwise run npx fumadocs-mdx).
2. Run the framework's typecheck — .source/index.d.ts must compile cleanly. A .source/ not regenerated is the most common cause of "module not found" or "property does not exist" errors.
3. Render the affected route(s) — sidebar items match meta.json.pages, breadcrumbs/TOC populate, search dialog opens with ⌘K. Layout-level breakage is silent until rendered.
4. If i18n is configured, check the locale variants: defaultLanguage and at least one non-default. hideLocale: 'always' cookies break static caches — surface this if applicable.

Step 6: Use the pitfall catalog before debugging

When the user reports a bug, read references/07-pitfalls.md first — most failures are catalogued. The five most common:

1. Tailwind v3 silently breaks the theme — only Tailwind v4 + fumadocs-ui/css/preset.css is supported.
2. next.config.js (CJS) won't load fumadocs-mdx — the loader is ESM only; rename to next.config.mjs or enable Native Node TS resolver.
3. Layout/page import mismatch — Notebook/Flux require DocsPage from layouts/<layout>/page; defaulting to layouts/docs/page produces broken TOC/footer.
4. Duplicated URLs in the page tree — Fumadocs locates the active node by pathname only; any duplicate corrupts active-link detection.
5. Provider subpath mismatch — fumadocs-ui/provider/<framework> must match the adapter or RootProvider silently no-ops (search, theme switch, i18n all stop working).

Error Handling

• The user mentions a feature that isn't visible in package.json. Ask which adapter they're on before generating code; never assume Next.js because the docs default to it.
• The framework adapter is older than Fumadocs 16. Earlier majors used different provider paths and Tailwind 3 — verify the version and read references/07-pitfalls.md for migration notes before editing.
• source.config.ts and a runtime source (local-md / mdx-remote) coexist. Two competing loaders is not a supported state — read references/06-integrations.md#content-sources and pick one before changing code.
• Static export is required. Confirm whether search needs to be static (Orama static, FlexSearch static, or hosted/cloud) — server-fetch search will not work statically. See references/05-search-and-i18n.md#static-export.
• .source/ does not exist or is stale. Trigger source generation before any typecheck; missing entries cause cryptic "module not found" / "is not exported" errors.
• OpenAPI is requested. openapiSource() mutates page.type to 'openapi' — every consumer (getLLMText, page renderer, search index, OG image, RSS) must branch on it. Read references/06-integrations.md#openapi before wiring.