Switch to Fumadocs

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:

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.

​

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:

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.

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

Code highlighting is done with an inline comment.

In Fumadocs, you can also highlight specific words.

console.log('Highlighted'); // [!code word:Highlighted]

​

Code Groups

For code groups, you can use the Tabs component:

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.

​

Adding Components

To use components without import, add them to your MDX component.

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.

​

Sidebar Items

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:

{
  "title": "Components", // optional
  "pages": ["index", "apple"] // file names (without extension)
}

Fumadocs also support the rest operator (...) if you want to include the other pages.

{ 
  "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:

: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.

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.

​

Search

app/api/search/route.ts contains the Route Handler for search, it is powered by Orama by default.

​

Navigation Links

Navigation links are passed to layouts, you can also customise them in your Layout config.

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.