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, toc } = await page.data.load();
 
  console.log(body, toc);
}

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.