Configuration

Configuration File

Configure Fumadocs MDX by creating a source.config.ts file.

Global Options

Shared options of Fumadocs MDX.

import { defineConfig } from 'fumadocs-mdx/config';
 
export default defineConfig({
  // global options
});

MDX Options

Customise the default MDX options of all MDX files.

See Default MDX Options for more details.

Manifest

Enable the generateManifest option to generate a manifest file for production builds.

See Manifest to learn more.

Collections

Define a collection to parse a certain set of files.

import { defineCollections } from 'fumadocs-mdx/config';
import { z } from 'zod';
 
export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  schema: z.object({
    // allowed...
  }),
});

dir

Directories to scan input files.

Schema

The Zod schema to validate file data (frontmatter on doc type, content on meta type).

import { defineCollections } from 'fumadocs-mdx/config';
import { z } from 'zod';
 
export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  schema: z.object({
    name: z.string(),
  }),
});

You can add additional properties to the output. Note that the validation is done by build time, hence the output must be serializable.

You can also pass a function and receives the transform context.

import { defineCollections } from 'fumadocs-mdx/config';
import { z } from 'zod';
 
export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  schema: (ctx) => {
    return z.object({
      name: z.string(),
      testPath: z.string().default(ctx.path),
    });
  },
});

Type

The accepted type of collection.

MDX Options

You can also customise MDX options from collections. Notice that passing mdxOptions to collection overrides all defaults from global config.

import { defineCollections, getDefaultMDXOptions } from 'fumadocs-mdx/config';
 
export const blog = defineCollections({
  type: 'doc',
  mdxOptions: getDefaultMDXOptions({
    // mdx options
  }),
});

We use getDefaultMDXOptions to apply default MDX options, it accepts the Default MDX Options.

For full control over MDX options, you can pass MDX options without getDefaultMDXOptions, which means no defaults will be applied (except the ones from MDX.js).

Transform

A function to perform runtime transformation on collection entries.

See Transform.

Define Docs

You can use defineDocs to define the required collections to work with Fumadocs. It offers the same API as defineCollections.

import { defineDocs } from 'fumadocs-mdx/config';
 
export const { docs, meta } = defineDocs({
  docs: {
    // optional, you can pass options to each collection
  },
  meta: {
    // optional, you can pass options to each collection
  },
});

Extend schema

You can extend the default Zod schema of docs and meta.

import { frontmatterSchema, metaSchema, defineDocs } from 'fumadocs-mdx/config';
import { z } from 'zod';
 
export const { docs, meta } = defineDocs({
  docs: {
    schema: frontmatterSchema.extend({
      index: z.boolean().default(false),
    }),
  },
  meta: {
    schema: metaSchema.extend({
      // other props
    }),
  },
});

Default MDX Options

Fumadocs MDX uses the MDX Compiler to compile MDX files into JavaScript files.

Since some options should be applied by default, it exposes a getDefaultMDXOptions function that applies these defaults on the input MDX options.

To allow changing the default settings, it supports a different set of options.

Remark Plugins

These plugins are applied by default:

• Remark Image - Handle images
• Remark Heading - Extract table of contents
• Remark Structure - Generate search indexes
• Remark Exports - Exports the output generated by remark plugins above

You can add other remark plugins with:

import { getDefaultMDXOptions } from 'fumadocs-mdx/config';
import { myPlugin } from './remark-plugin';
 
getDefaultMDXOptions({
  remarkPlugins: [myPlugin],
});

You can also pass a function to control the order of remark plugins.

import { getDefaultMDXOptions } from 'fumadocs-mdx/config';
import { myPlugin } from './remark-plugin';
 
getDefaultMDXOptions({
  remarkPlugins: (v) => [myPlugin, ...v],
});

Rehype Plugins

These plugins are applied by default:

• Rehype Code - Syntax highlighting

Same as remark plugins, you can pass an array or a function to add other rehype plugins.

import { getDefaultMDXOptions } from 'fumadocs-mdx/config';
import { myPlugin } from './rehype-plugin';
 
getDefaultMDXOptions({
  rehypePlugins: (v) => [myPlugin, ...v],
});

Customise Built-in Plugins

Customise the options of built-in plugins.

import { getDefaultMDXOptions } from 'fumadocs-mdx/config';
 
getDefaultMDXOptions({
  rehypeCodeOptions: {
    // options
  },
});

Export Properties from vfile.data

Some remark plugins store their output in vfile.data (an compile-time memory) which cannot be accessed from your code. Fumadocs MDX applies a remark plugin that turns vfile.data properties into exports, so that you can access these properties when importing the MDX file.

You can define additional properties to be exported.

import { getDefaultMDXOptions } from 'fumadocs-mdx/config';
 
getDefaultMDXOptions({
  valueToExport: ['dataName'],
});

By default, it includes:

• toc for the Remark Heading plugin
• structuredData for the Remark Structure Plugin
• frontmatter for the frontmatter of MDX (using gray-matter)

Plugin Options

Fumadocs MDX offers loaders and a Fumadocs Source API adapter to integrate with Fumadocs. You can configure the plugin by passing options to createMDX in next.config.mjs.

Config Path

Customise the path of config file.

import { createMDX } from 'fumadocs-mdx/next';
 
const withMDX = createMDX({
  configPath: './my-config.ts',
});