La documentation est la vitrine publique de tout produit destiné aux développeurs. Un excellent site de documentation transforme les visiteurs curieux en clients payants, tandis qu'un site lent ou confus les fait fuir discrètement. En 2026, une nouvelle génération de frameworks de documentation a émergé, et Fumadocs est rapidement devenu le choix favori des équipes qui utilisent Next.js. Il offre une esthétique digne de Mintlify, un support MDX profond, une recherche full-text, et aucun verrouillage propriétaire — le tout sur l'App Router que vous connaissez déjà.

Dans ce tutoriel, nous allons construire un site de documentation complet à partir de zéro avec Fumadocs et Next.js 15. À la fin, vous aurez une plateforme de documentation prête pour la production avec versionnage, mode sombre, recherche instantanée, onglets de groupe de code, encadrés, composants MDX personnalisés et un explorateur OpenAPI.

Prérequis

Avant de commencer, assurez-vous d'avoir :

Node.js 20 ou plus récent installé
Une connaissance pratique de React et de l'App Router de Next.js
Une familiarité avec TypeScript et MDX
Un éditeur de code (VS Code avec l'extension MDX est recommandé)
Un terminal et Git

Ce tutoriel suppose une connaissance intermédiaire de Next.js 15. Si vous découvrez l'App Router, consultez d'abord la documentation officielle de Next.js.

Ce que vous allez construire

Nous allons créer NoqtaDocs, un site de documentation fictif pour une plateforme API interne. À la fin, le site disposera :

D'une page d'accueil soignée avec un hero et des cartes de fonctionnalités
D'une navigation latérale qui reflète la structure des dossiers
De pages MDX avec composants personnalisés (encadrés, onglets, arborescences de fichiers)
D'une recherche full-text côté client propulsée par Orama
Du mode sombre et d'un thème accessible
D'une page d'exploration OpenAPI
D'un sélecteur de versions pour v1 et v2 de l'API
D'un export statique prêt à déployer sur Vercel ou Cloudflare

Pourquoi Fumadocs en 2026

Il y a trois ans, la plupart des équipes optaient pour Mintlify, GitBook, ou un site Next.js fait main. Chaque option avait ses compromis. Mintlify vous enfermait dans un modèle SaaS, GitBook semblait lent pour les docs riches en code, et les sites maison exigeaient de réinventer la recherche, les thèmes et la navigation à chaque fois.

Fumadocs résout ces trois problèmes d'un seul coup. C'est une bibliothèque, pas une plateforme, donc vous possédez votre code. Il propose un support de premier ordre pour l'App Router, les composants serveur, MDX 3 et la compatibilité totale avec Tailwind CSS v4. Le thème par défaut est superbe dès l'installation, mais chaque composant est personnalisable.

Comparé à Nextra 4, Fumadocs offre un contrôle plus fin sur le routage et les layouts, et son algorithme de parcours d'arbre produit des builds plus rapides sur de grands ensembles de documents. Comparé à Starlight, il reste dans l'écosystème Next.js, ce qui signifie que vous pouvez colocaliser pages marketing, tableaux de bord et docs dans le même monorepo.

Étape 1 : Configuration du projet

Commençons par créer un nouveau projet Next.js 15. Ouvrez votre terminal et lancez la commande de scaffolding Fumadocs, qui configure tout pour vous.

npx create-fumadocs-app@latest noqtadocs

Le CLI vous posera plusieurs questions. Pour ce tutoriel, choisissez :

Framework : Next.js
Source de contenu : Fumadocs MDX
Tailwind CSS : Oui
Installer les dépendances : Oui

Une fois l'installation terminée, accédez au projet et démarrez le serveur de développement.

cd noqtadocs
npm run dev

Ouvrez http://localhost:3000 dans votre navigateur. Vous devriez voir la page d'accueil Fumadocs par défaut avec une barre latérale déjà remplie de fichiers MDX d'exemple.

Aperçu de la structure des dossiers

Le scaffolding produit une structure propre et prévisible.

noqtadocs/
├── app/
│   ├── (home)/
│   │   └── page.tsx
│   ├── docs/
│   │   ├── [[...slug]]/
│   │   │   └── page.tsx
│   │   └── layout.tsx
│   ├── api/
│   │   └── search/
│   │       └── route.ts
│   ├── layout.config.tsx
│   └── layout.tsx
├── content/
│   └── docs/
│       ├── index.mdx
│       └── test.mdx
├── lib/
│   └── source.ts
├── source.config.ts
└── package.json

Les fichiers clés à retenir :

source.config.ts — déclare vos collections de contenu et le schéma frontmatter
lib/source.ts — exporte l'objet source utilisé pour lire vos docs
app/docs/[[...slug]]/page.tsx — la route dynamique qui rend chaque page de doc
app/api/search/route.ts — le point de terminaison de recherche Orama intégré
content/docs/ — où vivent vos fichiers MDX

Étape 2 : Configurer votre source de contenu

Ouvrez source.config.ts. Ce fichier indique à Fumadocs comment analyser votre MDX, quel frontmatter attendre et comment générer l'index de recherche.

import { defineDocs, defineConfig } from "fumadocs-mdx/config";
import { z } from "zod";
 
export const docs = defineDocs({
  dir: "content/docs",
  docs: {
    schema: z.object({
      title: z.string(),
      description: z.string().optional(),
      icon: z.string().optional(),
      version: z.enum(["v1", "v2"]).default("v2"),
    }),
  },
});
 
export default defineConfig({
  mdxOptions: {
    rehypeCodeOptions: {
      themes: {
        light: "github-light",
        dark: "github-dark",
      },
    },
  },
});

Nous avons ajouté un champ version personnalisé au schéma frontmatter. Nous l'utiliserons plus tard pour activer le sélecteur de versions. Le bloc rehypeCodeOptions active la coloration syntaxique Shiki avec des thèmes clair et sombre, qui s'adapte automatiquement au schéma de couleurs de l'utilisateur.

Redémarrez le serveur de développement pour que le changement de schéma prenne effet.

npm run dev

Fumadocs dérive la navigation directement de la structure de vos dossiers. Pour regrouper les docs en sections, créez un fichier meta.json dans chaque dossier. Remplacez le contenu de content/docs/ par la structure suivante.

content/docs/
├── index.mdx
├── meta.json
├── getting-started/
│   ├── meta.json
│   ├── installation.mdx
│   └── quickstart.mdx
├── guides/
│   ├── meta.json
│   ├── authentication.mdx
│   └── webhooks.mdx
└── reference/
    ├── meta.json
    └── openapi.mdx

Voici le meta.json racine :

{
  "title": "NoqtaDocs",
  "pages": [
    "index",
    "---Getting Started---",
    "getting-started",
    "---Guides---",
    "guides",
    "---Reference---",
    "reference"
  ]
}

La syntaxe ---Titre--- crée des séparateurs de section dans la barre latérale. L'ordre du tableau contrôle l'ordre visuel. Ce contrôle explicite est ce qui rend Fumadocs curated plutôt que chaotique alphabétiquement.

Dans chaque sous-dossier, ajoutez un meta.json qui liste les pages.

{
  "title": "Getting Started",
  "pages": ["installation", "quickstart"]
}

Étape 4 : Rédiger vos premières pages de documentation

Ajoutons du contenu réel. Ouvrez content/docs/getting-started/installation.mdx et collez ce qui suit.

---
title: Installation
description: Installer le SDK Noqta dans votre projet
icon: Download
---
 
Le SDK Noqta est publié sur npm et prend en charge Node.js 20 et plus récent.
 
## Installer avec votre gestionnaire de paquets
 
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
 
<Tabs items={["npm", "pnpm", "bun"]}>
  <Tab value="npm">```bash npm install @noqta/sdk ```</Tab>
  <Tab value="pnpm">```bash pnpm add @noqta/sdk ```</Tab>
  <Tab value="bun">```bash bun add @noqta/sdk ```</Tab>
</Tabs>
 
## Vérifier l'installation
 
Créez un petit script de test et exécutez-le.
 
```typescript
import { NoqtaClient } from "@noqta/sdk";
 
const client = new NoqtaClient({ apiKey: process.env.NOQTA_API_KEY });
const status = await client.health.check();
console.log(status);

Si tout est correctement configuré, vous verrez une réponse JSON confirmant la connexion.


Le composant `Tabs` est l'un des dizaines livrés avec `fumadocs-ui`. Chaque onglet peut héberger n'importe quel contenu MDX, y compris d'autres blocs de code, des tableaux ou des images.

## Étape 5 : Ajouter des encadrés et arborescences de fichiers

Fumadocs propose un riche ensemble de composants MDX. Les deux plus utiles sont `Callout` et `Files`. Ajoutez une nouvelle section à votre page d'installation.

```mdx
import { Callout } from "fumadocs-ui/components/callout";
import { Files, Folder, File } from "fumadocs-ui/components/files";

<Callout type="info">
  Le SDK est livré avec les types TypeScript dès le départ. Aucune installation supplémentaire nécessaire.
</Callout>

<Callout type="warn">
  Ne committez jamais votre clé API dans git. Utilisez plutôt des variables d'environnement.
</Callout>

## Structure du projet

Après l'installation, votre projet devrait ressembler à ceci.

<Files>
  <Folder name="src" defaultOpen>
    <File name="index.ts" />
    <Folder name="lib">
      <File name="noqta.ts" />
    </Folder>
  </Folder>
  <File name=".env.local" />
  <File name="package.json" />
</Files>

Sauvegardez le fichier et rafraîchissez votre navigateur. Les encadrés s'affichent avec des bordures colorées et l'arborescence est interactive — les dossiers peuvent être étendus et réduits.

Étape 6 : Personnaliser le layout

Ouvrez app/layout.config.tsx. Ce fichier contrôle le layout global : la barre de navigation supérieure, l'en-tête de la barre latérale et le lien GitHub.

import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
 
export const baseOptions: BaseLayoutProps = {
  nav: {
    title: (
      <span className="font-semibold">
        NoqtaDocs
      </span>
    ),
  },
  links: [
    { text: "Documentation", url: "/docs" },
    { text: "Blog", url: "/blog" },
    { text: "Changelog", url: "/changelog" },
  ],
  githubUrl: "https://github.com/your-org/noqtadocs",
};

La barre supérieure affiche maintenant votre marque et les liens externes. Comme tout est rendu côté serveur, ces éléments changent instantanément sans flash côté client.

Étape 7 : Implémenter la recherche full-text

Le scaffolding inclut déjà une recherche propulsée par Orama dans app/api/search/route.ts. Ouvrez-le et confirmez qu'il ressemble à ceci.

import { source } from "@/lib/source";
import { createFromSource } from "fumadocs-core/search/server";
 
export const { GET } = createFromSource(source);

C'est tout le code nécessaire. Fumadocs parcourt votre arborescence de contenu, extrait les titres et construit un index Orama en mémoire. Les résultats de recherche incluent une mise en évidence riche des termes correspondants.

Pour ouvrir la boîte de dialogue de recherche, appuyez sur Cmd+K ou Ctrl+K. Les résultats sont regroupés par page et affichent le titre correspondant, ce qui rend triviale la création de liens profonds vers des sections spécifiques.

Pour des ensembles de docs plus volumineux dépassant mille pages, basculez vers les adaptateurs Algolia ou Trieve. La même API createFromSource est utilisée, avec un backend différent.

Étape 8 : Ajouter une belle page d'accueil

La page d'accueil par défaut est un placeholder. Remplacez app/(home)/page.tsx par un hero, une grille de fonctionnalités et un appel à l'action.

import Link from "next/link";
 
export default function HomePage() {
  return (
    <main className="flex flex-1 flex-col">
      <section className="container flex flex-col items-center gap-6 py-24 text-center">
        <h1 className="text-5xl font-bold tracking-tight">
          La façon la plus rapide de livrer des docs.
        </h1>
        <p className="max-w-2xl text-lg text-fd-muted-foreground">
          NoqtaDocs est une plateforme de documentation construite sur Fumadocs et Next.js 15.
          Aucun verrouillage propriétaire, des défauts magnifiques, recherche instantanée.
        </p>
        <div className="flex gap-4">
          <Link
            href="/docs"
            className="rounded-md bg-fd-primary px-6 py-3 font-medium text-fd-primary-foreground"
          >
            Lire la documentation
          </Link>
          <Link
            href="https://github.com/your-org/noqtadocs"
            className="rounded-md border px-6 py-3 font-medium"
          >
            Voir sur GitHub
          </Link>
        </div>
      </section>
    </main>
  );
}

Notez les jetons de design préfixés par fd-. Fumadocs propose un système complet de variables CSS qui s'adapte automatiquement aux modes clair et sombre. Utilisez ces jetons au lieu de coder en dur les couleurs.

Étape 9 : Implémenter le sélecteur de versions

La documentation d'API doit souvent prendre en charge plusieurs versions. Nous avons ajouté un champ version au frontmatter plus tôt. Maintenant, nous allons l'utiliser pour filtrer les pages.

Créez un nouveau fichier lib/source.ts s'il n'existe pas déjà.

import { docs } from "@/.source";
import { loader } from "fumadocs-core/source";
 
export const source = loader({
  baseUrl: "/docs",
  source: docs.toFumadocsSource(),
});
 
export function getVersionPages(version: "v1" | "v2") {
  return source.getPages().filter((page) => page.data.version === version);
}

Ajoutez un sélecteur de versions à la barre latérale en créant app/docs/layout.tsx.

import { DocsLayout } from "fumadocs-ui/layouts/docs";
import { source } from "@/lib/source";
import { baseOptions } from "@/app/layout.config";
 
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <DocsLayout
      tree={source.pageTree}
      sidebar={{
        banner: (
          <select className="w-full rounded-md border bg-fd-card p-2">
            <option value="v2">API v2 (la plus récente)</option>
            <option value="v1">API v1 (héritage)</option>
          </select>
        ),
      }}
      {...baseOptions}
    >
      {children}
    </DocsLayout>
  );
}

