Başlarken

Markdown olarak görüntüle GitHub üzerinde düzenle Dokümantasyon: 7b38e05

Bu kılavuz, boş bir klasörden başlayarak Onedocs ile bir dokümantasyon sitesi kurar. Zaten bir Next.js projeniz varsa, mevcut dosyaları atlayıp geri kalanını karşılaştırın.

Ön koşullar

Node.js 20.9 veya üzeri (Next.js 16 tarafından gereklidir)
App Router ile Next.js 16, React 19.2 veya üzeri
Tailwind CSS v4 (Onedocs CSS ön ayarı tailwindcss öğesini içe aktarır)

Fumadocs UI 16 yalnızca Next.js 16 ve React 19.2 sürümlerini destekler; bu nedenle eski Next.js veya React sürümleri, onedocs paket meta verileri bunları hâlâ listelese de çalışmaz (#5).

Yükleme

Onedocs, Next.js veya Fumadocs paketini birlikte sunmaz. Bunlar eş bağımlılıklardır; bu nedenle yanlarına ayrıca yüklemeniz gerekir:

Kabuk

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 sabitlemesini koruyun. onedocs 0.1.27, ^0.562.0 öğesini lucide-react olarak tanımlar; sabitleme olmazsa npm lucide-react 1.x paketini yükler ve ERESOLVE hatasıyla durur (#1).

Aynı paketler pnpm, yarn veya bun ile de çalışır.

Next.js betiklerini package.json dosyasına ekleyin:

JSON

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

Proje yapısı

Sonunda elde edeceğiniz yapı şöyle:

Kod

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

Şimdi her dosyayı oluşturalım.

Yapılandırma dosyaları

onedocs.config.ts

Ana yapılandırma dosyanız. Yalnızca title gereklidir; geri kalanı için Yapılandırma bölümüne bakın.

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 öğesine içeriğinizin nerede bulunduğunu bildirir. İçerik klasörü yalnızca burada ayarlanır:

TypeScript

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

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

next.config.mjs

MDX işlemeyi etkinleştirir:

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX, Next.js başladığında source.config.ts kaynağından bir .source/ klasörü oluşturur. .source öğesini .gitignore dosyasına ekleyin.

postcss.config.mjs

Onedocs CSS ön ayarının temel aldığı Tailwind CSS v4 öğesini çalıştırır:

JavaScript

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

tsconfig.json

Aşağıdaki örnekler @/ kaynağından içe aktarır; bu nedenle onu src/ olarak eşleyin:

JSON

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

Next.js, next dev veya next build öğesini ilk kez çalıştırdığınızda bu dosyaya gereken diğer derleyici seçeneklerini ekler.

Kaynak kurulumu

src/lib/source.ts

Dokümantasyon içeriğinizi yükler:

TypeScript

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

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

Uygulama dosyaları

src/app/layout.tsx

Kök düzeniniz:

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 içindeki RootProvider, arama iletişim penceresini ve açık ile koyu temayı sağlar. FontHead, Inter Variable fontunu /fonts/InterVariable.woff2 kaynağından önceden yükler ve sayfa fontu olarak ayarlar. Onedocs font dosyasını içermez: Inter sürümleri bölümünden InterVariable.woff2 dosyasını indirip public/fonts/ konumuna koyun. Aksi halde metinde sistem sans-serif fontu kullanılır.

Bu meta verileri bunun yerine yapılandırmanızdan oluşturmak için API Referansı içindeki createMetadata bölümüne bakın.

src/app/globals.css

CSS ön ayarını içe aktarın:

CSS

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

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

Ön ayar, Tailwind CSS öğesini, Fumadocs UI stillerini ve Onedocs düzen stillerini yükler. @source yolları, globals.css konumuna göreli olarak tanımlanır; bu nedenle bu iki satır src/app/ konumunu ve proje kökündeki content/ klasörünü gösterir.

src/app/page.tsx

Ana sayfa. HomePage, yapılandırmanızdaki hero bölümünü, özellikleri ve altbilgiyi oluşturur:

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 ve bun için yükleme komutlarını hero bölümüne ekler. Projeniz bir paket değilse bunu eklemeyin.

src/app/docs/layout.tsx

Kenar çubuklu dokümantasyon düzeni:

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

Tek tek dokümantasyon sayfaları:

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,
  };
}

İçerik

content/docs/index.mdx

Her sayfanın frontmatter bölümünde bir title bulunmalıdır. description isteğe bağlıdır:

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

Kenar çubuğundaki sıralamayı belirler:

JSON

{
  "pages": ["index"]
}

Başka bir .mdx dosyası oluşturup adını pages içinde listeleyerek sayfa ekleyin.

Çalıştırma

Geliştirme sunucusunu başlatın:

Kabuk

npm run dev

Ana sayfa http://localhost:3000 adresinde, dokümantasyon ise http://localhost:3000/docs adresindedir.

Üretim için derleyin:

Kabuk

npm run build

Ardından SEO ve Arama bölümünde arama, site haritası ve llms.txt ekleyin.