异步模式

介绍

默认情况下，所有 Markdown 和 MDX 文件都需要先进行预编译。开发服务器也适用相同的限制。

对于大型文档站点，这可能会导致开发服务器启动时间更长。您可以在文档集合上启用异步模式来改善这一点。

设置

启用异步模式。

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

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

Next.js

Turbopack 目前不支持懒加载打包，异步模式通过使用 MDX Remote 进行按需编译来实现。

您需要安装额外的依赖：

npm i @fumadocs/mdx-remote shiki

限制

异步模式对 Next.js 的 MDX 功能有一些限制。

MDX 文件中不允许导入/导出。 对于 MDX 组件，请通过 components prop 传递它们。
图像必须使用 URL 引用（例如 /images/test.png）。 不要使用文件路径，如 ./image.png。您应该将图像放置在 public 文件夹中，并使用 URL 引用它们。

Vite

Vite 原生支持懒加载打包，启用后您只需更新 loader() 即可。

lib/source.ts

import { loader } from 'fumadocs-core/source';
import { docs, create } from '@/.source';

export const source = loader({
  baseUrl: '/docs',
  source: await create.sourceAsync(docs.doc, docs.meta),
  source: await create.sourceLazy(docs.doc, docs.meta),
});

使用

Frontmatter 属性仍然在 page 对象上可用，但您需要调用 load() 异步函数来加载编译后的内容（及其导出）。

例如：

page.tsx

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

const page = source.getPage(['...']);

if (page) {
  // frontmatter 属性可用
  console.log(page.data);

  // Markdown 内容需要 await
  const { body: MdxContent, toc } = await page.data.load();

  console.log(toc);

  return <MdxContent components={getMDXComponents()} />;
}

使用异步模式时，我们强烈推荐使用第三方服务来实现搜索，这些服务通常具有更好的处理大量内容索引的能力。

介绍

设置

Next.js

Vite

使用

On this page