手动安装 Fumadocs

请先阅读快速入门指南了解基本概念。

从空项目开始

先通过 create-next-app 创建一个新的 Next.js 项目，然后安装 Fumadocs 所需的依赖包。

fumadocs-ui fumadocs-core

选择内容源

Fumadocs 支持多种内容源，你可以根据自己的工作流挑选其中一种。

目前官方支持的方案包括：

继续之前，请先按对应文档把内容源本身配置好。本篇示例会从 @/lib/source.ts 导入源适配器。

配置根布局

先用 Root Provider 包裹整个应用，再给 body 添加最基础的布局样式。

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

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body
        // you can use Tailwind CSS too
        style={{
          display: 'flex',
          flexDirection: 'column',
          minHeight: '100vh',
        }}
      >
        <RootProvider>{children}</RootProvider>
      </body>
    </html>
  );
}

添加样式

在 Next.js 项目里配置好 Tailwind CSS v4 后，把下面这些导入放到 global.css 中。

Tailwind CSS

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

/* path of `fumadocs-ui` relative to the CSS file */
@source '../node_modules/fumadocs-ui/dist/**/*.js';

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

准备共享布局配置

创建 app/layout.config.tsx，用于集中放置多个布局都会复用的选项。

{
  "file": "../../examples/next-mdx/app/layout.config.tsx",
  "codeblock": {
    "meta": "title=\"app/layout.config.tsx\""
  }
}

接着创建 /app/docs，并为文档区域设置专门的布局。

{
  "file": "../../examples/next-mdx/app/docs/layout.tsx",
  "codeblock": {
    "meta": "title=\"app/docs/layout.tsx\""
  }
}

pageTree 指的是页面树，应该由您的内容源提供。

添加文档页面路由

为文档页面创建 /app/docs/[[...slug]] 这个捕获所有路由。

在对应页面中，用 Page 组件来包裹内容。具体写法会随着内容源不同而变化，同时别忘了配置 generateStaticParams 做静态渲染，以及 generateMetadata 生成元数据。

{
  "file": "../../examples/next-mdx/app/docs/[[...slug]]/page.tsx",
  "codeblock": {
    "meta": "title=\"app/docs/[[...slug]]/page.tsx\" tab=\"Fumadocs MDX\""
  }
}

{
  "file": "../../examples/content-collections/app/docs/[[...slug]]/page.tsx",
  "codeblock": {
    "meta": "title=\"app/docs/[[...slug]]/page.tsx\" tab=\"Content Collections\""
  }
}

启用搜索

你可以直接使用基于 Orama 的默认文档搜索实现。

{
  "file": "../../examples/next-mdx/app/api/search/route.ts",
  "codeblock": {
    "meta": "title=\"app/api/search/route.ts\" tab=\"Fumadocs MDX\""
  }
}

{
  "file": "../../examples/content-collections/app/api/search/route.ts",
  "codeblock": {
    "meta": "title=\"app/api/search/route.ts\" tab=\"Content Collections\""
  }
}

想了解更多，可以继续阅读文档搜索。

收尾

到这里就可以启动开发服务器，并开始创建自己的 MDX 文件了。

content/docs/index.mdx

---
title: Hello World
---

## Introduction

I love Anime.

进一步定制

站点中的其他页面可以使用 Home Layout，它已经包含导航栏和主题切换能力。

部署

这套方案默认就可以部署到 Vercel 和 Netlify。

Docker 部署

如果你打算在 已配置 Fumadocs MDX 的前提下使用 Docker 部署，请记得把 source.config.ts 复制进 Dockerfile 的 WORKDIR。下面这段示例来自官方 Next.js Dockerfile 示例：

Dockerfile

WORKDIR /app

# Install dependencies based on the preferred package manager
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* source.config.ts ./

这样一来，Fumadocs MDX 在构建阶段依然可以读取到对应的配置文件。

请先阅读快速入门指南了解基本概念。

从空项目开始

先通过 create-next-app 创建一个新的 Next.js 项目，然后安装 Fumadocs 所需的依赖包。

fumadocs-ui fumadocs-core