Pour un sélecteur entièrement interactif, extrayez le menu déroulant en composant client et utilisez useRouter pour naviguer vers le bon sous-arbre de version. Les sites de production segmentent généralement les versions dans des dossiers comme content/docs/v1/ et content/docs/v2/.

Étape 10 : Ajouter un explorateur OpenAPI

Fumadocs inclut une intégration OpenAPI officielle qui transforme votre spécification API en documentation interactive. Installez-la.

npm install fumadocs-openapi

Générez des fichiers MDX à partir d'une spécification OpenAPI. Créez scripts/generate-openapi.ts.

import { generateFiles } from "fumadocs-openapi";
 
void generateFiles({
  input: ["./openapi.json"],
  output: "./content/docs/reference",
  per: "operation",
});

Lancez le script.

npx tsx scripts/generate-openapi.ts

Chaque opération API devient sa propre page MDX, avec des tableaux de paramètres, des échantillons de réponse et un panneau "Try it" en direct. Les pages générées vivent aux côtés de vos docs écrites à la main et héritent du même thème.

Étape 11 : Thème et finitions

Ouvrez app/global.css et personnalisez les jetons de design. Fumadocs utilise des variables CSS HSL que vous pouvez surcharger par thème.

@layer base {
  :root {
    --color-fd-primary: 250 95% 55%;
    --color-fd-primary-foreground: 0 0% 100%;
    --color-fd-background: 0 0% 100%;
  }
 
  .dark {
    --color-fd-primary: 250 95% 65%;
    --color-fd-background: 240 10% 4%;
  }
}

