Getting Started

Learn how to use Fumadocs MDX in your documentation


fumadocs-mdx is the official content source of Fumadocs. It parses frontmatter and is bundled with many MDX plugins for building a good documentation site.

This package must be used with Fumadocs

Getting Started

Install Dependencies

npm install fumadocs-mdx @types/mdx


Add the plugin to your next.config.mjs file.

import createMDX from 'fumadocs-mdx/config';
const withMDX = createMDX();
/** @type {import('next').NextConfig} */
const config = {
  reactStrictMode: true,
export default withMDX(config);

It generates a .map.ts file once you start the dev server or start building the app. The map file contains all parsed files, you should add it to .gitignore.

ESM Only

The Next.js config must be a .mjs file since Fumadocs is ESM-only.

Define MDX Components

Create mdx-components.tsx in your root directory.

import type { MDXComponents } from 'mdx/types';
// Assume you're using Fumadocs UI
import defaultComponents from 'fumadocs-ui/mdx';
export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {

Resolve Files

To integrate with Fumadocs, create:

import { map } from '@/.map';
import { createMDXSource } from 'fumadocs-mdx';
import { loader } from 'fumadocs-core/source';
export const { getPage, getPages, pageTree } = loader({
  baseUrl: '/docs',
  rootDir: 'docs',
  source: createMDXSource(map),

For more customisation options, check Source API.

Start Server

next dev

A .map.ts file should be created. You can log and see if it is loaded correctly.

See Pages Conventions to learn how to organize your pages.


Built-in Properties

These properties are exported from MDX files by default.

tocTable of Contents
structuredDataStructured Data, useful for implementing search

MDX Plugins

You can customise the options passed to the MDX processor.

import createMDX from 'fumadocs-mdx/config';
import rehypeKatex from 'rehype-katex';
import remarkMath from 'remark-math';
const withMDX = createMDX({
  mdxOptions: {
    remarkPlugins: [remarkMath],
    // When order matters
    rehypePlugins: (v) => [rehypeKatex, ...v],

See Configuration to learn more.

What is the .map file?

The .map file is generated by our Webpack plugin in build time. It includes the information of files under your content directory, which can be access by your Next.js app to implement SSG and many other features.

Deep Dive

How does it work?

Fumadocs MDX is a webpack plugin over Next.js to support reading/importing a MDX file by its name. Because Next.js could only optimize static imports, it first generates a map file that imports all supported files under the root directory.

The imported files form an array called map in your .map.ts file, so that your Next.js app can access them without manually importing all of them.

Last updated on

On this page

Edit on Github