选择内容源

Fumadocs 支持多种内容源，你可以根据自己的工作流挑选其中一种。

目前官方支持的方案包括：

继续之前，请先按对应文档把内容源本身配置好。本篇示例会从 @/lib/source.ts 导入源适配器。

配置根布局

先用 Root Provider 包裹整个应用，再给 body 添加最基础的布局样式。

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

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body
        // you can use Tailwind CSS too
        style={{
          display: 'flex',
          flexDirection: 'column',
          minHeight: '100vh',
        }}
      >
        <RootProvider>{children}</RootProvider>
      </body>
    </html>
  );
}

添加样式

在 Next.js 项目里配置好 Tailwind CSS v4 后，把下面这些导入放到 global.css 中。

Tailwind CSS

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

/* path of `fumadocs-ui` relative to the CSS file */
@source '../node_modules/fumadocs-ui/dist/**/*.js';

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

准备共享布局配置

创建 app/layout.config.tsx，用于集中放置多个布局都会复用的选项。

{
  "file": "../../examples/next-mdx/app/layout.config.tsx",
  "codeblock": {
    "meta": "title=\"app/layout.config.tsx\""
  }
}

接着创建 /app/docs，并为文档区域设置专门的布局。

{
  "file": "../../examples/next-mdx/app/docs/layout.tsx",
  "codeblock": {
    "meta": "title=\"app/docs/layout.tsx\""
  }
}

pageTree 指的是页面树，应该由您的内容源提供。

添加文档页面路由

为文档页面创建 /app/docs/[[...slug]] 这个捕获所有路由。

{
  "file": "../../examples/next-mdx/app/docs/[[...slug]]/page.tsx",
  "codeblock": {
    "meta": "title=\"app/docs/[[...slug]]/page.tsx\" tab=\"Fumadocs MDX\""
  }
}

{
  "file": "../../examples/content-collections/app/docs/[[...slug]]/page.tsx",
  "codeblock": {
    "meta": "title=\"app/docs/[[...slug]]/page.tsx\" tab=\"Content Collections\""
  }
}

启用搜索

你可以直接使用基于 Orama 的默认文档搜索实现。

{
  "file": "../../examples/next-mdx/app/api/search/route.ts",
  "codeblock": {
    "meta": "title=\"app/api/search/route.ts\" tab=\"Fumadocs MDX\""
  }
}

{
  "file": "../../examples/content-collections/app/api/search/route.ts",
  "codeblock": {
    "meta": "title=\"app/api/search/route.ts\" tab=\"Content Collections\""
  }
}

想了解更多，可以继续阅读文档搜索。

收尾

到这里就可以启动开发服务器，并开始创建自己的 MDX 文件了。

content/docs/index.mdx

---
title: Hello World
---

## Introduction

I love Anime.

进一步定制

站点中的其他页面可以使用 Home Layout，它已经包含导航栏和主题切换能力。

部署

这套方案默认就可以部署到 Vercel 和 Netlify。

Docker 部署

Dockerfile

WORKDIR /app

# Install dependencies based on the preferred package manager
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* source.config.ts ./

这样一来，Fumadocs MDX 在构建阶段依然可以读取到对应的配置文件。

从空项目开始

选择内容源

配置根布局

添加样式

准备共享布局配置

添加文档页面路由

启用搜索

收尾

进一步定制

部署

Docker 部署

作者

分类

更多文章

Orelune Tarot Series: Two of Wands - Vision, Choice, and Future Planning

认识 Fumadocs

Orelune Tarot Series: The Suit of Cups - Feeling, Intuition, and Emotional Flow

邮件列表

手动安装 Fumadocs

从空项目开始

选择内容源

配置根布局

添加样式

准备共享布局配置

添加文档页面路由

启用搜索

收尾

进一步定制

部署

Docker 部署

作者

分类

更多文章

Orelune Tarot Series: Two of Wands - Vision, Choice, and Future Planning

认识 Fumadocs

Orelune Tarot Series: The Suit of Cups - Feeling, Intuition, and Emotional Flow

邮件列表