Next.js

前提条件

开始之前，请确保你有：

Next.js 16
Tailwind CSS 4

本指南使用 Fumadocs MDX 作为内容源，你可以先配置好它。

安装

安装包

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

配置文件

创建 source.config.ts：

source.config.ts

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

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

export default defineConfig();

Next.js 插件集成

添加到 next.config.mjs：

next.config.mjs

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

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

const withMDX = createMDX({
  // 自定义配置文件路径
  // configPath: "source.config.ts"
});

export default withMDX(config);

Fumadocs MDX 仅支持 ESM，建议使用 next.config.mjs 以确保正确的模块解析。TypeScript 配置文件需要原生 Node.js TypeScript 解析器。

导入别名设置

配置 tsconfig.json：

tsconfig.json

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

与 Fumadocs 集成

创建 lib/source.ts：

lib/source.ts

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

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

.source 文件夹会在运行 next dev 或 next build 时自动生成。

其他数据源： Fumadocs 支持 Content Collections 和无头 CMS 选项。

安装 UI 包

npm i fumadocs-ui fumadocs-core

根布局设置

在 app/layout.tsx 中用 Root Provider 包裹你的应用：

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 className="flex flex-col min-h-screen">
        <RootProvider>{children}</RootProvider>
      </body>
    </html>
  );
}

样式配置

在 global.css 中添加 Tailwind CSS 导入：

global.css

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

注意：默认不包含字体，请从 next/font 中选择一个。

路由设置

共享布局选项

创建 lib/layout.shared.tsx：

lib/layout.shared.tsx

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

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

MDX 组件

创建 components/mdx.tsx：

components/mdx.tsx

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

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

export const useMDXComponents = getMDXComponents;

declare global {
  type MDXProvidedComponents = ReturnType<typeof getMDXComponents>;
}

文档布局

创建 app/docs/layout.tsx：

app/docs/layout.tsx

import { source } from '@/lib/source';
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { baseOptions } from '@/lib/layout.shared';

export default function Layout({ children }: LayoutProps<'/docs'>) {
  return (
    <DocsLayout tree={source.getPageTree()} {...baseOptions()}>
      {children}
    </DocsLayout>
  );
}

文档页面

创建 app/docs/[[...slug]]/page.tsx：

app/docs/[[...slug]]/page.tsx

import { source } from '@/lib/source';
import {
  DocsBody,
  DocsDescription,
  DocsPage,
  DocsTitle,
} from 'fumadocs-ui/layouts/docs/page';
import { notFound } from 'next/navigation';
import { getMDXComponents } from '@/components/mdx';
import type { Metadata } from 'next';
import { createRelativeLink } from 'fumadocs-ui/mdx';

export default async function Page(
  props: PageProps<'/docs/[[...slug]]'>,
) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  const MDX = page.data.body;

  return (
    <DocsPage toc={page.data.toc} full={page.data.full}>
      <DocsTitle>{page.data.title}</DocsTitle>
      <DocsDescription>{page.data.description}</DocsDescription>
      <DocsBody>
        <MDX
          components={getMDXComponents({
            a: createRelativeLink(source, page),
          })}
        />
      </DocsBody>
    </DocsPage>
  );
}

export async function generateStaticParams() {
  return source.generateParams();
}

export async function generateMetadata(
  props: PageProps<'/docs/[[...slug]]'>,
): Promise<Metadata> {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  return {
    title: page.data.title,
    description: page.data.description,
  };
}

搜索 API

创建 app/api/search/route.ts：

app/api/search/route.ts

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';

export const { GET } = createFromSource(source, {
  language: 'english',
});

搜索由 Orama 提供支持。详情请查看文档搜索文档。

完成

启动开发服务器并创建 MDX 文件。示例 content/docs/index.mdx：

content/docs/index.mdx

---
title: Hello World
---

## 介绍

I love Anime.

Next.js

On this page