Guida introduttiva

Visualizza come Markdown Modifica su GitHub Documentazione di 7b38e05

Questa guida configura un sito di documentazione con Onedocs partendo da una cartella vuota. Se avete già un progetto Next.js, saltate i file che possedete e confrontate gli altri.

Prerequisiti

Node.js 20.9 o versioni successive (richiesto da Next.js 16)
Next.js 16 con App Router, React 19.2 o versioni successive
Tailwind CSS v4 (il preset Onedocs CSS importa tailwindcss)

Fumadocs UI 16 supporta solo Next.js 16 e React 19.2, quindi le versioni precedenti di Next.js o React non funzionano, anche se i metadati del pacchetto onedocs le indicano ancora (#5).

Installazione

Onedocs non include Next.js né Fumadocs. Sono dipendenze peer, quindi vanno installate accanto al pacchetto:

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

Mantenete il pin lucide-react@0.562. onedocs 0.1.27 dichiara lucide-react ^0.562.0 come dipendenza peer e, senza il pin, npm installa lucide-react 1.x e si arresta con un errore ERESOLVE (#1).

Gli stessi pacchetti funzionano con pnpm, yarn o bun.

Aggiungete gli script Next.js a package.json:

JSON

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

Struttura del progetto

Ecco cosa otterrete:

Codice

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

Creiamo ora ciascun file.

File di configurazione

onedocs.config.ts

Il file di configurazione principale. È richiesto solo title; per il resto, consultate Configurazione.

TypeScript

import { defineConfig } from "onedocs/config";

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

source.config.ts

Indica a Fumadocs MDX dove si trovano i contenuti. È l'unico punto in cui si imposta la cartella dei contenuti:

TypeScript

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

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

next.config.mjs

Abilita l'elaborazione di MDX:

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX genera una cartella .source/ da source.config.ts all'avvio di Next.js. Aggiungete .source a .gitignore.

postcss.config.mjs

Esegue Tailwind CSS v4, su cui si basa il preset Onedocs CSS:

JavaScript

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

tsconfig.json

Gli esempi seguenti importano da @/, quindi associatelo a src/:

JSON

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

La prima volta che eseguite next dev o next build, Next.js aggiunge a questo file le opzioni del compilatore mancanti.

Configurazione della sorgente

src/lib/source.ts

Carica i contenuti della documentazione:

TypeScript

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

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

File dell'app

src/app/layout.tsx

Il layout principale:

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 di Fumadocs UI fornisce il dialogo di ricerca e il tema chiaro e scuro. FontHead precarica il font Inter Variable da /fonts/InterVariable.woff2 e lo imposta come font della pagina. Onedocs non include il file del font: scaricate InterVariable.woff2 dalle release di Inter e inseritelo in public/fonts/. In sua assenza, il testo usa il font sans-serif di sistema.

Per generare questi metadati dalla configurazione, consultate createMetadata nel API Reference.

src/app/globals.css

Importate il preset CSS:

CSS

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

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

Il preset carica Tailwind CSS, gli stili Fumadocs UI e gli stili del layout Onedocs. I percorsi @source sono relativi a globals.css, quindi queste due righe puntano a src/app/ e alla cartella content/ nella radice del progetto.

src/app/page.tsx

La home page. HomePage visualizza la sezione principale, le funzionalità e il piè di pagina definiti nella configurazione:

TSX

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

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

packageName aggiunge alla sezione principale i comandi di installazione per npm, yarn, pnpm e bun. Omettetelo se il progetto non è un pacchetto.

src/app/docs/layout.tsx

Layout della documentazione con barra laterale:

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

Pagine singole della documentazione:

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

Contenuto

content/docs/index.mdx

Ogni pagina deve avere un title nel frontmatter. description è facoltativo:

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

Imposta l'ordine della barra laterale:

JSON

{
  "pages": ["index"]
}

Aggiungete una pagina creando un altro file .mdx e inserendone il nome in pages.

Esecuzione

Avviate il server di sviluppo:

Shell

npm run dev

La home page si trova in http://localhost:3000 e la documentazione in http://localhost:3000/docs.

Compilate per la produzione:

Shell

npm run build

Poi aggiungete la ricerca, una sitemap e llms.txt in SEO e ricerca.