基于 Next.js 的高性能文档站框架，极速构建现代化的文档系统。

Fumadocs

为什么用它

一句话价值主张：如果你想在 Next.js 项目中用最少配置搭建高性能、美观且 SEO 友好的文档站，Fumadocs 能在 5 分钟内帮你搞定。
三个立刻能感知的收益：
1. 开箱即用：内置全文搜索、深色模式、目录导航 (TOC)。
2. MDX 强力驱动：直接在 Markdown 中使用 React 组件，Type-safe 内容管理。
3. 极速性能：基于 Next.js App Router 优化，静态生成加载飞快。
适合/不适合：
- ✅ 适合：需要构建产品文档、技术博客、知识库的开发者。
- ❌ 不适合：完全非技术背景且需要可视化编辑器（CMS）的运营人员。

3 步极速上手

目标：让用户复制粘贴命令就能看到效果。

步骤 1：初始化项目

使用脚手架快速创建（推荐）：

npm create fumadocs-app@latest
# 或者使用 pnpm
pnpm create fumadocs-app

按提示选择：

Project name: my-docs
Framework: Next.js
Tailwind CSS: Yes

步骤 2：启动开发服务器

进入目录并启动：

cd my-docs
npm run dev

打开浏览器访问 http://localhost:3000，你将看到默认的文档首页。

步骤 3：编写第一篇文档

修改 content/docs/index.mdx（或新建文件）：

---
title: Hello World
description: 我的第一篇文档
---

## 欢迎使用 Fumadocs

这是一个 **Callout** 组件示例：

<Callout title="提示">
  Fumadocs 让文档编写变得非常简单！
</Callout>

保存后，浏览器会自动热更新显示内容。

高频命令

只保留日常开发中最常用的命令：

启动开发环境

npm run dev
# 启动本地服务器，支持热更新

构建生产版本

npm run build
# 生成用于部署的静态文件和产物

更新内容索引

npm run postinstall
# 如果添加了新文件但没显示，运行此命令重新生成内容索引（.map.ts）

类型检查

npm run types:check
# 检查 MDX 内容和 TypeScript 类型是否有误

实用但不高频的命令

自定义 CLI

npx fumadocs-mdx
# 手动触发 MDX 处理流程

添加 UI 组件

# 如果是手动集成而非脚手架创建
npm install fumadocs-ui fumadocs-core

最小可用配置

核心配置文件 source.config.ts (定义内容源)：

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

export const { docs, meta } = defineDocs({
  dir: 'content/docs', // 文档存放目录
});

export default defineConfig({
  lastModifiedTime: 'git', // 自动获取最后修改时间
});

侧边栏结构控制 content/docs/meta.json：

{
  "root": true,
  "pages": [
    "index",
    "---指南---",
    "getting-started",
    "deployment"
  ]
}

常见问题

Q: 新建的 MDX 文件在侧边栏不显示？

症状：文件已创建，但左侧导航栏找不到。
解决：
1. 确保文件在 content/docs 目录下。
2. 运行 npm run postinstall 重新生成索引。
3. 检查 meta.json 是否显式定义了 pages 且漏掉了该文件（如果 meta.json 存在）。
成功判定：重启 dev 服务后侧边栏出现新页面。

Q: 图片无法显示？

症状：MDX 中引用的本地图片 404。
解决：
- 将图片放在 public/ 目录下，引用时使用绝对路径 /image.png。
- 或者使用 import 语法引入图片资源（需配置 Next.js 图片加载）。
成功判定：图片正常渲染。

继续深入

官方文档：https://fumadocs.dev （详细 API、主题定制）
GitHub：fuma-nama/fumadocs

微挑战

现在动手试试（≤ 3 分钟）：

按上面步骤启动项目。
在 content/docs 下新建一个 guide.mdx，写入 Hello Fumadocs。
观察侧边栏是否自动出现 Guide 链接。
尝试在文档中加入一个代码块，看看语法高亮效果。

Fumadocs

On this page