Fumadocs 项目文档

项目概述

这是一个基于 Fumadocs 构建的文档网站项目，主要用于展示 Telegram 机器人开发相关的教程和指南。项目采用 Next.js 15 + React 19 + TypeScript 技术栈，并集成了自定义的增强功能。

技术栈

前端框架: Next.js 15.4.2
UI 库: React 19.1.0
文档框架: Fumadocs (Core 15.6.5, UI 15.6.5, MDX 11.7.0)
样式: Tailwind CSS 4.1.11
图标: Lucide React 0.544.0
语言: TypeScript 5.8.3
包管理: pnpm

项目结构

fumadocs/
├── app/                          # Next.js App Router
│   ├── (home)/                   # 首页路由组
│   │   ├── layout.tsx           # 首页布局
│   │   └── page.tsx             # 首页内容
│   ├── api/                     # API 路由
│   │   └── search/              # 搜索功能
│   │       └── route.ts         # 搜索路由处理
│   ├── docs/                    # 文档页面
│   │   ├── [[...slug]]/         # 动态路由
│   │   │   └── page.tsx         # 文档页面渲染
│   │   └── layout.tsx           # 文档布局
│   ├── global.css               # 全局样式
│   ├── layout.config.tsx        # 布局配置
│   └── layout.tsx               # 根布局
├── components/                   # 自定义组件
│   └── custom-docs-page.tsx     # 增强文档页面组件 ⭐
├── content/                     # 文档内容
│   └── docs/                    # 文档文件
│       └── index.mdx            # Telegram Bot 教程
├── lib/                         # 工具库
│   └── source.ts                # 内容源适配器
├── mdx-components.tsx           # MDX 组件配置
├── next.config.mjs              # Next.js 配置
├── source.config.ts             # Fumadocs MDX 配置
└── package.json                 # 项目依赖

核心功能

1. 基础文档系统

基于 Fumadocs 提供的完整文档解决方案：

MDX 文件支持
自动路由生成
搜索功能
响应式布局
暗色主题支持

2. 自定义增强功能 ⭐

右侧目录结构 (Table of Contents)

功能特点：

🎯 智能层级显示: 根据 Markdown 标题层级自动生成目录树
🎨 视觉层级区分: 不同层级使用不同的缩进、字体大小和颜色
📱 响应式交互: 支持显示/隐藏切换，适配不同屏幕尺寸
🔄 平滑动画: 使用 CSS Transform 实现流畅的展开收起效果

技术实现：

// 目录项渲染逻辑
const renderTocItem = (item: any) => {
    const level = item.depth || 0;
    
    // 根据层级设置缩进
    const indentClass = level === 1 ? 'pl-0' :
        level === 2 ? 'pl-3' :
        level === 3 ? 'pl-6' :
        level === 4 ? 'pl-9' :
        level === 5 ? 'pl-12' : 'pl-15';
    
    // 根据层级设置字体样式
    const textSizeClass = level === 1 ? 'text-sm' : 
        level === 2 ? 'text-sm' : 'text-xs';
    const fontWeightClass = level === 1 ? 'font-semibold' : 
        level === 2 ? 'font-medium' : 'font-normal';
};

交互特性：

固定定位: 右侧固定 320px 宽度侧边栏
切换控制: 通过 isTocVisible 状态控制显示/隐藏
悬浮按钮: 隐藏时显示圆形悬浮按钮快速展开
平滑过渡: 300ms CSS transition 动画效果

页面字数统计

功能特点：

🔢 智能计算: 中英文混合内容的精确字数统计
🎯 实时更新: 基于 DOM 内容实时计算，确保准确性
🌍 多语言支持: 中文字符按字计算，英文按单词计算
⏱️ 性能优化: 使用 useRef 和 setTimeout 避免重复计算

技术实现：

