Async Mode

Introduction

By default, all Markdown and MDX files need to be pre-compiled first, the same constraint also applies on development server.

This may result in longer dev server start time for large docs sites, you can enable Async Mode on doc collections to improve this.

Setup

Install required dependencies.

npm install @fumadocs/mdx-remote shiki

Enable Async Mode.

import { defineDocs } from 'fumadocs-mdx/config';
 
export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    async: true,
  },
});

Usage

Async Mode allows on-demand compilation of Markdown and MDX content, by moving the compilation process from build time to Next.js runtime.

However, you need to invoke the load() async function to load and compile content.

For example:

import { loader } from 'fumadocs-core/source';
import { docs } from '@/.source';
 
export const source = loader({
  baseUrl: '/docs',
  source: docs.toFumadocsSource(),
});
 
// page.tsx
const page = source.getPage(['...']);
 
if (page) {
  // frontmatter properties are available
  console.log(page.data);
 
  // Markdown content requires await
  const { body: MdxContent, toc } = await page.data.load();
 
  console.log(toc);
 
  return (
    <MdxContent
      components={
        {
          // your MDX components
        }
      }
    />
  );
}

When using Async Mode, we highly recommend to use 3rd party services to implement search, which usually has a better capability to handle massive amount of content to index.

Constraints

It comes with some limitations on MDX features.

• No import/export allowed in MDX files, for MDX components, pass them from the components prop instead.
• Images must be referenced with URL (e.g. /images/test.png). Don't use file paths like ./image.png, you should locate your images in public folder, and reference them with URLs.