速查手册
Fumadocs
基于 Next.js 的高性能文档站框架，极速构建现代化的文档系统。
为什么用它
- 一句话价值主张：如果你想在 Next.js 项目中用最少配置搭建高性能、美观且 SEO 友好的文档站，Fumadocs 能在 5 分钟内帮你搞定。
- 三个立刻能感知的收益：
- 开箱即用：内置全文搜索、深色模式、目录导航 (TOC)。
- MDX 强力驱动：直接在 Markdown 中使用 React 组件，Type-safe 内容管理。
- 极速性能：基于 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 文件在侧边栏不显示？
- 症状：文件已创建，但左侧导航栏找不到。
- 解决：
- 确保文件在
content/docs目录下。 - 运行
npm run postinstall重新生成索引。 - 检查
meta.json是否显式定义了pages且漏掉了该文件（如果meta.json存在）。
- 确保文件在
- 成功判定：重启
dev服务后侧边栏出现新页面。
Q: 图片无法显示？
- 症状：MDX 中引用的本地图片 404。
- 解决：
- 将图片放在
public/目录下，引用时使用绝对路径/image.png。 - 或者使用
import语法引入图片资源（需配置 Next.js 图片加载）。
- 将图片放在
- 成功判定：图片正常渲染。
继续深入
- 官方文档：https://fumadocs.dev （详细 API、主题定制）
- GitHub：fuma-nama/fumadocs
核心特性
| 特性 | 说明 |
|---|---|
| MDX 支持 | Markdown + React 组件 |
| 自动生成导航 | 基于文件结构生成侧边栏 |
| 全文搜索 | 内置 Fuse.js 搜索 |
| 主题系统 | 支持自定义主题 |
| 代码高亮 | 语法高亮、行号、复制 |
| 数学公式 | LaTeX 支持 |
快速开始
npm create fumadocs@latest项目结构
my-docs/
├── app/ # Next.js 应用
│ ├── docs/[[...slug]]/ # 文档路由
│ ├── layout.tsx # 根布局
│ └── page.tsx # 首页
├── content/ # 文档内容 (MDX)
│ └── docs/
├── components/ # 自定义组件
├── lib/ # 工具函数
├── fumadocs.config.ts # 全局配置
└── package.json配置文件
fumadocs.config.ts
import { defineConfig } from 'fumadocs/config';
export default defineConfig({
title: 'My Docs',
description: 'Documentation site',
baseUrl: 'https://docs.example.com',
search: {
provider: 'fuse',
},
i18n: {
defaultLocale: 'zh',
locales: [
{ code: 'zh', name: '中文' },
{ code: 'en', name: 'English' },
],
},
});meta.json（页面元数据）
每个目录可放置 meta.json 控制导航和页面属性：
{
"title": "Getting Started",
"description": "Quick start guide",
"icon": "Rocket",
"root": true,
"defaultOpen": true,
"pages": ["index", "installation", "configuration"]
}| 字段 | 类型 | 说明 |
|---|---|---|
title | string | 目录/页面标题 |
description | string | 描述（用于 SEO） |
icon | string | Lucide 图标名称 |
root | boolean | 是否为根节点 |
defaultOpen | boolean | 默认展开子项 |
pages | string[] | 页面排序（文件名，不含扩展名） |
页面级 frontmatter
MDX 文件顶部配置：
---
title: 页面标题
description: 页面描述
icon: IconName
full: false # 是否全宽布局
toc: true # 是否显示目录
---
# 正文内容常用命令
npm run dev # 开发模式
npm run build # 构建
npm run preview # 预览构建结果MDX 组件使用
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
<Callout type="info" title="提示">
重要信息
</Callout>
<Tabs items={["npm", "pnpm"]}>
<Tab value="npm">npm install</Tab>
<Tab value="pnpm">pnpm install</Tab>
</Tabs>内置组件
| 组件 | 用途 |
|---|---|
Callout | 提示框（info/warning/error） |
Tabs/Tab | 标签页切换 |
Steps | 步骤指引 |
Files | 文件树展示 |
TypeTable | 类型表格 |
Accordions | 手风琴折叠 |
Card/ Cards | 卡片布局 |
自定义组件示例
// components/Alert.tsx
export function Alert({ children }: { children: React.ReactNode }) {
return (
<div className="bg-blue-100 border-l-4 border-blue-500 p-4">
{children}
</div>
);
}MDX 中使用：
import { Alert } from '@/components/Alert';
<Alert>自定义警告内容</Alert>