Fumadocs

Layout

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.