fumadocs

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 <framework>", "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.