コンテンツへスキップ

はじめに

Markdownとして表示 GitHubで編集 ドキュメント: 7b38e05

このガイドでは、空のフォルダーからOnedocsを使ったドキュメントサイトをセットアップします。すでにNext.jsプロジェクトがある場合は、用意済みのファイルを飛ばし、残りを確認してください。

前提条件

  • Node.js 20.9以降（Next.js 16で必須）
  • App Routerを備えたNext.js 16、またはReact 19.2以降
  • Tailwind CSS v4（OnedocsのCSSプリセットがtailwindcssを読み込みます）

Fumadocs UI 16が対応するのはNext.js 16とReact 19.2のみです。そのため、onedocsパッケージのメタデータに記載されていても、古いNext.jsやReactのバージョンは動作しません（#5）。

インストール

OnedocsにはNext.jsもFumadocsも同梱されていません。これらはピア依存関係のため、Onedocsと一緒にインストールします。

シェル
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

OnedocsのCSSプリセットの基盤であるTailwind CSS v4を実行します。

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/に配置してください。配置しない場合、テキストにはシステムのサンセリフフォントが使われます。

設定からこのメタデータを生成する方法については、APIリファレンスのcreateMetadataを参照してください。

src/app/globals.css

CSSプリセットをインポートします。

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

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

プリセットはTailwind CSS、FumadocsのUIスタイル、Onedocsのレイアウトスタイルを読み込みます。@sourceのパスはglobals.cssからの相対パスです。そのため、この2行は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

各ページのフロントマターには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ファイルをもう1つ作成し、その名前をpagesに記載すると、ページを追加できます。

実行

開発サーバーを起動します。

シェル
npm run dev

ホームページはhttp://localhost:3000、ドキュメントはhttp://localhost:3000/docsにあります。

本番用にビルドします。

シェル
npm run build

次に、SEOと検索で検索、サイトマップ、llms.txtを追加します。