文档系统

🏗️ 文档架构

NEXTDEVKIT 的文档系统结构如下：

src/
├── content/
│   └── docs/
│       ├── index.mdx                    # 文档首页
│       ├── index.zh.mdx                 # 中文首页
│       ├── meta.json                    # 根导航
│       ├── ...
│       └── deployment/
│           ├── index.mdx
│           ├── nextjs.mdx
│           ├── cloudflare-worker.mdx
│           ├── sst-aws.mdx
│           └── meta.json
├── app/
│   └── [locale]/
│       └── docs/
│           ├── layout.tsx               # 文档布局
│           └── [[...slug]]/
│               └── page.tsx             # 文档页面
├── components/
│   └── docs/
│       └── mdx-components.tsx           # 文档组件
├── lib/
│   └── source.ts                       # 文档源加载器
└── source.config.ts                   # 文档集合配置

⚙️ 文档配置

源配置

文档系统在 source.config.ts 中配置：

src/source.config.ts

import { defineDocs } from "fumadocs-mdx/config";

export const docs = defineDocs({
  dir: "src/content/docs",
});

源加载器

文档使用 Fumadocs 在 src/lib/source.ts 中加载：

src/lib/source.ts

export const source = loader({
  i18n,
  baseUrl: "/docs",
  source: docs.toFumadocsSource(),
});

📁 文档组织

Meta 文件

文档结构使用 meta.json 文件组织：

根目录 meta.json：

{
  "title": "NEXTDEVKIT",
  "description": "NEXTDEVKIT 文档",
  "root": true,
  "pages": [
    "index",
    "tech-stack",
    "environment",
    "configuration",
    "deployment",
    "---代码库---",
    "project-structure",
    "ide-setup",
    "formatting-and-linting",
    "update-the-codebase",
    "---功能特性---",
    "database",
    "authentication",
    "payment",
    "blog",
    "documentation",
    "---高级选项---",
    "themes",
    "seo"
  ]
}

章节 meta.json（例如 environment/meta.json）：

{
  "title": "环境设置",
  "description": "配置您的开发环境",
  "pages": [
    "index",
    "nextjs",
    "cloudflare-worker",
    "sst-aws"
  ]
}

分层组织

使用带有索引文件的文件夹组织文档：

docs/
├── environment/
│   ├── index.mdx          # 环境概述
│   ├── nextjs.mdx         # Next.js 设置
│   ├── cloudflare-worker.mdx
│   ├── sst-aws.mdx
│   └── meta.json          # 章节导航
├── configuration/
│   ├── index.mdx          # 配置概述
│   ├── website-config.mdx
│   ├── marketing-config.mdx
│   └── meta.json

📝 创建文档

添加新的文档页面

在 src/content/docs/ 中创建一个新的 MDX 文件：

---
title: API 参考
description: NEXTDEVKIT 的完整 API 参考
icon: Code
---

# API 参考

NEXTDEVKIT 服务器操作和工具的完整 API 参考。

## 认证 API

### `getSession()`

在服务器端获取当前用户会话。

```typescript title="src/app/components/server-component.tsx"
import { getSession } from '@/lib/auth/server';

export default async function ServerComponent() {
  const session = await getSession();
  
  if (!session?.user) {
    redirect('/auth/login');
  }
  
  return <div>欢迎，{session.user.name}！</div>;
}

frontmatter 中的 icon 属性支持所有 Lucide 图标，并将在侧边栏中生成为图标。

组织结构

Fumadocs 支持文档的分层组织。

您可以在每个文件夹中创建 meta.json 文件来组织文档。

例如，要创建一个名为 configuration 的新章节，您需要在 src/content/docs/ 目录中创建一个名为 configuration 的新文件夹，并在其中添加一个 meta.json 文件。

src/content/docs/configuration/meta.json

{
  "title": "配置",
  "description": "配置文档",
  "pages": [
    "index",
    "website-config",
    "marketing-config"
  ]
}

多语言支持

Fumadocs 支持多语言文档。

您可以使用以下文件命名约定创建多语言内容：

默认语言（例如英语）：filename.mdx
其他语言（例如中文）：filename.zh.mdx

对于国际化，您可以在同一文件夹中创建一个新的 meta.zh.json 文件。

搜索 API

Fumadocs 提供搜索 API 来搜索文档。

您可以使用 createI18nSearchAPI 函数来搜索文档。

src/app/api/search/route.ts

export const { GET } = createI18nSearchAPI("advanced", {
	i18n: {
		defaultLanguage: appConfig.i18n.defaultLocale,
		languages: Object.keys(appConfig.i18n.locales).filter(
			(locale) => locale !== "zh",
		),
	},
	indexes: source.getLanguages().flatMap((entry) =>
		entry.pages.map((page) => ({
			title: page.data.title,
			description: page.data.description,
			structuredData: (page.data as any)?.structuredData,
			id: page.url,
			url: page.url,
			locale: entry.language,
		})),
	),
});

因为默认搜索 API 不支持中文 zh，您需要从 languages 数组中过滤掉中文。

如果您想支持像中文这样的特殊语言搜索，您可以参考以下链接：

例如，对于中文和日文，它们需要额外的配置：

pnpm add @orama/tokenizers

更新搜索 API 以支持特殊语言：

src/app/api/search/route.ts

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
import { createTokenizer } from '@orama/tokenizers/mandarin';

export const { GET } = createFromSource(source, {
  localeMap: {
    // [locale]: Orama 选项
    zh: {
      components: {
        tokenizer: createTokenizer(),
      },
      search: {
        threshold: 0,
        tolerance: 0,
      },
    },
  },
});

🔗 相关资源

🎯 下一步

现在您了解了文档系统，请探索这些相关功能：

On this page