Fumadocs MDX v10 摘要

特性

🌐 Features

• 通过 source.config.ts 提供更多自定义，这是一个用于你内容的新配置文件。
• 引入了集合。
• Turbopack 支持。
• 构建时数据验证支持。

从 v9 迁移

🌐 Migrate from v9

重构导入

🌐 Refactor Imports

重构 next.config 中的导入。

🌐 Refactor the import in next.config.

发件人：

import createMDX from 'fumadocs-mdx/config';

const withMDX = createMDX();

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

export default withMDX(config);

收件人：

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

const withMDX = createMDX();

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

export default withMDX(config);

移除 mdx-components.tsx

🌐 Remove mdx-components.tsx

mdx-components.tsx 已不再使用。现在它只允许从 MDX 的 components 属性传入的 MDX 组件。

import defaultMdxComponents from 'fumadocs-ui/mdx';

const MDX = page.data.body;

// set your MDX components with `components` prop
<MDX components={{ ...defaultMdxComponents }} />;

这鼓励显式导入 MDX 组件。

🌐 This encourages explicit import of MDX components.

以前，mdx-components.tsx 的工作方式是向每个编译后的 Markdown/MDX 文件注入一个导入。这有点不必要，因为你总是可以显式地导入组件，或者从 MDX 内容的 components 属性中替换默认的 HTML 标签，如 img。

🌐 Previously, mdx-components.tsx worked by injecting an import to every compiled Markdown/MDX file. It's somewhat unnecessary because you can always import the components explicitly, or replace default HTML tags like img from MDX body's components prop.

定义集合

🌐 Define Collections

Collection 现在已在源配置文件（source.config.ts）中引入。它指的是一组文件/内容，例如 Markdown 文件或 JSON/YAML 文件。

🌐 Collection is now introduced on source config file (source.config.ts). It refers to a collection of files/content, such as Markdown files or JSON/YAML files.

每个集合都有自己的配置，你可以使用自定义的 Zod 模式来验证其数据，或者针对内容集合使用集合级的 MDX 选项。

🌐 Every collection has its own config, you can have customised Zod schema to validate its data, or collection-level MDX options for content collections.

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

🌐 You can create a source config file, and add the following:

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

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

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

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

🌐 Now you can generate types using fumadocs-mdx command, it's recommended to set it as a postinstall script.

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

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

🌐 When starting the development server, a .source folder will be generated, it contains all parsed collections/files. You can add it to .gitignore, it will replace the old .map file.

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

🌐 To access the collections, import them from the folder with their original name in source.config.ts.

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

现在要将其与 Fumadocs 框架集成，请将你的 source.ts 从：

🌐 Now to integrate it with Fumadocs framework, change your source.ts from:

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

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

到:

🌐 to:

import { docs, meta } from '@/.source';
import { createMDXSource } from 'fumadocs-mdx/runtime/next';
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 对象中。

🌐 When using with loader, you no longer need data.frontmatter to access frontmatter data. It is merged into the page.data object.

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

MDX 选项

🌐 MDX Options

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

🌐 Instead of passing them to next.config file, define a global config in source.config.ts:

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

export default defineConfig({
  mdxOptions: {
    // here!
  },
});

集合模式

🌐 Collection Schema

集合的 schema 选项允许你自定义验证模式，它接受一个 Zod 类型。

🌐 The schema option of collection allow you to customise the validation schema, it accepts a Zod type.

有关 defineDocs，请参见 schema。

🌐 For defineDocs, see schema.

多种类型

🌐 Multiple Types

和以前一样，你可以多次调用 loader 来处理不同类型（例如文档和博客）。

🌐 Same as before, you can call loader multiple times for different types (e.g. for docs and blog).

import { createMDXSource } from 'fumadocs-mdx/runtime/next';
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',
  // as mentioned before, you can leave `meta` an empty array
  source: createMDXSource(blogPosts, []),
});

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

以及对应的 source.config.ts：

🌐 and the corresponding 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(),
  }),
});

延伸阅读

🌐 Further Readings

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

🌐 You can read the latest docs of Fumadocs MDX for details.