const calculateWordCount = () => {
    let textContent = '';
    
    // 优先从DOM获取实际渲染的文本
    if (contentRef.current) {
        textContent = contentRef.current.textContent || '';
    } else if (content) {
        textContent = content.toString();
    }
    
    if (textContent) {
        // 文本清理：合并空格和换行
        const cleanText = textContent
            .replace(/\s+/g, ' ')
            .trim();
        
        // 分别计算中文字符和英文单词
        const chineseChars = (cleanText.match(/[\u4e00-\u9fa5]/g) || []).length;
        const englishWords = cleanText
            .replace(/[\u4e00-\u9fa5]/g, '') // 移除中文字符
            .split(/\s+/)
            .filter(word => word.length > 0).length;
        
        setWordCount(chineseChars + englishWords);
    }
};

统计逻辑：

中文字符: 使用正则 [\u4e00-\u9fa5] 匹配中文字符，每个字符计为 1 字
英文内容: 按空格分割后过滤空字符串，每个单词计为 1 字
混合计算: 中文字符数 + 英文单词数 = 总字数
DOM优先: 优先使用实际渲染的 DOM 内容，确保统计准确性

显示效果：

本文共 123 字    最后更新: 2025/9/20

3. 内容管理

MDX 支持：

支持 Markdown 语法和 React 组件
自定义 frontmatter 配置
图片和媒体文件支持

内容结构：

/content/docs/ - 主要文档内容
支持嵌套目录结构
自动生成导航和面包屑

配置说明

1. Next.js 配置 (next.config.mjs)

const config = {
  reactStrictMode: true,
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'pic.616pic.com',  // 限制图片域名
        port: '',
        pathname: '/**',
      },
    ],
  },
};

2. Fumadocs 配置 (source.config.ts)

export const docs = defineDocs({
  docs: {
    schema: frontmatterSchema,  // 文档元数据模式
  },
  meta: {
    schema: metaSchema,         // 导航元数据模式
  },
});

3. 布局配置 (app/layout.config.tsx)

export const baseOptions: BaseLayoutProps = {
  nav: {
    title: "My App",          // 导航标题
  },
  links: [],                  // 导航链接
};

开发指南

启动开发服务器

# 使用 pnpm (推荐)
pnpm dev

# 使用 npm
npm run dev

# 使用 yarn
yarn dev

访问 http://localhost:3000 查看效果

构建部署

# 构建生产版本
pnpm build

# 启动生产服务器
pnpm start

添加新文档

在 /content/docs/ 下创建 .mdx 文件

添加 frontmatter 元数据：

---
title: 文档标题
description: 文档描述
---

编写 Markdown 内容
系统会自动生成路由和导航

自定义组件

在 mdx-components.tsx 中添加自定义 MDX 组件：

export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultMdxComponents,
    // 添加自定义组件
    CustomComponent: MyCustomComponent,
    ...components,
  };
}

部署配置

Vercel 部署

项目已配置 vercel.json：

{
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "installCommand": "npm install",
  "framework": "nextjs"
}

环境要求

Node.js 18+
pnpm 8+ (推荐)
现代浏览器支持

特色亮点

1. 用户体验优化

📖 沉浸式阅读: 自定义目录侧边栏，不干扰主要内容
📊 阅读进度: 实时字数统计，帮助用户了解内容长度
🎨 视觉层次: 清晰的目录层级和视觉反馈
📱 响应式设计: 适配各种屏幕尺寸

2. 开发体验

🔧 类型安全: 完整的 TypeScript 支持
⚡ 快速开发: Turbo 模式和热重载
🎯 模块化: 清晰的组件和配置分离
📝 易于扩展: 基于 Fumadocs 的标准化架构

3. 性能优化

🚀 静态生成: Next.js 静态页面生成
💾 智能缓存: 合理的缓存策略
📦 代码分割: 自动的代码分割和懒加载
🎨 CSS 优化: Tailwind CSS 的按需加载

未来规划

技术支持

本文档最后更新: 2025年9月20日

Fumadocs 项目文档

文档目录