Premiers pas

Afficher au format Markdown Modifier sur GitHub Documentation de 7b38e05

Ce guide vous accompagne dans la création d’un site de documentation avec Onedocs dans un dossier vide. Si vous avez déjà un projet Next.js, ignorez les fichiers déjà présents et comparez les autres.

Prérequis

Node.js 20.9 ou version ultérieure (requis par Next.js 16)
Next.js 16 avec App Router, React 19.2 ou version ultérieure
Tailwind CSS v4 (le préréglage Onedocs CSS importe tailwindcss)

Fumadocs UI 16 ne prend en charge que Next.js 16 et React 19.2 ; les versions antérieures de Next.js ou React ne fonctionnent donc pas, même si les métadonnées du paquet onedocs les répertorient encore (#5).

Installation

Onedocs n’intègre ni Next.js ni Fumadocs. Ce sont des dépendances homologues, à installer à ses côtés :

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

Conservez l’épinglage lucide-react@0.562. onedocs 0.1.27 déclare lucide-react ^0.562.0 comme dépendance homologue ; sans cet épinglage, npm installe lucide-react 1.x et s’arrête avec une erreur ERESOLVE (#1).

Les mêmes paquets fonctionnent avec pnpm, yarn ou bun.

Ajoutez les scripts Next.js à package.json :

JSON

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

Structure du projet

Voici la structure que vous obtiendrez :

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

Créons chaque fichier.

Fichiers de configuration

onedocs.config.ts

Votre fichier de configuration principal. Seul title est obligatoire ; consultez Configuration pour le reste.

TypeScript

import { defineConfig } from "onedocs/config";

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

source.config.ts

Indique à Fumadocs MDX où se trouve votre contenu. C’est le seul endroit où le dossier de contenu est défini :

TypeScript

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

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

next.config.mjs

Active le traitement MDX :

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX génère un dossier .source/ à partir de source.config.ts au démarrage de Next.js. Ajoutez .source à .gitignore.

postcss.config.mjs

Exécute Tailwind CSS v4, sur lequel repose le préréglage Onedocs CSS :

JavaScript

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

tsconfig.json

Les exemples ci-dessous importent depuis @/ ; associez-le donc à src/ :

JSON

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

Next.js ajoute à ce fichier les options de compilation restantes nécessaires lors de la première exécution de next dev ou next build.

Configuration de la source

src/lib/source.ts

Charge le contenu de votre documentation :

TypeScript

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

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

Fichiers de l’application

src/app/layout.tsx

Votre mise en page racine :

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 de Fumadocs UI fournit la boîte de dialogue de recherche et les thèmes clair et sombre. FontHead précharge la police Inter Variable depuis /fonts/InterVariable.woff2 et la définit comme police de la page. Onedocs ne fournit pas le fichier de police : téléchargez InterVariable.woff2 depuis les versions d’Inter et placez-le dans public/fonts/. Sans cela, le texte utilise la police sans empattement du système.

Pour générer ces métadonnées à partir de votre configuration, consultez createMetadata dans la référence API.

src/app/globals.css

Importez le préréglage CSS :

CSS

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

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

Le préréglage charge Tailwind CSS, les styles Fumadocs UI et les styles de mise en page Onedocs. Les chemins @source sont relatifs à globals.css ; ces deux lignes pointent donc vers src/app/ et vers le dossier content/ à la racine du projet.

src/app/page.tsx

La page d’accueil. HomePage affiche la bannière, les fonctionnalités et le pied de page à partir de votre configuration :

TSX

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

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

packageName ajoute à la bannière les commandes d’installation pour npm, yarn, pnpm et bun. Omettez-le si votre projet n’est pas un paquet.

src/app/docs/layout.tsx

Mise en page de la documentation avec barre latérale :

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

Pages de documentation individuelles :

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

Contenu

content/docs/index.mdx

Chaque page nécessite un title dans son frontmatter. Le description est facultatif :

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

Définit l’ordre de la barre latérale :

JSON

{
  "pages": ["index"]
}

Ajoutez une page en créant un autre fichier .mdx et en indiquant son nom dans pages.

Exécution

Démarrez le serveur de développement :

Shell

npm run dev

La page d’accueil se trouve à http://localhost:3000 et la documentation à http://localhost:3000/docs.

Générez la version de production :

Shell

npm run build

Ajoutez ensuite la recherche, un plan de site et llms.txt dans SEO et recherche.