Documentation

Write and organize product documentation with Fumadocs MDX.

The starter kit includes a Fumadocs documentation site at /docs. Its pages are local MDX files in content/docs, so the documentation stays versioned with the application code.

One documentation source

Both starter kit repositories use the same documentation structure. Do not create an ORM-specific folder inside content/docs.

How documentation is connected

File	Responsibility
`content/docs/*.mdx`	Documentation content and page metadata
`content/docs/meta.json`	Sidebar groups, labels and page order
`source.config.ts`	Declares `content/docs` as the Fumadocs MDX source
`lib/marketing/docs/source.ts`	Loads the content and assigns the `/docs` base URL
`app/docs/layout.tsx`	Configures the documentation layout and navigation tree
`app/docs/[[...slug]]/page.tsx`	Renders each page and generates its metadata

The kit already connects these files. You normally only need to edit content/docs when writing product documentation.

Add a page

Create the MDX file

Add a file directly under content/docs. Its path becomes the URL after /docs.

content/docs/getting-started.mdx

---
title: Getting started
description: Configure the application for local development.
icon: Rocket
---

## Prerequisites

Add your guide here.

This example is available at /docs/getting-started. The optional icon value must match an icon exported by Lucide React.

Add the page to the sidebar

Add the filename without .mdx to the pages array in content/docs/meta.json:

content/docs/meta.json

{
  "title": "Documentation",
  "root": true,
  "pages": ["index", "getting-started"]
}

Keep this array in the order you want readers to follow. Fumadocs also supports separators and external links in this file.

Preview the page

Start the application and open the new route:

npm run dev

Visit http://localhost:3000/docs/getting-started and check the page on both desktop and mobile.

Organize a section

For a larger topic, put its pages in a folder and add a meta.json inside that folder. The folder name becomes the URL segment.

content/docs/
├── meta.json
└── billing/
    ├── meta.json
    ├── overview.mdx
    └── webhooks.mdx

content/docs/billing/meta.json

{
  "title": "Billing",
  "pages": ["overview", "webhooks"]
}

The pages are then available at /docs/billing/overview and /docs/billing/webhooks. Add billing to the root content/docs/meta.json where that section should appear.

Use the included MDX components

The page renderer registers Fumadocs components including Callout, Cards, Tabs, Steps, Files and ImageZoom. You can use them directly in an MDX page without importing them.

content/docs/getting-started.mdx

<Callout
  type="warn"
  title="Before you continue"
>
  Copy `.env.example` to `.env` and provide the required values.
</Callout>

<Tabs items={['Local', 'Production']}>
  <Tab value="Local">Use your local service credentials.</Tab>
  <Tab value="Production">Use credentials from the production project.</Tab>
</Tabs>

Standard fenced code blocks support syntax highlighting. Add a filename attribute when the file location helps the reader.

Change the documentation UI

Edit app/docs/layout.tsx to change the documentation shell or sidebar behavior.
Edit lib/marketing/docs/layout.config.tsx to change shared layout options such as navigation links.
Edit app/docs/[[...slug]]/page.tsx to register another MDX component or change page rendering.
Edit lib/marketing/docs/source.ts only when changing how the content source is loaded.

Keep content changes in content/docs and layout changes in the application files above. This separation makes upgrades easier and keeps navigation generated from the same source as the pages.

Validate before publishing

Run the same checks used for application changes:

npm run typecheck
npm run lint
npm run build

Also open every new documentation route locally. A successful build confirms that Fumadocs can compile the MDX, while the browser check catches navigation, layout and readability problems.

For advanced navigation and MDX options, see the Fumadocs documentation.