延迟加载

介绍

🌐 Introduction

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

🌐 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.

适用于 Next.js

目前 Turbopack 不支持懒加载打包，异步模式只能提升服务器性能。

动态模式

🌐 Dynamic Mode

动态模式通过与 MDX Remote 一起执行按需编译来工作。

🌐 Dynamic mode works by performing on-demand compilation with MDX Remote.

你需要安装额外的依赖：

🌐 You need to install extra dependencies:

npm i @fumadocs/mdx-remote shiki

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.

约束

动态模式在 MDX 功能上有一些限制。

🌐 Dynamic mode comes with some limitations on MDX features.

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

使用

🌐 Usage

page 对象仍然可以使用 frontmatter 属性，但你需要调用 load() 异步函数来加载已编译的内容（及其导出）。

🌐 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:

page.tsx

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

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.

介绍

异步模式

动态模式

使用

On this page