ClaudeSkills
浏览文档

旧模板文档

快速入门

Fumadocs 入门指南

Historical Fumadocs template

旧模板文档为历史链接保留，内容不作为当前 ClaudeSkills 产品指南。

这里保留既有编辑译文；如有最新完整官方参考，会在下方独立提供英文原文。

查看来源
本页目录

简介

Fumadocs (Foo-ma docs) 是一个基于 Next.js 的文档框架，设计为快速、灵活， 并无缝集成到 Next.js App Router 中。

Fumadocs 由不同部分组成：

Fumadocs Core

处理大部分逻辑，包括文档搜索、内容源适配器和 Markdown 扩展。

Fumadocs UI

Fumadocs 的默认主题为文档站点提供了美观的外观和交互式组件。

Content Source

您内容的来源，可以是 CMS 或本地数据层，如 Content Collections 和 Fumadocs MDX，即官方内容源。

Fumadocs CLI

一个命令行工具，用于安装 UI 组件和自动化操作，对于自定义布局非常有用。

想了解更多？

阅读我们深入的 什么是 Fumadocs 介绍。

术语

Markdown/MDX: Markdown 是一种用于创建格式化文本的标记语言。Fumadocs 默认支持 Markdown 和 MDX（Markdown 的超集）。

虽然不是必需的，但对 Next.js App Router 的基本了解对于进一步的自定义会很有帮助。

自动安装

需要 Node.js 18 或更高版本，请注意 Node.js 23.1 可能在 Next.js 生产构建中存在问题。

npm create fumadocs-app

pnpm create fumadocs-app

yarn create fumadocs-app

bun create fumadocs-app

它会询问您要使用的框架和内容源，随后将初始化一个新的 fumadocs 应用程序。现在您可以开始动手了！

从现有代码库开始？

您可以按照 [手动安装](/docs/manual-installation) 指南开始。

尽情使用！

在 docs 文件夹中创建您的第一个 MDX 文件。

---
title: Hello World
---

## Yo what's up

在开发模式下运行应用程序并查看 http://localhost:3000/docs。

npm run dev

探索

在项目中，您可以看到：

  • lib/source.ts：内容源适配器的代码，loader() 提供了与内容源交互的接口，并为您的页面分配 URL。
  • app/layout.config.tsx：布局的共享选项，可选但建议保留。
路由 描述
app/(home) 您的登陆页面和其他页面的路由组。
app/docs 文档布局和页面。
app/api/search/route.ts 搜索的路由处理器。

编写内容

对于编写文档，请务必阅读：

Markdown

Fumadocs 还有一些额外的内容创作功能。

了解如何自定义导航链接/侧边栏项目。

内容源

内容源处理您的所有内容，例如编译 Markdown 文件和验证前言。

Fumadocs MDX

    阅读 [介绍](/docs/mdx) 了解它如何处理您的内容。

    项目中已包含 `source.config.ts` 配置文件，您可以自定义不同的选项，如前言模式。

Custom Source

    Fumadocs 不仅限于 Markdown。对于其他源（如 Sanity），您可以构建 [自定义内容源](https://fumadocs.dev/docs/headless/custom-source)。

自定义 UI

请参阅 自定义指南。

常见问题

您可能遇到的一些常见问题。

如何修复 Monorepo 中样式不应用的问题？

有时，fumadocs-ui 没有安装在您的 Tailwind CSS 配置文件的工作区中（例如，在 monorepo 设置中）。

您必须确保 Tailwind CSS 扫描 fumadocs-ui 包，并为 @source 提供正确的相对路径。

例如，添加 ../../ 指向根工作区中的 node_modules 文件夹。

    ```css
    @import 'tailwindcss';
    @import 'fumadocs-ui/css/neutral.css';
    @import 'fumadocs-ui/css/preset.css';

    /* [!code --] */
    @source '../node_modules/fumadocs-ui/dist/**/*.js';
    /* [!code ++] */
    @source '../../../node_modules/fumadocs-ui/dist/**/*.js';
    ```

如何更改 /docs 的基本路由？

您可以更改文档的基本路由（例如，从 /docs/page 更改为 /info/page）。 由于 Fumadocs 使用 Next.js App Router，您可以简单地重命名路由：

  • app/docs/

    • layout.tsx

  • app/info/

    • layout.tsx

并在 source.ts 中告诉 Fumadocs 使用新的路由：

import { loader } from 'fumadocs-core/source';

export const source = loader({
  baseUrl: '/info',
  // other options
});

它使用动态路由，性能会很差吗？

当配置了 generateStaticParams 时，Next.js 会将动态路由转换为静态路由。 因此，它与静态页面一样快。

您可以在 Next.js 上启用静态导出，获得静态构建输出。（请注意，路由处理器不适用于静态导出，您必须配置静态搜索）

如何在 /docs 中创建没有文档布局的页面？

与在 Next.js App Router 中管理布局相同，从内容目录（/content/docs）中删除原始 MDX 文件。 这确保重复的页面不会导致错误。

现在，您可以将页面添加到另一个路由组，该组不是文档布局的后代。

例如，在您的 app 文件夹下：

  • (home)/docs/page.tsx

  • docs/

    • layout.tsx

    • [[...slug]]/page.tsx

将用您的 page.tsx 替换 /docs 页面。

如何实现多版本文档？

    为每个版本使用单独的部署。

    在 Vercel 上，可以通过在 GitHub 存储库中为特定版本创建另一个分支来实现。
    要链接到其他版本的站点，请使用 Links API 或自定义导航组件。

如何实现多文档？

    我们建议使用 [侧边栏标签](https://fumadocs.dev/docs/ui/navigation/sidebar#sidebar-tabs)。

视频教程

Video tutorial

了解更多

刚来这里？别担心，我们欢迎您的问题。