MDX Options

Customising MDX Processor

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

You can customise it on Global Config or Collection Config.

Extended MDX Options

Fumadocs MDX will apply some default MDX options, to make features like syntax highlighting work out of the box.

To allow overriding the defaults, Fumadocs MDX's mdxOptions option accepts Extended MDX Options on top of ProcessorOptions. You can see the additional options below:

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 { defineConfig } from 'fumadocs-mdx/config';
import { myPlugin } from './remark-plugin';

export default defineConfig({
  mdxOptions: {
    remarkPlugins: [myPlugin],
    // You can also pass a function to control the order of remark plugins.
    remarkPlugins: (v) => [myPlugin, ...v],
  },
});

import { defineCollections, getDefaultMDXOptions } from 'fumadocs-mdx/config';
import { myPlugin } from './remark-plugin';

export const blog = defineCollections({
  type: 'doc',
  mdxOptions: getDefaultMDXOptions({
    remarkPlugins: [myPlugin],
    // You can also pass a function to control the order of remark plugins.
    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 { defineConfig } from 'fumadocs-mdx/config';
import { myPlugin } from './rehype-plugin';

export default defineConfig({
  mdxOptions: {
    rehypePlugins: (v) => [myPlugin, ...v],
  },
});

import { defineCollections, getDefaultMDXOptions } from 'fumadocs-mdx/config';
import { myPlugin } from './rehype-plugin';

export const blog = defineCollections({
  type: 'doc',
  mdxOptions: getDefaultMDXOptions({
    rehypePlugins: (v) => [myPlugin, ...v],
  }),
});

Customise Built-in Plugins

Customise the options of built-in plugins like:

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

export default defineConfig({
  mdxOptions: {
    rehypeCodeOptions: {
      // options
    },
    remarkImageOptions: {
      // options
    },
    remarkHeadingOptions: {
      // options
    },
  },
});

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

export const blog = defineCollections({
  type: 'doc',
  mdxOptions: getDefaultMDXOptions({
    rehypeCodeOptions: {
      // options
    },
    remarkImageOptions: {
      // options
    },
    remarkHeadingOptions: {
      // 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 ESM exports, so that you can access these properties when importing the MDX file.

You can define additional properties to be exported.

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

export default defineConfig({
  mdxOptions: {
    valueToExport: ['dataName'],
  },
});

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

export const blog = defineCollections({
  type: 'doc',
  mdxOptions: 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)