Erste Schritte

Als Markdown anzeigen Auf GitHub bearbeiten Dokumentation zu 7b38e05

Diese Anleitung richtet in einem leeren Ordner eine Dokumentationswebsite mit Onedocs ein. Wenn du bereits ein Next.js-Projekt hast, überspringe vorhandene Dateien und vergleiche die übrigen.

Voraussetzungen

Node.js 20.9 oder neuer (erforderlich für Next.js 16)
Next.js 16 mit App Router, React 19.2 oder neuer
Tailwind CSS v4 (das Onedocs-CSS-Preset importiert tailwindcss)

Fumadocs UI 16 unterstützt nur Next.js 16 und React 19.2. Ältere Versionen von Next.js oder React funktionieren daher nicht, obwohl sie in den Metadaten des onedocs-Pakets noch aufgeführt sind (#5).

Installation

Onedocs bündelt weder Next.js noch Fumadocs. Beides sind Peer-Abhängigkeiten und muss daher zusätzlich installiert werden:

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

Behalte die Versionsfixierung für lucide-react@0.562 bei. onedocs 0.1.27 deklariert lucide-react ^0.562.0 als Peer-Abhängigkeit. Ohne die Fixierung installiert npm lucide-react 1.x und bricht mit einem ERESOLVE-Fehler ab (#1).

Dieselben Pakete funktionieren mit pnpm, yarn oder bun.

Füge die Next.js-Skripte zu package.json hinzu:

JSON

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

Projektstruktur

So sieht das Ergebnis aus:

Code

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

Erstellen wir nun die einzelnen Dateien.

Konfigurationsdateien

onedocs.config.ts

Deine Hauptkonfigurationsdatei. Nur title ist erforderlich. Die übrigen Optionen findest du unter Konfiguration.

TypeScript

import { defineConfig } from "onedocs/config";

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

source.config.ts

Gibt Fumadocs MDX den Speicherort deiner Inhalte an. Nur hier wird der Inhaltsordner festgelegt:

TypeScript

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

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

next.config.mjs

Aktiviert die Verarbeitung von MDX:

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX erstellt beim Start von Next.js aus source.config.ts einen .source/-Ordner. Füge .source zu .gitignore hinzu.

postcss.config.mjs

Führt Tailwind CSS v4 aus, auf dem das Onedocs-CSS-Preset basiert:

JavaScript

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

tsconfig.json

Die folgenden Beispiele importieren aus @/. Weise ihm daher src/ zu:

JSON

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

Next.js ergänzt diese Datei beim ersten Aufruf von next dev oder next build um die übrigen benötigten Compileroptionen.

Quelle einrichten

src/lib/source.ts

Lädt deine Doku-Inhalte:

TypeScript

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

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

App-Dateien

src/app/layout.tsx

Dein Root-Layout:

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 aus Fumadocs UI stellt den Suchdialog sowie das helle und dunkle Theme bereit. FontHead lädt die Schriftart Inter Variable von /fonts/InterVariable.woff2 vor und legt sie als Seitenschriftart fest. Onedocs enthält die Schriftdatei nicht. Lade InterVariable.woff2 aus den Inter-Releases herunter und lege sie in public/fonts/ ab. Andernfalls wird die Systemschrift ohne Serifen verwendet.

Wie du diese Metadaten stattdessen aus deiner Konfiguration erstellst, erfährst du unter createMetadata in der API-Referenz.

src/app/globals.css

Importiere das CSS-Preset:

CSS

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

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

Das Preset lädt Tailwind CSS, die Fumadocs-UI-Styles und die Onedocs-Layout-Styles. @source-Pfade sind relativ zu globals.css. Die beiden Zeilen verweisen also auf src/app/ und auf den content/-Ordner im Projektstammverzeichnis.

src/app/page.tsx

Die Startseite. HomePage rendert Hero-Bereich, Features und Fußzeile aus deiner Konfiguration:

TSX

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

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

packageName fügt dem Hero-Bereich Installationsbefehle für npm, yarn, pnpm und bun hinzu. Lass es weg, wenn dein Projekt kein Paket ist.

src/app/docs/layout.tsx

Docs-Layout mit Seitenleiste:

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

Einzelne Docs-Seiten:

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

Inhalte

content/docs/index.mdx

Jede Seite benötigt ein title in ihren Frontmatter-Angaben. description ist optional:

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

Legt die Reihenfolge der Seitenleiste fest:

JSON

{
  "pages": ["index"]
}

Erstelle eine weitere .mdx-Datei und trage ihren Namen in pages ein, um eine Seite hinzuzufügen.

Ausführen

Starte den Entwicklungsserver:

Shell

npm run dev

Die Startseite findest du unter http://localhost:3000, die Doku unter http://localhost:3000/docs.

Erstelle einen Produktions-Build:

Shell

npm run build

Füge als Nächstes die Suche, eine Sitemap und llms.txt hinzu. Siehe SEO und Suche.