Créer des sites de documentation avec Docusaurus

Vous avez besoin d’un site de documentation pour votre bibliothèque, framework ou produit SaaS. Vous le voulez statique, rapide et maintenable sans tout construire de zéro. Docusaurus v3 répond bien à ces besoins : c’est un générateur de sites statiques mature basé sur React qui intègre nativement la gestion de versions, l’intégration de recherche et le support MDX.

Ce guide couvre l’architecture et la configuration pratique d’un site de documentation Docusaurus, en se concentrant sur les concepts qui restent stables d’une version mineure à l’autre.

Architecture de base d’un site de documentation Docusaurus

Docusaurus organise le contenu en trois types distincts :

Docs se trouvent dans le répertoire /docs. Ce sont vos pages de documentation principales, rendues avec une navigation latérale automatique et un support de versioning. Chaque fichier Markdown ou MDX devient une page.

Blog : les articles vont dans /blog. Ils conviennent bien pour les changelogs, les annonces de versions ou les tutoriels sensibles au temps.

Pages dans /src/pages sont des composants React autonomes ou des fichiers MDX pour des pages d’accueil personnalisées, des sections « à propos » ou tout ce qui sort de la structure docs/blog.

Le modèle de sidebar et de versioning mérite attention. Docusaurus génère automatiquement les sidebars à partir de votre structure de dossiers, ou vous pouvez les définir explicitement dans sidebars.js. Lorsque vous créez une version, il prend un instantané de vos docs actuels dans versioned_docs/, permettant aux utilisateurs d’accéder à la documentation des versions antérieures.

Configuration de Docusaurus v3 : Démarrage

Le scaffolding moderne prend en charge npm, Yarn, pnpm et Bun. Choisissez celui que votre équipe utilise :

npx create-docusaurus@latest my-docs classic

Le preset classic regroupe le plugin docs, le plugin blog et le thème par défaut — suffisant pour la plupart des sites de documentation développeur. Docusaurus v3 nécessite Node.js 20 ou supérieur pour le développement local et la CI.

Après le scaffolding, votre structure de projet ressemble à ceci :

my-docs/
├── docs/
├── blog/
├── src/
│   ├── components/
│   ├── css/
│   └── pages/
├── static/
├── docusaurus.config.js
└── sidebars.js

Le fichier docusaurus.config.js contrôle les métadonnées du site, la configuration du thème, la navbar, le footer et les options des plugins. Ce fichier unique gère la plupart des personnalisations sans toucher au code React.

Documentation MDX : Rédaction du contenu

Docusaurus v3 utilise MDX v3, qui est plus strict que les versions précédentes. Cela compte si vous migrez depuis la v2 — MDX v3 impose une syntaxe JSX correcte et n’ignore pas silencieusement les composants mal formés.

Chaque fichier doc supporte le frontmatter pour les métadonnées :

---
id: getting-started
title: Getting Started
sidebar_position: 1
---

# Getting Started

Your content here. You can import React components directly.

Vous pouvez intégrer des composants React, utiliser des diagrammes Mermaid et inclure des blocs de code interactifs. L’alias @site pointe vers la racine de votre projet pour les imports.

Pour les diagrammes, activez le plugin Mermaid dans votre configuration :

// docusaurus.config.js
module.exports = {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
}

Thématisation et personnalisation

Le système de plugins vous permet d’étendre les fonctionnalités sans forker le thème. Les plugins courants gèrent l’analytique, les sitemaps, le support PWA et les redirections.

Pour la personnalisation visuelle, surchargez les variables CSS dans src/css/custom.css. Le thème utilise Infima en interne, vous ajustez donc des design tokens plutôt que d’écrire des styles de composants :

:root {
  --ifm-color-primary: #2e8555;
  --ifm-code-font-size: 95%;
}

Une personnalisation plus profonde utilise le « swizzling » — l’éjection de composants du thème pour les modifier. Exécutez npx docusaurus swizzle pour voir les composants disponibles. Ne swizzlez que ce dont vous avez besoin, car les composants éjectés nécessitent des mises à jour manuelles lors de la mise à niveau de Docusaurus.

Intégration de la recherche

La plupart des sites Docusaurus en production utilisent Algolia DocSearch. Postulez au programme gratuit si votre documentation est publique, ou auto-hébergez le crawler pour une documentation privée.

La configuration se trouve dans themeConfig :

// docusaurus.config.js
module.exports = {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
}

DocSearch v4 prend également en charge Algolia AskAI, qui ajoute une recherche conversationnelle optionnelle en plus de l’expérience de recherche standard et est configuré dans le cadre de la même intégration Algolia.

Déploiement

Docusaurus génère du HTML, CSS et JavaScript statiques dans le répertoire /build. N’importe quel hébergement statique fonctionne : Vercel, Netlify, GitHub Pages, Cloudflare Pages ou votre propre CDN.

npm run build

La sortie est un site statique standard sans runtime serveur requis. Configurez votre fournisseur d’hébergement pour gérer le routage côté client en servant index.html pour les chemins inconnus.

Ce qu’il faut savoir pour la production

Quelques notes pratiques pour maintenir un site de documentation développeur :

• Le versioning ajoute de la complexité. Ne versionnez que lorsque les utilisateurs ont réellement besoin d’accéder aux anciennes docs. Beaucoup de projets se contentent d’une seule version « actuelle ».
• La rigueur de MDX détecte de vrais bugs. Si la migration depuis la v2 casse des pages, les erreurs pointent généralement vers de vrais problèmes JSX qui méritent d’être corrigés.
• Les temps de build évoluent avec le contenu. Les grands sites bénéficient de builds incrémentaux en CI et de la mise en cache de node_modules.

Conclusion

Docusaurus gère l’infrastructure pour que vous puissiez vous concentrer sur la rédaction d’une bonne documentation. La fondation React signifie que les équipes frontend peuvent personnaliser en profondeur si nécessaire, tandis que les paramètres par défaut fonctionnent suffisamment bien pour que de nombreux sites soient déployés sans toucher au code React. Commencez avec le preset classic, ajoutez des plugins au fur et à mesure que les besoins émergent, et résistez à l’envie de trop personnaliser avant que votre contenu de documentation ne soit solide.

FAQ

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.