快速入门

以 Markdown 格式查看在 GitHub 上编辑文档位置 7b38e05

本指南将从空文件夹开始，使用 Onedocs 搭建文档网站。如果你已有 Next.js 项目，请跳过已有文件，并参照其余步骤。

先决条件

Node.js 20.9 或更高版本（Next.js 16 的要求）
Next.js 16（使用 App Router），React 19.2 或更高版本
Tailwind CSS v4（Onedocs CSS 预设会导入 tailwindcss）

Fumadocs UI 16 仅支持 Next.js 16 和 React 19.2，因此较旧的 Next.js 或 React 版本无法使用，尽管 onedocs 包元数据仍列出了这些版本（问题 #5）。

安装

Onedocs 不会捆绑 Next.js 或 Fumadocs。它们是对等依赖项，因此需要与它一同安装：

命令行

npm install onedocs fumadocs-core fumadocs-mdx fumadocs-ui lucide-react@0.562 next react react-dom
npm install -D tailwindcss @tailwindcss/postcss typescript @types/react @types/react-dom @types/node

保留 lucide-react@0.562 固定版本。onedocs 0.1.27 将 lucide-react ^0.562.0 声明为对等依赖项；如果不固定版本，npm 会安装 lucide-react 1.x，并因 ERESOLVE 错误而停止（问题 #1）。

同一组包也适用于 pnpm、yarn 或 bun。

将 Next.js 脚本添加到 package.json：

JSON

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

项目结构

最终的项目结构如下：

代码

your-project/
├── content/
│   └── docs/
│       ├── index.mdx
│       └── meta.json
├── public/
│   └── fonts/
│       └── InterVariable.woff2
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   ├── globals.css
│   │   └── docs/
│   │       ├── layout.tsx
│   │       └── [[...slug]]/
│   │           └── page.tsx
│   └── lib/
│       └── source.ts
├── onedocs.config.ts
├── source.config.ts
├── next.config.mjs
├── postcss.config.mjs
├── tsconfig.json
└── package.json

现在来创建每个文件。

配置文件

onedocs.config.ts

你的主要配置文件。只有 title 是必需的；其他配置请参阅配置。

TypeScript

import { defineConfig } from "onedocs/config";

export default defineConfig({
  title: "My Docs",
  description: "Documentation for my project",
  nav: {
    github: "username/repo",
  },
});

source.config.ts

告诉 Fumadocs MDX 内容所在的位置。这是唯一设置内容文件夹的位置：

TypeScript

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

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

next.config.mjs

启用 MDX 处理：

JavaScript

import { createMDX } from "fumadocs-mdx/next";

const withMDX = createMDX();

/** @type {import('next').NextConfig} */
const config = {};

export default withMDX(config);

Fumadocs MDX 会在 Next.js 启动时，根据 source.config.ts 生成 .source/ 文件夹。将 .source 添加到 .gitignore 中。

postcss.config.mjs

运行 Tailwind CSS v4，这是 Onedocs CSS 预设的基础：

JavaScript

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

tsconfig.json

以下示例从 @/ 导入，因此请将其映射到 src/：

JSON

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

首次运行 next dev 或 next build 时，Next.js 会向此文件添加所需的其余编译器选项。

源设置

src/lib/source.ts

加载文档内容：

TypeScript

import { loader } from "fumadocs-core/source";
import { docs } from "../../.source/server";

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

应用文件

src/app/layout.tsx

你的根布局：

TSX

import type { Metadata } from "next";
import { RootProvider } from "fumadocs-ui/provider/next";
import { FontHead } from "onedocs";
import "./globals.css";

export const metadata: Metadata = {
  title: "My Docs",
  description: "Documentation for my project",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <FontHead />
      </head>
      <body className="antialiased">
        <RootProvider>{children}</RootProvider>
      </body>
    </html>
  );
}

来自 Fumadocs UI 的 RootProvider 提供搜索对话框和浅色、深色主题。FontHead 会从 /fonts/InterVariable.woff2 预加载 Inter Variable 字体，并将其设为页面字体。Onedocs 不会附带字体文件：请从 Inter 发布版本下载 InterVariable.woff2，并将其放入 public/fonts/。若未提供，文本会回退到系统无衬线字体。

如需改为根据配置生成此元数据，请参阅 createMetadata，位置在 API 参考中。

src/app/globals.css

导入 CSS 预设：

CSS

@import "onedocs/css/preset.css";

@source "./**/*.tsx";
@source "../../content/**/*.mdx";

此预设会加载 Tailwind CSS、Fumadocs UI 样式和 Onedocs 布局样式。@source 路径相对于 globals.css，因此这两行分别指向 src/app/ 和项目根目录中的 content/ 文件夹。

src/app/page.tsx

主页。HomePage 会根据你的配置渲染主视觉、功能介绍和页脚：

TSX

import { HomePage } from "onedocs";
import config from "../../onedocs.config";

export default function Home() {
  return <HomePage config={config} packageName="my-package" />;
}

packageName 会在主视觉中添加适用于 npm、yarn、pnpm 和 bun 的安装命令。如果你的项目不是一个包，请省略它。

src/app/docs/layout.tsx

带侧边栏的文档布局：

TSX

import { DocsLayout } from "onedocs";
import type { ReactNode } from "react";
import { source } from "@/lib/source";
import config from "../../../onedocs.config";

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <DocsLayout config={config} pageTree={source.pageTree}>
      {children}
    </DocsLayout>
  );
}

src/app/docs/[[...slug]]/page.tsx

单独的文档页面：

TSX

import { source } from "@/lib/source";
import { DocsPage, mdxComponents } from "onedocs";
import { notFound } from "next/navigation";

export default async function Page(props: {
  params: Promise<{ slug?: string[] }>;
}) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  const MDX = page.data.body;

  return (
    <DocsPage toc={page.data.toc}>
      <MDX components={mdxComponents} />
    </DocsPage>
  );
}

export async function generateStaticParams() {
  return source.generateParams();
}

export async function generateMetadata(props: {
  params: Promise<{ slug?: string[] }>;
}) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  return {
    title: page.data.title,
    description: page.data.description,
  };
}

内容

content/docs/index.mdx

每个页面都需要在 frontmatter 中设置 title。description 为可选项：

Mdx

---
title: Introduction
description: What this project does.
---

Welcome to the docs. Components such as `<Callout>` work without imports; see [Components](/docs/components).

content/docs/meta.json

设置侧边栏中的页面顺序：

JSON

{
  "pages": ["index"]
}

创建另一个 .mdx 文件并在 pages 中列出其名称，即可添加页面。

运行

启动开发服务器：

命令行

npm run dev

主页位于 http://localhost:3000，文档位于 http://localhost:3000/docs。

构建生产版本：

命令行

npm run build

接下来，在 SEO 与搜索中添加搜索、站点地图和 llms.txt。