Fumadocs MDX v10 摘要 | Fumadocs 中文文档

特性

通过 source.config.ts 提供更多自定义选项，这是您内容的新配置文件。
引入了 collections（集合）。
支持 Turbopack。
支持构建时数据验证。

从 v9 迁移

重构导入

重构 next.config 中的导入。

From（从）：

import createMDX from 'fumadocs-mdx/config';

const withMDX = createMDX();

/** @type {import('next').NextConfig} */
const config = {
  reactStrictMode: true,
};

export default withMDX(config);

To（到）：

import { createMDX } from 'fumadocs-mdx/next';

const withMDX = createMDX();

/** @type {import('next').NextConfig} */
const config = {
  reactStrictMode: true,
};

export default withMDX(config);

移除 `mdx-components.tsx`

mdx-components.tsx 不再使用。现在仅允许从 MDX 主体的 components prop 传递 MDX 组件。

import defaultMdxComponents from 'fumadocs-ui/mdx';

const MDX = page.data.body;

// 使用 `components` prop 设置您的 MDX 组件
<MDX components={{ ...defaultMdxComponents }} />;

这鼓励显式导入 MDX 组件。

以前，mdx-components.tsx 通过向每个编译的 Markdown/MDX 文件注入导入来工作。这在某种程度上是不必要的，因为您可以始终显式导入组件，或者从 MDX 主体的 components prop 替换默认 HTML 标签，如 img。

定义集合

集合现在在源配置文件 (source.config.ts) 中引入。它指的是文件/内容集合，例如 Markdown 文件或 JSON/YAML 文件。

每个集合都有自己的配置，您可以使用自定义的 Zod 架构来验证其数据，或者为内容集合定义集合级别的 MDX 选项。

您可以创建一个源配置文件，并添加以下内容：

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

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

defineDocs 声明了两个集合，一个是 doc 类型，用于扫描内容文件（例如 md/mdx），另一个是 meta 类型，用于扫描元数据文件（例如 json）。

现在，您可以使用 fumadocs-mdx 命令生成类型，建议将其设置为 postinstall 脚本。

package.json

{
  "scripts": {
    "postinstall": "fumadocs-mdx"
  }
}

启动开发服务器时，将生成一个 .source 文件夹，它包含所有解析的集合/文件。您可以将它添加到 .gitignore，它将替换旧的 .map 文件。

要访问集合，请从文件夹中导入它们，使用 source.config.ts 中的原始名称。

import { docs, meta } from '@/.source';

现在要将其与 Fumadocs 框架集成，请将您的 source.ts 从以下更改：

import { map } from '@/.map';
import { createMDXSource } from 'fumadocs-mdx';
import { loader } from 'fumadocs-core/source';

export const { getPage, getPages, pageTree } = loader({
  baseUrl: '/docs',
  rootDir: 'docs',
  source: createMDXSource(map),
});

到：

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

export const source = loader({
  baseUrl: '/docs',
  source: createMDXSource(docs, meta),
});

我们现在推荐直接将 loader 的输出导出为单个变量。
schema 选项不再在 source.ts 中定义，它由 source.config.ts 处理。
它接受两个集合：docs（内容）和 meta（meta.json）。如果未使用，您可以将 meta 留为空数组，这样您可以只为 docs 定义一个集合。

`page.data`

在使用 loader 时，您不再需要 data.frontmatter 来访问 frontmatter 数据。它已合并到 page.data 对象中。

page.data.frontmatter.title;
page.data.title;

MDX 选项

不再将它们传递到 next.config 文件，而是定义 source.config.ts 中的全局配置：

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

export default defineConfig({
  mdxOptions: {
    // 这里！
  },
});

集合架构

集合的 schema 选项允许您自定义验证架构，它接受 Zod 类型。

对于 defineDocs，请参阅 schema。

多种类型

与以前相同，您可以为不同类型（例如文档和博客）多次调用 loader。

import { createMDXSource } from 'fumadocs-mdx';
import type { InferMetaType, InferPageType } from 'fumadocs-core/source';
import { loader } from 'fumadocs-core/source';
import { meta, docs, blog as blogPosts } from '@/.source';

export const source = loader({
  baseUrl: '/docs',
  source: createMDXSource(docs, meta),
});

export const blog = loader({
  baseUrl: '/blog',
  // 如前所述，您可以将 `meta` 留为空数组
  source: createMDXSource(blogPosts, []),
});

export type DocsPage = InferPageType<typeof source>;
export type DocsMeta = InferMetaType<typeof source>;

以及对应的 source.config.ts：

import {
  defineDocs,
  defineCollections,
  frontmatterSchema,
} from 'fumadocs-mdx/config';
import { z } from 'zod';

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

export const blog = defineCollections({
  type: 'doc',
  dir: 'content/blog',
  schema: frontmatterSchema.extend({
    author: z.string(),
    date: z.string().date().or(z.date()).optional(),
  }),
});

进一步阅读

您可以阅读 Fumadocs MDX 的最新文档以获取详细信息。

Fumadocs MDX

内置内容源，在 Next.js 上构建更好的内容体验。