Kom igång

Visa som Markdown Redigera på GitHub Dokumentation på 7b38e05

Den här guiden konfigurerar en dokumentationswebbplats med Onedocs från en tom mapp. Om du redan har ett Next.js-projekt hoppar du över de filer du redan har och jämför resten.

Förutsättningar

Node.js 20.9 eller senare (krävs av Next.js 16)
Next.js 16 med App Router, React 19.2 eller senare
Tailwind CSS v4 (förinställningen Onedocs CSS importerar tailwindcss)

Fumadocs UI 16 stöder endast Next.js 16 och React 19.2, så äldre versioner av Next.js eller React fungerar inte, trots att paketmetadata för onedocs fortfarande listar dem (#5).

Installation

Onedocs paketerar inte Next.js eller Fumadocs. De är peer-beroenden, så du installerar dem bredvid det:

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

Behåll lucide-react@0.562-låsningen. onedocs 0.1.27 deklarerar lucide-react ^0.562.0 som ett peer-beroende, och utan låsningen installerar npm lucide-react 1.x och avbryts med ett ERESOLVE-fel (#1).

Samma paket fungerar med pnpm, yarn eller bun.

Lägg till skripten Next.js i package.json:

JSON

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

Projektstruktur

Så här ser resultatet ut:

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

Nu skapar vi varje fil.

Konfigurationsfiler

onedocs.config.ts

Din huvudsakliga konfigurationsfil. Endast title krävs; se Konfiguration för resten.

TypeScript

import { defineConfig } from "onedocs/config";

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

source.config.ts

Talar om för Fumadocs MDX var innehållet finns. Det är den enda platsen där innehållsmappen anges:

TypeScript

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

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

next.config.mjs

Aktiverar MDX-bearbetning:

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX skapar en mapp .source/ från source.config.ts när Next.js startar. Lägg till .source i .gitignore.

postcss.config.mjs

Kör Tailwind CSS v4, som förinställningen Onedocs CSS bygger på:

JavaScript

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

tsconfig.json

Exemplen nedan importerar från @/, så mappa den till src/:

JSON

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

Next.js lägger till de återstående kompilatoralternativ som behövs i den här filen första gången du kör next dev eller next build.

Konfigurera källan

src/lib/source.ts

Läser in dokumentationsinnehållet:

TypeScript

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

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

Appfiler

src/app/layout.tsx

Din rotlayout:

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 från Fumadocs UI tillhandahåller sökdialogen och det ljusa och mörka temat. FontHead förladdar typsnittet Inter Variable från /fonts/InterVariable.woff2 och anger det som sidans typsnitt. Onedocs levereras inte med typsnittsfilen: ladda ner InterVariable.woff2 från Inter-releaser och placera den i public/fonts/. Utan filen används systemets sans serif-typsnitt som reserv.

Om du i stället vill skapa dessa metadata från din konfiguration, se createMetadata i API-referensen.

src/app/globals.css

Importera förinställningen CSS:

CSS

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

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

Förinställningen läser in Tailwind CSS, stilarna Fumadocs UI och layoutstilarna Onedocs. Sökvägarna @source är relativa till globals.css, så de här två raderna pekar på src/app/ och på mappen content/ i projektroten.

src/app/page.tsx

Startsidan. HomePage renderar huvudsektionen, funktionerna och sidfoten från din konfiguration:

TSX

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

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

packageName lägger till installationskommandon för npm, yarn, pnpm och bun i huvudsektionen. Utelämna den om projektet inte är ett paket.

src/app/docs/layout.tsx

Dokumentationslayout med sidofält:

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

Enskilda dokumentationssidor:

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

Innehåll

content/docs/index.mdx

Varje sida behöver en title i sin frontmatter. description är valfritt:

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

Anger sidofältets ordning:

JSON

{
  "pages": ["index"]
}

Lägg till en sida genom att skapa ytterligare en .mdx-fil och ange dess namn i pages.

Kör

Starta utvecklingsservern:

Shell

npm run dev

Startsidan finns på http://localhost:3000 och dokumentationen på http://localhost:3000/docs.

Bygg för produktion:

Shell

npm run build

Lägg sedan till sök, en webbplatskarta och llms.txt i SEO och sök.