Skip to main content
Co-authored by
Zopio Labszopio
Fuma NamaFumadocs
Fumadocs is a beautiful & powerful docs framework powered by Next.js, allowing advanced customisations.

​
1. Create a Fumadocs App

Fumadocs is similar to a set of libraries built on Next.js App Router, which works very differently from a hosted solution like Mintlify, or other frameworks/static site generator that takes complete control over your app. To begin, you can use a command to initialize a Fumadocs app quicky:
Terminal
pnpm create fumadocs-app
Here we assume you have enabled Fumadocs MDX, Tailwind CSS, and without a default ESLint config.

​
What is a Content Source?

The input/source of your content, it can be a CMS, or local data layers like Content Collections and Fumadocs MDX (the official content source). Fumadocs is designed carefully to allow a custom content source, there’s also examples for Sanity if you are interested.
lib/source.ts is where you organize code for content sources.

​
Update your Tailwind CSS

Start the app with pnpm dev. If some styles are missing, it could be due to your monorepo setup, you can change the content property in your Tailwind CSS config (tailwind.config.mjs) to ensure it works:
tailwind.config.mjs
export default {
  content: [
    // from
    './node_modules/fumadocs-ui/dist/**/*.js',
    // to
    '../../node_modules/fumadocs-ui/dist/**/*.js',

    './components/**/*.{ts,tsx}',
    // ...
  ],
};
You can either keep the Tailwind config file isolated to the docs, or merge it with your existing config from the tailwind-config package.

​
2. Migrate MDX Files

Fumadocs, same as Mintlify, utilize MDX for content files. You can move the .mdx files from your Mintlify app to content/docs directory.
Fumadocs requires a title frontmatter property.
The MDX syntax of Fumadocs is almost identical to Mintlify, despite from having different components and usage for code blocks. Visit Markdown for supported Markdown syntax.

​
Code Block

Code block titles are formatted with title="Title". 
```sh Name
pnpm i
```
Code highlighting is done with an inline comment. 
```ts {1}
console.log('Highlighted');
```
In Fumadocs, you can also highlight specific words.
Fumadocs
console.log('Highlighted'); // [!code word:Highlighted]

​
Code Groups

For code groups, you can use the Tabs component: 
<CodeGroup>

```ts Tab One
console.log('Hello, world!');
```

```ts Tab Two
console.log('Hello, world!');
```
</CodeGroup>
Fumadocs also has a built-in integration for TypeScript Twoslash, check it out in the Setup Guide.

​
Callout

Fumadocs uses a generic Callout component for callouts, as opposed to Mintlify’s specific ones. 
<Note>Hello World</Note>
<Warning>Hello World</Warning>
<Info>Hello World</Info>
<Tip>Hello World</Tip>
<Check>Hello World</Check>

​
Adding Components

To use components without import, add them to your MDX component.
app/docs/[[...slug]]/page.tsx
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
 
<MDX components={{ Tabs, Tab }} />;

​
3. Migrate mint.json File

Instead of a single file, you can configure Fumadocs using code. The sidebar items are generated from your file system, Fumadocs takes meta.json as the configurations of a folder. You don’t need to hardcode the sidebar config manually. For example, to customise the order of pages in content/docs/components folder, you can create a meta.json folder in the directory:
meta.json
{
  "title": "Components", // optional
  "pages": ["index", "apple"] // file names (without extension)
}
Fumadocs also support the rest operator (...) if you want to include the other pages.
meta.json
{ 
  "title": "Components", // optional
  "pages": ["index", "apple", "..."] // file names (without extension)
}
Visit the Pages Organization Guide for an overview of supported syntaxs.

​
Appearance

The overall theme can be customised using CSS variables and/or presets.

​
CSS variables

In your global CSS file:
global.css
:root {
  /* hsl values, like hsl(239 37% 50%) but without `hsl()` */
  --background: 239 37% 50%;

  /* Want a max width for docs layout? */
  --fd-layout-width: 1400px;
}

.dark {
  /* hsl values, like hsl(239 37% 50%) but without `hsl()` */
  --background: 239 37% 50%;
}

​
Tailwind Presets

In your Tailwind config, use the preset option.
tailwind.config.mjs
import { createPreset } from 'fumadocs-ui/tailwind-plugin';
 
/** @type {import('tailwindcss').Config} */
export default {
  presets: [
    createPreset({
      preset: 'ocean',
    }),
  ],
};
See all available presets.

​
Layout Styles

You can open app/layout.config.tsx, it contains the shared options for layouts. Fumadocs offer a default Docs Layout for documentation pages, and Home Layout for other pages. You can customise the layouts in layout.tsx. app/api/search/route.ts contains the Route Handler for search, it is powered by Orama by default. Navigation links are passed to layouts, you can also customise them in your Layout config.
app/layout.config.tsx
import { BookIcon } from 'lucide-react';
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  links: [
    {
      icon: <BookIcon />,
      text: 'Blog',
      url: '/blog',
    },
  ],
};
See all supported items.

​
Done

Now, you should be able to build and preview the docs. Visit Fumadocs for details and additional features.