Introduction

Fumadocs MDX is the official content source of Fumadocs.

It provides the tool for Next.js to transform content into type-safe data, similar to Content Collections. This library made for Next.js, you can use it to handle blog and other contents.

Getting Started

Setup Fumadocs MDX for your Next.js application.

npm install fumadocs-mdx @types/mdx

pnpm add fumadocs-mdx @types/mdx

yarn add fumadocs-mdx @types/mdx

bun add fumadocs-mdx @types/mdx

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

import { createMDX } from 'fumadocs-mdx/next';

const withMDX = createMDX();

/** @type {import('next').NextConfig} */
const config = {
  reactStrictMode: true,
};

export default withMDX(config);

Defining Collections

Collection refers to a collection containing a certain type of files, you can define collections by creating a source.config.ts file.

Fumadocs MDX transforms collections into arrays of type-safe data, accessible in your app, available collections:

import { defineCollections } from 'fumadocs-mdx/config';

export const test = defineCollections({
  type: 'doc',
  dir: 'content/docs',
});

import { defineCollections } from 'fumadocs-mdx/config';

export const test = defineCollections({
  type: 'meta',
  dir: 'content/docs',
});

import { defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    // options for `doc` collection
  },
  meta: {
    // options for `meta` collection
  },
});

For example, a doc collection will transform the .md and .mdx files:

Output Folder

A .source folder is generated in root directory when you run next dev or next build, it contains all output data and types, you should add it to .gitignore.

The fumadocs-mdx command also generates types for .source folder, add it as a post install script to ensure types are generated when initializing the project.

{
  "scripts": {
    "postinstall": "fumadocs-mdx"
  }
}

Accessing Collections

Collection Output is the generated data of a collection, it can have a different type/shape depending on the collection type and schema.

You can access the collection output from .source folder with its original name:

import { defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    // options for `doc` collection
  },
  meta: {
    // options for `meta` collection
  },
});

import { docs } from '@/.source';

console.log(docs);

Integrate with Fumadocs

Create a docs collection and use the toFumadocsSource() function of its output.

import { docs } from '@/.source';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  baseUrl: '/docs',
  source: docs.toFumadocsSource(),
});

Generally, you'll interact with the collection through loader().

import { source } from '@/lib/source';

const page = source.getPage(['slugs']);

if (page) {
  // access page data
  console.log(page.data);

  // frontmatter properties are also inside
  console.log(page.data.title);
}

To render the page, use page.data.body as a component.

import { getMDXComponents } from '@/mdx-components';

const MDX = page.data.body;

// set your MDX components with `components` prop
return <MDX components={getMDXComponents()} />;

FAQ

Built-in Properties

These properties are exported from MDX files by default.

Customise Frontmatter

Use the schema option to pass a validation schema to validate frontmatter and define its output properties.

MDX Plugins

For other customisation needs such as Syntax Highlighting, see MDX Options.