Portail de doc React généré à partir de fichiers MDX
Docusaurus compile des fichiers Markdown et MDX en site de documentation statique. Chaque chemin reçoit sa page HTML générée au build, puis le site tourne comme une application monopage React, avec une navigation côté client. Meta l'a publié parce qu'il outille ses nombreux projets open source. Le gabarit classic livre la doc avec barre latérale, un blog, des pages libres et un thème clair ou sombre.
Composants React dans le Markdown et docs versionnées
- MDX : des composants React s'insèrent dans le Markdown (onglets, encadrés), et le thème
live-codeblockaffiche des exemples de code modifiables directement dans la page. - Versions de la doc :
docusaurus docs:version 1.1.0copie l'état courant dansversioned_docs/, et le site sert chaque version figée à côté de la doc en cours, publiée par défaut sous/docs/next/. - Traductions : chaque langue a ses fichiers de traduction, tenus dans Git ou synchronisés avec Crowdin. Les libellés génériques du thème (« Suivant », « Précédent ») sont déjà traduits dans de nombreuses langues.
- Swizzling : un composant du thème se copie (eject) ou s'enveloppe (wrap) dans le dossier
src/themedu site, sans forker le thème. - Docusaurus Faster : l'infrastructure de build revue (Rspack, SWC, LightningCSS) est stable depuis la 3.10, en option, et sera active par défaut en v4.
Node.js 20, Algolia et une v4 en préparation
Le projet revendique la documentation comme terrain principal. Sa page de présentation se compare aux autres générateurs : VitePress vise le même usage mais repose sur Vue ; MkDocs, en Python, est selon elle une bonne option pour qui ne veut ni application monopage ni React ; GitBook n'est gratuit que pour les équipes open source et à but non lucratif, quand Docusaurus l'est pour tout le monde.
La 3.10 exige Node.js 20 ou plus. La branche principale, déjà numérotée 4.0.0 dans son package.json, relève ce plancher à Node.js 24.21.
La recherche officielle passe par Algolia DocSearch, un service externe. Il est gratuit pour la documentation de développeurs et les blogs techniques, après acceptation d'une candidature ; un site privé ou derrière un pare-feu doit faire tourner son propre robot d'indexation. Des plugins de recherche locale existent, mais la communauté les maintient, pas l'équipe du projet. Starlight, lui, embarque par défaut une recherche plein texte Pagefind.
La documentation déconseille elle-même le versionnage dans la plupart des cas. Il allonge le build et complique le dépôt. Le guide le réserve aux sites à fort trafic dont la doc change beaucoup d'une version à l'autre, et conseille de rester sous dix versions.
Chaque langue est une application monopage distincte. Le serveur de développement n'en démarre qu'une à la fois. La traduction des slugs et la détection automatique de la langue du visiteur sont hors du périmètre annoncé.
Un composant éjecté peut casser à la mise à jour. Ceux que le thème marque « unsafe » peuvent changer de façon incompatible entre deux versions mineures, et la doc conseille d'envelopper plutôt que de copier.
La 3.10 est annoncée comme la dernière version de la branche 3.x. Sortie le 7 avril 2026, elle ajoute des options future.v4 qui activent par avance les changements cassants de la v4. Le dernier correctif, 3.10.2, date du 10 juillet 2026, et le dépôt reçoit toujours des commits, le plus récent le 23 octobre 2026.