Memulai

Lihat sebagai Markdown Edit di GitHub Dokumentasi di 7b38e05

Panduan ini menyiapkan situs dokumentasi dengan Onedocs dari folder kosong. Jika Anda sudah memiliki proyek Next.js, lewati file yang sudah ada dan bandingkan sisanya.

Prasyarat

Node.js 20.9 atau yang lebih baru (diperlukan oleh Next.js 16)
Next.js 16 dengan App Router, React 19.2 atau yang lebih baru
Tailwind CSS v4 (preset Onedocs CSS mengimpor tailwindcss)

Fumadocs UI 16 hanya mendukung Next.js 16 dan React 19.2, jadi versi Next.js atau React yang lebih lama tidak berfungsi meskipun metadata paket onedocs masih mencantumkannya (#5).

Instalasi

Onedocs tidak menyertakan Next.js atau Fumadocs. Keduanya adalah dependensi peer, jadi instal bersama paket ini:

Shell

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

Pertahankan pin lucide-react@0.562. onedocs 0.1.27 menetapkan lucide-react ^0.562.0 sebagai peer, dan tanpa pin tersebut npm menginstal lucide-react 1.x lalu berhenti dengan error ERESOLVE (#1).

Paket yang sama berfungsi dengan pnpm, yarn, atau bun.

Tambahkan skrip Next.js ke package.json:

JSON

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

Struktur proyek

Berikut hasil akhirnya:

Kode

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

Mari buat setiap file.

File konfigurasi

onedocs.config.ts

File konfigurasi utama Anda. Hanya title yang diperlukan; lihat Konfigurasi untuk sisanya.

TypeScript

import { defineConfig } from "onedocs/config";

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

source.config.ts

Memberi tahu Fumadocs MDX tempat konten Anda berada. Hanya di sinilah folder konten ditetapkan:

TypeScript

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

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

next.config.mjs

Mengaktifkan pemrosesan MDX:

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX membuat folder .source/ dari source.config.ts saat Next.js dijalankan. Tambahkan .source ke .gitignore.

postcss.config.mjs

Menjalankan Tailwind CSS v4, yang menjadi dasar preset Onedocs CSS:

JavaScript

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

tsconfig.json

Contoh di bawah mengimpor dari @/, jadi petakan ke src/:

JSON

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

Next.js menambahkan opsi compiler lain yang diperlukan ke file ini saat pertama kali Anda menjalankan next dev atau next build.

Penyiapan sumber

src/lib/source.ts

Memuat konten dokumentasi Anda:

TypeScript

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

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

File aplikasi

src/app/layout.tsx

Tata letak root Anda:

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

RootProvider dari Fumadocs UI menyediakan dialog pencarian serta tema terang dan gelap. FontHead memuat awal font Inter Variable dari /fonts/InterVariable.woff2 dan menetapkannya sebagai font halaman. Onedocs tidak menyertakan file font: unduh InterVariable.woff2 dari rilis Inter dan letakkan di public/fonts/. Tanpanya, teks akan menggunakan font sans-serif sistem.

Untuk membuat metadata ini dari config Anda, lihat createMetadata di API Referensi.

src/app/globals.css

Impor preset CSS:

CSS

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

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

Preset memuat Tailwind CSS, gaya Fumadocs UI, dan gaya tata letak Onedocs. Jalur @source bersifat relatif terhadap globals.css, jadi kedua baris ini mengarah ke src/app/ dan folder content/ di root proyek.

src/app/page.tsx

Halaman beranda. HomePage merender hero, fitur, dan footer dari config Anda:

TSX

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

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

packageName menambahkan perintah instalasi untuk npm, yarn, pnpm, dan bun ke hero. Abaikan jika proyek Anda bukan sebuah paket.

src/app/docs/layout.tsx

Tata letak dokumentasi dengan sidebar:

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

Halaman dokumentasi individual:

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

Konten

content/docs/index.mdx

Setiap halaman memerlukan title di frontmatter-nya. description bersifat opsional:

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

Menetapkan urutan sidebar:

JSON

{
  "pages": ["index"]
}

Tambahkan halaman dengan membuat file .mdx lain dan mencantumkan namanya di pages.

Jalankan

Mulai server pengembangan:

Shell

npm run dev

Halaman beranda ada di http://localhost:3000 dan dokumentasi ada di http://localhost:3000/docs.

Build untuk produksi:

Shell

npm run build

Selanjutnya, tambahkan pencarian, sitemap, dan llms.txt di SEO & Pencarian.