Aan de slag

Bekijken als Markdown Bewerken op GitHub Documentatie op 7b38e05

Deze handleiding helpt u een documentatiesite met Onedocs op te zetten vanuit een lege map. Hebt u al een Next.js-project, sla dan de bestanden over die u al hebt en vergelijk de rest.

Vereisten

Node.js 20.9 of hoger (vereist door Next.js 16)
Next.js 16 met de App Router, React 19.2 of hoger
Tailwind CSS v4 (de preset Onedocs CSS importeert tailwindcss)

Fumadocs UI 16 ondersteunt alleen Next.js 16 en React 19.2. Oudere versies van Next.js of React werken dus niet, ook al vermeldt de pakketmetadata van onedocs ze nog (#5).

Installeren

Onedocs bevat Next.js of Fumadocs niet. Dit zijn peer dependencies, dus u installeert ze ernaast:

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

Behoud de lucide-react@0.562-vastzetting. onedocs 0.1.27 declareert lucide-react ^0.562.0 als peer dependency. Zonder de vastzetting installeert npm lucide-react 1.x en stopt het met een foutmelding ERESOLVE (#1).

Dezelfde pakketten werken met pnpm, yarn of bun.

Voeg de scripts Next.js toe aan package.json:

JSON

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

Projectstructuur

Dit is het resultaat:

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

Laten we elk bestand maken.

Configuratiebestanden

onedocs.config.ts

Uw hoofdconfiguratiebestand. Alleen title is vereist; zie Configuratie voor de rest.

TypeScript

import { defineConfig } from "onedocs/config";

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

source.config.ts

Geeft aan Fumadocs MDX waar uw content staat. Dit is de enige plek waar de contentmap wordt ingesteld:

TypeScript

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

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

next.config.mjs

Schakelt de verwerking van MDX in:

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX genereert bij het starten van Next.js een map .source/ vanuit source.config.ts. Voeg .source toe aan .gitignore.

postcss.config.mjs

Voert Tailwind CSS v4 uit, waarop de preset Onedocs CSS is gebaseerd:

JavaScript

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

tsconfig.json

De voorbeelden hieronder importeren uit @/; koppel dit daarom aan src/:

JSON

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

De eerste keer dat u next dev of next build uitvoert, voegt Next.js de overige compileropties die het nodig heeft aan dit bestand toe.

Bron instellen

src/lib/source.ts

Laadt uw documentatiecontent:

TypeScript

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

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

App-bestanden

src/app/layout.tsx

Uw hoofdlayout:

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 uit Fumadocs UI levert het zoekvenster en het lichte en donkere thema. FontHead laadt vooraf het lettertype Inter Variable van /fonts/InterVariable.woff2 en stelt het in als paginalettertype. Onedocs levert het lettertypebestand niet mee: download InterVariable.woff2 via Inter-releases en plaats het in public/fonts/. Zonder dit bestand valt de tekst terug op het systeemlettertype zonder schreef.

Zie createMetadata in de API-referentie als u deze metadata liever op basis van uw configuratie opbouwt.

src/app/globals.css

Importeer de preset CSS:

CSS

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

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

De preset laadt Tailwind CSS, de stijlen van Fumadocs UI en de layoutstijlen van Onedocs. Paden @source zijn relatief aan globals.css; deze twee regels verwijzen dus naar src/app/ en naar de map content/ in de hoofdmap van het project.

src/app/page.tsx

De startpagina. HomePage geeft de hero, functies en voettekst uit uw configuratie weer:

TSX

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

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

packageName voegt installatieopdrachten voor npm, yarn, pnpm en bun toe aan de hero. Laat dit weg als uw project geen pakket is.

src/app/docs/layout.tsx

Documentatielayout met zijbalk:

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

Afzonderlijke documentatiepagina's:

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

Inhoud

content/docs/index.mdx

Elke pagina heeft een title nodig in de frontmatter. De description is optioneel:

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

Bepaalt de volgorde van de zijbalk:

JSON

{
  "pages": ["index"]
}

Voeg een pagina toe door nog een bestand .mdx aan te maken en de naam ervan in pages te vermelden.

Uitvoeren

Start de ontwikkelserver:

Shell

npm run dev

De startpagina staat op http://localhost:3000 en de documentatie op http://localhost:3000/docs.

Bouw voor productie:

Shell

npm run build

Voeg vervolgens zoeken, een sitemap en llms.txt toe in SEO en zoeken.