Primii pași

Vizualizați ca Markdown Editați pe GitHub Documentație la 7b38e05

Acest ghid configurează un site de documentație cu Onedocs pornind de la un dosar gol. Dacă aveți deja un proiect Next.js, omiteți fișierele existente și comparați restul.

Cerințe preliminare

Node.js 20.9 sau o versiune ulterioară (necesară pentru Next.js 16)
Next.js 16 cu App Router, React 19.2 sau o versiune ulterioară
Tailwind CSS v4 (presetarea Onedocs CSS importă tailwindcss)

Fumadocs UI 16 acceptă doar Next.js 16 și React 19.2, așadar versiunile mai vechi de Next.js sau React nu funcționează, chiar dacă metadatele pachetului onedocs încă le enumeră (Problema #5).

Instalare

Onedocs nu include Next.js sau Fumadocs. Acestea sunt dependențe peer, deci trebuie instalate alături de acesta:

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

Păstrați fixarea lucide-react@0.562. onedocs 0.1.27 declară lucide-react ^0.562.0 drept dependență peer, iar fără fixare npm instalează lucide-react 1.x și se oprește cu o eroare ERESOLVE (Problema #1).

Aceleași pachete funcționează cu pnpm, yarn sau bun.

Adăugați scripturile Next.js la package.json:

JSON

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

Structura proiectului

Iată ce veți obține la final:

Cod

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

Să creăm fiecare fișier.

Fișiere de configurare

onedocs.config.ts

Fișierul principal de configurare. Este necesar doar title; consultați Configurare pentru restul.

TypeScript

import { defineConfig } from "onedocs/config";

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

source.config.ts

Îi indică lui Fumadocs MDX unde se află conținutul. Acesta este singurul loc în care se setează dosarul de conținut:

TypeScript

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

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

next.config.mjs

Activează procesarea MDX:

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX generează un dosar .source/ din source.config.ts la pornirea lui Next.js. Adăugați .source la .gitignore.

postcss.config.mjs

Rulează Tailwind CSS v4, pe care se bazează presetarea Onedocs CSS:

JavaScript

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

tsconfig.json

Exemplele de mai jos importă din @/, așadar mapați-l la src/:

JSON

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

Next.js adaugă la acest fișier opțiunile de compilare rămase de care are nevoie, la prima rulare a next dev sau next build.

Configurarea sursei

src/lib/source.ts

Încarcă conținutul documentației:

TypeScript

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

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

Fișierele aplicației

src/app/layout.tsx

Layoutul rădăcină:

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 din Fumadocs UI furnizează dialogul de căutare și temele luminoasă și întunecată. FontHead preîncarcă fontul Inter Variable din /fonts/InterVariable.woff2 și îl setează ca font al paginii. Onedocs nu include fișierul fontului: descărcați InterVariable.woff2 din Versiuni Inter și plasați-l în public/fonts/. Fără acesta, textul folosește fontul sans-serif implicit al sistemului.

Pentru a genera aceste metadate în schimb din configurația voastră, consultați createMetadata din APIReferință.

src/app/globals.css

Importați presetarea CSS:

CSS

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

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

Presetarea încarcă Tailwind CSS, stilurile Fumadocs UI și stilurile de layout Onedocs. Căile @source sunt relative la globals.css, așadar aceste două linii indică spre src/app/ și spre dosarul content/ din rădăcina proiectului.

src/app/page.tsx

Pagina principală. HomePage randează secțiunea principală, funcționalitățile și subsolul din configurația voastră:

TSX

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

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

packageName adaugă la secțiunea principală comenzi de instalare pentru npm, yarn, pnpm și bun. Omiteți-l dacă proiectul vostru nu este un pachet.

src/app/docs/layout.tsx

Layoutul documentației cu bara laterală:

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

Pagini individuale de documentație:

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

Conținut

content/docs/index.mdx

Fiecare pagină are nevoie de un title în frontmatter. description este opțional:

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

Stabilește ordinea barei laterale:

JSON

{
  "pages": ["index"]
}

Adăugați o pagină creând un alt fișier .mdx și enumerându-i numele în pages.

Rulare

Porniți serverul de dezvoltare:

Shell

npm run dev

Pagina principală se află la http://localhost:3000, iar documentația la http://localhost:3000/docs.

Creați versiunea pentru producție:

Shell

npm run build

Apoi adăugați căutarea, o hartă a site-ului și llms.txt în SEO și căutare.