Getting Started

Introduction

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.

Getting Started

Install Dependencies

npm install fumadocs-mdx @types/mdx

Configuration

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.

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 {
    ...defaultComponents,
    ...components,
  };
}

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),
});

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.

FAQ

Built-in Properties

These properties are exported from MDX files by default.

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.