Lazy Loading

Introduction

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

This may result in longer dev server start times for large docs sites. You can enable Async or Dynamic mode on doc collections to improve this.

Async Mode

Async mode will generate collection outputs using async imports.

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

export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    async: true,
  },
});

Depending on your bundler, this may reduce compilation time significantly on development server.

Dynamic Mode

Dynamic mode works by performing on-demand compilation, then execute the output on runtime.

It is recommended to install & externalize shiki:

npm i shiki

Enable dynamic mode in collections like:

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

export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    dynamic: true,
  },
});

Then, follow Dynamic Entry to access the collection from dynamic entry instead.

Usage

Frontmatter properties are still available on page object, but you need to invoke the load() async function to load the compiled content (and its exports).

For example:

import { source } from '@/lib/source';
import { getMDXComponents } from '@/components/mdx';

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={getMDXComponents()} />;
}

When using Async or Dynamic mode, we highly recommend to use third-party services to implement search, which usually have better capability to handle massive amount of content to index.