La couleur de marque traverse maintenant les boutons, les liens, les éléments actifs de la barre latérale et les surlignages de recherche. Les changements se rechargent à chaud instantanément grâce à Tailwind v4.

Pour ajouter votre logo dans la barre supérieure, déposez un SVG dans public/logo.svg et référencez-le dans layout.config.tsx.

import Image from "next/image";
 
nav: {
  title: (
    <span className="flex items-center gap-2">
      <Image src="/logo.svg" alt="" width={24} height={24} />
      <span className="font-semibold">NoqtaDocs</span>
    </span>
  ),
},

Étape 12 : Build et déploiement

Construisez le bundle de production.

npm run build

Fumadocs utilise par défaut la régénération statique incrémentale de Next.js. Chaque page est générée statiquement au moment du build, et l'index de recherche est livré comme un seul fichier JSON récupéré à la demande.

Pour le déploiement Vercel, poussez sur GitHub et importez le dépôt. Aucune configuration supplémentaire n'est nécessaire.

Pour Cloudflare Pages, ajoutez un wrangler.toml et utilisez l'adaptateur @cloudflare/next-on-pages. La taille du build est généralement inférieure à 5 Mo même pour des sites de 500 pages, bien dans le niveau gratuit de Cloudflare.

Tester votre implémentation

