Next.js

先决条件

🌐 Prerequisite

在继续之前，请确保你已配置：

🌐 Before continuing, make sure you have configured:

Next.js 16
Tailwind CSS 4

我们将使用 Fumadocs MDX 作为内容来源，你可以先进行配置：

🌐 We will use Fumadocs MDX as a content source, you can configure it first:

安装

🌐 Installation

npm i fumadocs-mdx fumadocs-core @types/mdx

创建配置文件：

🌐 Create the configuration file:

source.config.ts

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

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

export default defineConfig();

将插件添加到 Next.js 配置中：

🌐 Add the plugin to Next.js config:

next.config.mjs

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

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

const withMDX = createMDX({
  // customise the config file path
  // configPath: "source.config.ts"
});

export default withMDX(config);

仅限 ESM

Fumadocs MDX 仅支持 ESM，建议使用 next.config.mjs 以实现准确的 ESM 解析。

🌐 Fumadocs MDX is ESM-only, it's recommended to use next.config.mjs for accurate ESM resolution.

对于 TypeScript 配置文件，它需要本地 Node.js TypeScript 解析器，你可以查看 Next.js 文档获取详细信息。

🌐 For TypeScript config file, it requires Native Node.js TypeScript Resolver, you can see Next.js docs for details.

Setup an import alias (recommended):

tsconfig.json

{
  "compilerOptions": {
    "paths": {
      "fumadocs-mdx:collections/*": [".source/*"]
    }
  }
}

与 Fumadocs 集成

🌐 Integrate with Fumadocs

你可以创建一个 lib/source.ts 文件，并从 docs 集合输出中获取 Fumadocs 源代码。

🌐 You can create a lib/source.ts file and obtain Fumadocs source from the docs collection output.

lib/source.ts

import { docs } from 'fumadocs-mdx:collections/server';
import { loader } from 'fumadocs-core/source';

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

当你运行 next dev 或 next build 时，将会生成 .source 文件夹。

🌐 The .source folder will be generated when you run next dev or next build.

完成

🌐 Done

你现在可以在 content/docs 文件夹中编写内容。

🌐 You can now write content in content/docs folder.

值得了解

Fumadocs 还支持其他内容来源，包括内容集合和无头 CMS。

🌐 Fumadocs also supports other content sources, including Content Collections and headless CMS.

入门

🌐 Getting Started

npm i fumadocs-ui fumadocs-core

根布局

🌐 Root Layout

将整个应用封装在根提供程序内，并向 body 添加所需的样式。

🌐 Wrap the entire application inside Root Provider, and add required styles to body.

app/layout.tsx

import { RootProvider } from 'fumadocs-ui/provider/next';
import type { ReactNode } from 'react';

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body
        // required styles
        className="flex flex-col min-h-screen"
      >
        <RootProvider>{children}</RootProvider>
      </body>
    </html>
  );
}

样式

🌐 Styles

将以下 Tailwind CSS 样式添加到 global.css。

🌐 Add the following Tailwind CSS styles to global.css.

global.css

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';

它不带默认字体，你可以从 next/font 中选择一个。

路线

🌐 Routes

创建一个 lib/layout.shared.tsx 文件来放置我们布局的共享选项。

🌐 Create a lib/layout.shared.tsx file to put the shared options for our layouts.

lib/layout.shared.tsx

import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';

export function baseOptions(): BaseLayoutProps {
  return {
    nav: {
      title: 'My App',
    },
  };
}

创建以下文件和路由：

🌐 Create the following files & routes:

import defaultMdxComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';

export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultMdxComponents,
    ...components,
  };
}

该搜索由 Orama 提供支持，了解更多关于文档搜索的信息。

完成

🌐 Finish

你可以启动开发服务器并创建 MDX 文件。

🌐 You can start the dev server and create MDX files.

content/docs/index.mdx

---
title: Hello World
---

## Introduction

I love Anime.

On this page