Docusaurus est un générateur de sites statiques de Meta, taillé pour la documentation. Vous écrivez vos pages en Markdown, vous les versionnez dans Git, et une commande produit un site rapide avec recherche, blog et thème personnalisable. Ce guide vous fait créer un site de zéro avec Docusaurus 3, puis le configurer, y ajouter de la doc et un blog, et le déployer. Tout a été vérifié sur la version 3.10.1 (React 19, Node 20).
Ce que vous allez apprendre
Section intitulée « Ce que vous allez apprendre »- Installer Docusaurus 3 et créer un site avec
create-docusaurus - Comprendre la structure générée et le rôle de chaque dossier
- Configurer le site via
docusaurus.config.js(désormais en ESM) - Rédiger la documentation et organiser la barre latérale
- Activer et alimenter le blog intégré
- Construire et déployer le site statique
Qu'est-ce que Docusaurus ?
Section intitulée « Qu'est-ce que Docusaurus ? »Docusaurus est un générateur de sites statiques open source développé par Meta sous licence MIT et basé sur React. Un générateur statique produit des pages HTML pré-rendues, sans base de données : le site est léger, rapide et facile à héberger.
Son intérêt pour un DevOps, c'est l'approche doc as code : la documentation vit dans un dépôt Git, à côté du code, et un pipeline CI/CD la construit et la déploie automatiquement à chaque commit. Vous traitez votre doc comme du code (revue, versioning, historique), et Docusaurus y ajoute un blog, la recherche et le versioning de documentation prêts à l'emploi.
Prérequis
Section intitulée « Prérequis »- Node.js 20 ou supérieur (Docusaurus 3.10 exige Node ≥ 20).
- Un gestionnaire de paquets : npm (fourni avec Node), pnpm ou yarn.
- Des bases de Markdown et un terminal.
node --version# v20.19.0 ou plusCréer le site
Section intitulée « Créer le site »La commande create-docusaurus génère toute la structure. Le template
classic inclut la doc, le blog et un thème prêt à personnaliser.
npx create-docusaurus@latest mon-site classic --javascriptnpx create-docusaurus@latest mon-site classic --typescriptSans --javascript ni --typescript, la commande vous demande le langage.
À la fin, elle affiche les prochaines étapes :
cd mon-sitenpm startHappy building awesome websites!La structure générée
Section intitulée « La structure générée »Une fois dans le dossier (cd mon-site), voici l'arborescence du template
classic en version 3.10 :
mon-site/├── blog/ # billets datés + authors.yml + tags.yml├── docs/ # intro.mdx + tutorial-basics/ + tutorial-extras/├── src/│ ├── components/ # composants React réutilisables│ ├── css/ # styles globaux (custom.css)│ └── pages/ # pages libres (.js/.tsx/.mdx) → routes├── static/img/ # fichiers servis tels quels (images, robots.txt)├── docusaurus.config.js # configuration du site (ESM)├── sidebars.js # structure de la barre latérale└── package.jsonTrois dossiers structurent le contenu : docs/ pour la documentation,
blog/ pour les billets, src/pages/ pour les pages libres. Tout fichier
Markdown/MDX déposé dans docs/ devient une page de doc.
Lancer le site en local
Section intitulée « Lancer le site en local »Le serveur de développement recharge à chaud à chaque modification :
npm startLe site s'ouvre sur http://localhost:3000. Éditez un fichier de docs/ :
la page se met à jour instantanément, sans relancer la commande.
La configuration
Section intitulée « La configuration »Tout se règle dans docusaurus.config.js. En version 3, il est écrit en
ESM. Les champs essentiels :
import {themes as prismThemes} from 'prism-react-renderer';
/** @type {import('@docusaurus/types').Config} */const config = { title: 'Ma Doc', tagline: 'La documentation de mon produit', url: 'https://docs.mon-domaine.fr', baseUrl: '/', organizationName: 'mon-org', // org/utilisateur GitHub projectName: 'ma-doc', // dépôt future: { v4: true }, // compat anticipée Docusaurus v4 // presets, themeConfig (navbar, footer, coloration Prism)...};
export default config;urletbaseUrl: l'adresse de production (et le sous-chemin, utile pour GitHub Pages).future: { v4: true }: active les comportements de la future v4 pour préparer la migration sans surprise.organizationName/projectName: nécessaires pour le déploiement GitHub Pages.
Modifiez ces valeurs avant tout : ce sont elles qui conditionnent les liens et le déploiement.
Rédiger la documentation
Section intitulée « Rédiger la documentation »Chaque fichier de docs/ devient une page. Le front matter (en tête de
fichier) contrôle le titre, l'ordre et l'URL :
---sidebar_position: 1slug: /demarrage---
# Démarrage
Le contenu de la page en **Markdown** ou MDX.sidebar_positionordonne les entrées dans la barre latérale.slugforce l'URL de la page (pratique pour conserver un lien existant lors d'une migration et ne pas casser le référencement).
La barre latérale se génère automatiquement à partir de l'arborescence de
docs/, ou se déclare explicitement dans sidebars.js pour un contrôle total.
Ajouter un blog
Section intitulée « Ajouter un blog »Le blog est inclus dans le template classic. Les billets vivent dans
blog/, nommés yyyy-mm-dd-titre.mdx : Docusaurus se sert de la date du
nom de fichier pour classer les articles.
blog/├── 2026-06-23-premier-billet.mdx├── authors.yml # définition des auteurs└── tags.yml # définition des tagsUn billet déclare son auteur et ses tags dans son front matter, en référençant
authors.yml :
---title: Nouveautés de la version 2authors: sroberttags: [release]---
Commencez **directement par un titre de niveau 2** dans le corps du billet : letitre principal vient du champ `title`.Et authors.yml centralise les profils :
srobert: name: Stéphane ROBERT title: Consultant DevOps url: https://github.com/stephrobert image_url: https://github.com/stephrobert.pngConstruire et déployer
Section intitulée « Construire et déployer »Pour la production, Docusaurus génère un site statique dans build/ :
npm run build# [SUCCESS] Generated static files in "build".Vous pouvez tester ce build localement avant de publier :
npm run serveLe dossier build/ se déploie sur n'importe quel hébergement statique :
GitHub Pages, Netlify, Vercel, ou un bucket S3 + CDN. En doc as
code, c'est un job de pipeline CI/CD qui exécute npm run build puis pousse
build/ à chaque commit sur la branche principale.
Mon retour d'expérience : Docusaurus ou Astro Starlight ?
Section intitulée « Mon retour d'expérience : Docusaurus ou Astro Starlight ? »Soyons transparents : j'ai évalué Docusaurus pour ce blog (alors sous Hugo), et j'ai finalement retenu Astro Starlight pour sa sobriété et sa performance (moins de JavaScript envoyé au navigateur). Ce n'est pas un reproche à Docusaurus.
Docusaurus reste un excellent choix, et je le recommande quand vous voulez : l'écosystème React (composants interactifs dans la doc), le versioning de documentation natif (plusieurs versions d'un produit en parallèle), l'i18n mûre, et un blog intégré sérieux. Pour une doc produit ambitieuse, c'est souvent le meilleur outil. Pour un site sobre et ultra-rapide, regardez aussi Starlight. Les deux font du doc as code : le réflexe compte plus que l'outil.
Pièges courants
Section intitulée « Pièges courants »| Piège | Conséquence | Solution |
|---|---|---|
| Node < 20 | L'installation ou le build échoue | Passer sur Node 20+ |
Oublier url / baseUrl | Liens cassés en production (surtout GitHub Pages) | Renseigner les deux avant de déployer |
Confondre docs/ et blog/ | Pages au mauvais endroit | docs/ = documentation, blog/ = billets datés |
Config en module.exports | Erreur depuis la v3 (ESM) | Utiliser import / export default |
Commiter build/ | Dépôt alourdi | L'ignorer dans .gitignore, le générer en CI |
FAQ : questions fréquentes
Section intitulée « FAQ : questions fréquentes »npx create-docusaurus@latest mon-site classic
cd mon-site
npm start
npm start lance le serveur de développement (rechargement à chaud). Vous éditez ensuite les pages Markdown dans docs/, puis vous générez le site statique avec npm run build pour le déployer (GitHub Pages, Netlify, Vercel).