Parcourez cette liste de contrôle avant de partager votre site.

Ouvrez /docs et cliquez sur chaque élément de la barre latérale. Tous devraient s'afficher sans erreur.
Appuyez sur Cmd+K et cherchez des termes sur plusieurs pages. Les résultats devraient surligner les correspondances.
Basculez le mode sombre via le sélecteur de thème. Vérifiez que les blocs de code s'adaptent correctement.
Réduisez la fenêtre à une largeur mobile. La barre latérale devrait se replier en tiroir.
Inspectez la source de la page. Chaque doc devrait être livrée avec les bonnes meta-balises et images OpenGraph.
Lancez Lighthouse. Un site Fumadocs correctement configuré obtient un score de 95 ou plus sur tous les critères.

Dépannage

La barre latérale n'affiche pas les nouvelles pages. Redémarrez le serveur de développement. Fumadocs met en cache l'arborescence des pages au démarrage et la reconstruit chaque fois que source.config.ts ou meta.json change.

Les composants MDX s'affichent en HTML brut. Assurez-vous d'avoir importé le composant en haut du fichier MDX. Contrairement au Pages Router, les fichiers MDX de l'App Router ne s'auto-importent pas.

La recherche ne renvoie aucun résultat. Vérifiez que app/api/search/route.ts exporte correctement GET. Ouvrez l'onglet réseau du navigateur et cherchez une réponse 200 de /api/search.

