Install Fumadocs Manually

Read the Quick Start guide first for basic concept.

Start from a Blank App

Begin with a fresh Next.js project created through create-next-app, then install the packages Fumadocs needs.

fumadocs-ui fumadocs-core

Choose a Content Source

Fumadocs works with multiple content sources, so pick the one that matches your workflow.

Officially supported options include:

Before moving on, make sure the source library itself is configured correctly. In this guide, the source adapter is imported from @/lib/source.ts.

Set Up the Root Layout

Wrap the entire app with Root Provider, then give body the minimum layout styling it needs.

import { RootProvider } from 'fumadocs-ui/provider';
import type { ReactNode } from 'react';

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body
        // you can use Tailwind CSS too
        style={{
          display: 'flex',
          flexDirection: 'column',
          minHeight: '100vh',
        }}
      >
        <RootProvider>{children}</RootProvider>
      </body>
    </html>
  );
}

Add Styles

Install Tailwind CSS v4 in your Next.js app, then place the following imports in global.css.

Tailwind CSS

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';

/* path of `fumadocs-ui` relative to the CSS file */
@source '../node_modules/fumadocs-ui/dist/**/*.js';

It doesn't come with a default font, you may choose one from next/font.

Configure Shared Layout Options

Create app/layout.config.tsx to hold the options reused by your layouts.

{
  "file": "../../examples/next-mdx/app/layout.config.tsx",
  "codeblock": {
    "meta": "title=\"app/layout.config.tsx\""
  }
}

Next, create /app/docs and give the docs section its own layout.

{
  "file": "../../examples/next-mdx/app/docs/layout.tsx",
  "codeblock": {
    "meta": "title=\"app/docs/layout.tsx\""
  }
}

pageTree refers to Page Tree, it should be provided by your content source.

Add the Docs Page Route

Create the catch-all route at /app/docs/[[...slug]] to serve documentation pages.

Inside that page, render content with the Page component. The exact implementation depends on the content source you chose, and you should also configure generateStaticParams for static rendering plus generateMetadata for metadata.

{
  "file": "../../examples/next-mdx/app/docs/[[...slug]]/page.tsx",
  "codeblock": {
    "meta": "title=\"app/docs/[[...slug]]/page.tsx\" tab=\"Fumadocs MDX\""
  }
}

{
  "file": "../../examples/content-collections/app/docs/[[...slug]]/page.tsx",
  "codeblock": {
    "meta": "title=\"app/docs/[[...slug]]/page.tsx\" tab=\"Content Collections\""
  }
}

Enable Search

You can use the built-in document search powered by Orama.

{
  "file": "../../examples/next-mdx/app/api/search/route.ts",
  "codeblock": {
    "meta": "title=\"app/api/search/route.ts\" tab=\"Fumadocs MDX\""
  }
}

{
  "file": "../../examples/content-collections/app/api/search/route.ts",
  "codeblock": {
    "meta": "title=\"app/api/search/route.ts\" tab=\"Content Collections\""
  }
}

Finish Up

At this point you can run the dev server and begin writing MDX files.

content/docs/index.mdx

---
title: Hello World
---

## Introduction

I love Anime.

Further Customization

For other pages on your site, you can use Home Layout, which already includes a navbar and theme toggle.

Deployment

The setup should deploy out of the box to Vercel and Netlify.

Docker Deployment

If you plan to ship a Docker image with Fumadocs MDX configured, remember to copy source.config.ts into the Docker WORKDIR. The snippet below comes from the official Next.js Dockerfile Example:

Dockerfile

WORKDIR /app

# Install dependencies based on the preferred package manager
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* source.config.ts ./

That way, Fumadocs MDX can still read the configuration file during the build.

Read the Quick Start guide first for basic concept.

Start from a Blank App

Begin with a fresh Next.js project created through create-next-app, then install the packages Fumadocs needs.

fumadocs-ui fumadocs-core

Choose a Content Source

Fumadocs works with multiple content sources, so pick the one that matches your workflow.

