文档站点生成器 - Fumadocs

一、简介

Fumadocs 是一款基于 React + Next.js 开发的现代化开源文档站点生成器，主打Headless 架构、MDX 驱动、高度可定制 ，专为技术文档、API 文档、知识库与产品手册设计。它遵循文档即代码理念，支持文件路由、多版本、多仓库聚合、全文搜索与自动化 API 文档生成，开箱即用且深度可扩展。

二、核心特点

特性	说明
MDX 原生支持	支持 Markdown 增强，可直接嵌入 React 组件、代码块、图表、交互演示
Headless 架构	核心逻辑与 UI 完全分离，可自由替换主题、布局、组件
Next.js 原生	基于 App Router + React Server Components，支持 SSG、ISR、流式渲染
多版本管理	支持文档版本切换，适配多分支、多版本文档托管
内置全文搜索	自带 Orama 搜索，可无缝对接 Algolia，无需额外服务
自动化文档	支持从 TypeScript 类型、OpenAPI 规范自动生成 API 文档
Playbook 式配置	通过 `fumadocs.config.ts` 统一管理导航、侧边栏、主题、搜索等
UI 主题化	提供默认精美 UI，支持暗色模式、响应式、Tailwind 定制

三、典型应用场景

开源项目/组件库官方文档
企业多产品、多版本技术手册
微服务统一文档门户
API 文档、开发者平台
个人知识库、教程网站、笔记站点
需要高度自定义 UI 的品牌化文档站

四、核心概念

核心包分层

fumadocs-core：导航、侧边栏、TOC、搜索等无 UI 核心逻辑
fumadocs-ui：官方默认 UI 组件、布局、主题
fumadocs-mdx：MDX 解析、文件路由、内容加载

文档组件（Content Collection）

以文件夹组织文档，支持多模块、多版本结构：

复制代码

content/
└── docs/
    ├── index.mdx        # 首页
    ├── guide/           # 子目录
    │   ├── install.mdx
    │   └── config.mdx
    └── api/             # API 模块
        └── index.mdx

配置文件（fumadocs.config.ts）

站点统一配置入口，定义标题、导航、侧边栏、主题、搜索等。
文件路由
content/docs 下的 .mdx 文件自动生成路由，无需手动配置。
TOC / 侧边栏

自动从标题生成目录，支持滚动跟随、锚点定位。

五、快速开始

1. 环境要求

Node.js 18+

2. 创建项目

bash 复制代码

npm create fumadocs-app@latest my-fumadoc
cd my-fumadoc

3. 安装依赖

bash 复制代码

npm install

4. 启动开发

bash 复制代码

npm run dev

访问：http://localhost:3000

5. 编写文档

在 content/docs/ 下新建 .mdx 文件即可自动生成页面。

6. 基础配置

修改 fumadocs.config.ts 配置导航、主题、版本等。

7. 生产构建

bash 复制代码

npm run build

六、部署方案

1. Vercel（推荐）

直接导入 Git 仓库
构建命令：npm run build
输出目录：.next
自动部署、自动 HTTPS

2. GitHub Actions

yaml 复制代码

name: Deploy Fumadocs
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: {node-version: 20}
      - run: npm install
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./out

3. Netlify / Cloudflare Pages

构建命令：npm run build
发布目录：out（需开启静态导出）

4. 自建服务器 / Nginx

构建：npm run build
将 out 目录部署到 Nginx 静态站点即可

七、学习资源

官方文档：https://fumadocs.vercel.app
GitHub 源码：https://github.com/fuma-nama/fumadocs
示例模板：文档站、API 文档、博客、多版本
UI 定制指南：主题、组件覆盖、Tailwind 配置
扩展插件：Orama 搜索、Algolia、OpenAPI、TypeScript 自动文档