Le build échoue avec des erreurs de type sur le frontmatter. Votre schéma Zod dans source.config.ts ne correspond pas au frontmatter de vos fichiers MDX. Ajoutez le champ manquant ou marquez-le comme optionnel.

Prochaines étapes

Vous avez maintenant un site de documentation de niveau production. Voici quelques idées pour l'étendre.

Ajoutez une section /blog en utilisant le même pipeline MDX
Intégrez l'analytique avec PostHog ou Plausible pour suivre les pages populaires
Auto-générez des pages de changelog à partir de vos releases GitHub
Ajoutez un assistant de documentation propulsé par l'IA en utilisant le SDK Vercel AI et votre index de recherche
Créez un explorateur d'API public qui exécute les requêtes directement depuis le navigateur

Pour des modèles plus avancés, consultez nos tutoriels associés sur les server actions de Next.js 15, le SDK AI et TanStack Query.

Conclusion

Fumadocs trouve un équilibre rare entre l'ergonomie pour les développeurs et la finition du design. Il vous offre la même esthétique magnifique que les plateformes SaaS payantes tout en gardant chaque ligne de code dans votre dépôt. En combinant les composants serveur, MDX 3, Tailwind v4 et la recherche Orama, il produit un site de documentation rapide à construire, rapide à charger et facile à maintenir.

Si vous démarrez un nouveau projet en 2026, Fumadocs est le pari le plus sûr pour la documentation. La communauté est dynamique, l'API est stable et le chemin de mise à niveau est convivial. Livrez-le, partagez-le et regardez votre expérience développeur s'améliorer du jour au lendemain.

Créer un site de documentation moderne avec Fumadocs et Next.js 15 en 2026