Officially supported options include:

Before moving on, make sure the source library itself is configured correctly. In this guide, the source adapter is imported from @/lib/source.ts.

Set Up the Root Layout

Wrap the entire app with Root Provider, then give body the minimum layout styling it needs.

import { RootProvider } from 'fumadocs-ui/provider';
import type { ReactNode } from 'react';

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body
        // you can use Tailwind CSS too
        style={{
          display: 'flex',
          flexDirection: 'column',
          minHeight: '100vh',
        }}
      >
        <RootProvider>{children}</RootProvider>
      </body>
    </html>
  );
}

Add Styles

Install Tailwind CSS v4 in your Next.js app, then place the following imports in global.css.

Tailwind CSS

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';

/* path of `fumadocs-ui` relative to the CSS file */
@source '../node_modules/fumadocs-ui/dist/**/*.js';

It doesn't come with a default font, you may choose one from next/font.

Configure Shared Layout Options

Create app/layout.config.tsx to hold the options reused by your layouts.

{
  "file": "../../examples/next-mdx/app/layout.config.tsx",
  "codeblock": {
    "meta": "title=\"app/layout.config.tsx\""
  }
}

Next, create /app/docs and give the docs section its own layout.

{
  "file": "../../examples/next-mdx/app/docs/layout.tsx",
  "codeblock": {
    "meta": "title=\"app/docs/layout.tsx\""
  }
}

pageTree refers to Page Tree, it should be provided by your content source.

Add the Docs Page Route

Create the catch-all route at /app/docs/[[...slug]] to serve documentation pages.

{
  "file": "../../examples/next-mdx/app/docs/[[...slug]]/page.tsx",
  "codeblock": {
    "meta": "title=\"app/docs/[[...slug]]/page.tsx\" tab=\"Fumadocs MDX\""
  }
}

{
  "file": "../../examples/content-collections/app/docs/[[...slug]]/page.tsx",
  "codeblock": {
    "meta": "title=\"app/docs/[[...slug]]/page.tsx\" tab=\"Content Collections\""
  }
}

Enable Search

You can use the built-in document search powered by Orama.

{
  "file": "../../examples/next-mdx/app/api/search/route.ts",
  "codeblock": {
    "meta": "title=\"app/api/search/route.ts\" tab=\"Fumadocs MDX\""
  }
}

{
  "file": "../../examples/content-collections/app/api/search/route.ts",
  "codeblock": {
    "meta": "title=\"app/api/search/route.ts\" tab=\"Content Collections\""
  }
}

Finish Up

At this point you can run the dev server and begin writing MDX files.

content/docs/index.mdx

---
title: Hello World
---

## Introduction

I love Anime.

WORKDIR /app

# Install dependencies based on the preferred package manager
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* source.config.ts ./

That way, Fumadocs MDX can still read the configuration file during the build.

Start from a Blank App

Choose a Content Source

Set Up the Root Layout

Add Styles

Configure Shared Layout Options

Add the Docs Page Route

Enable Search

Finish Up

Further Customization

Deployment

Docker Deployment

Author

Categories

More Posts

Orelune Tarot Series: The Suit of Cups - Feeling, Intuition, and Emotional Flow

Orelune Tarot Series: The Star - Hope, Healing & Quiet Renewal

Orelune Tarot Series: The Suit of Wands - Fire, Drive, and Creative Momentum

Newsletter

Install Fumadocs Manually

Start from a Blank App

Choose a Content Source

Set Up the Root Layout

Add Styles

Configure Shared Layout Options

Add the Docs Page Route

Enable Search

Finish Up

Further Customization

Deployment

Docker Deployment

Author

Categories

More Posts

Orelune Tarot Series: The Suit of Cups - Feeling, Intuition, and Emotional Flow

Orelune Tarot Series: The Star - Hope, Healing & Quiet Renewal

Orelune Tarot Series: The Suit of Wands - Fire, Drive, and Creative Momentum

Newsletter