手动安装 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塔罗系列：权杖国王牌义——远见、领导与掌控力

Orelune 塔罗系列：节制——平衡、调和与耐心

邮件列表

手动安装 Fumadocs

从空项目开始

选择内容源

配置根布局

添加样式

准备共享布局配置

添加文档页面路由

启用搜索

收尾

进一步定制

部署

Docker 部署

作者

分类

更多文章

对比

Orelune塔罗系列：权杖国王牌义——远见、领导与掌控力

Orelune 塔罗系列：节制——平衡、调和与耐心

邮件列表