J'ai testé Docusaurus V2
Migrer en toute confiance : de Hugo à Docusaurus V2
Cet été, je me suis replongée dans la documentation d’un client avec une double mission : expliquer leur nouvelle API et migrer l’ensemble du site vers Docusaurus V2.
Du moteur de recherche aux admonitions stylisées en passant par l’intégration ReDoc, cette version ne se contente pas d’être belle — elle fonctionne brillamment. Voici ce que nous y avons gagné, et ce à quoi il faut faire attention.
🟢 Cet été, j’ai eu le plaisir de retravailler pour Lineberty. Ma mission : documenter leur nouvelle API et migrer toute la documentation vers Docusaurus V2.
En 2019, nous avions opté pour un template Hugo "Documentation", qui remplissait bien son rôle — Markdown pour le contenu, YAML pour la structure, une mise en page en trois volets, une jolie page d’accueil et un design responsive. Mais il montrait ses limites pour faire évoluer la documentation de Lineberty.
Lineberty a donc choisi Docusaurus — et plus précisément la version V2 (basée sur React).
Pourquoi pas la V1, me direz-vous ? La V1 que j’avais eu l’occasion de tester au premier semestre 2020, lorsque j’ai aidé 3DVia à migrer sa documentation de HTML vers Docusaurus ?
👉 Tout simplement parce que la V2, bien qu’encore qualifiée d’alpha, est parfaitement stable. C’est une version très mature, avec de nombreuses fonctionnalités séduisantes.
Une structure solide
-
Le moteur de recherche est l’un des points forts de Docusaurus, avec une navigation intuitive et le support de l’i18n (internationalisation), annoncé pour la V2. La prise en main est facile, surtout que Docusaurus V2 est très bien documenté.
-
La sidebar est construite à partir d’un fichier par défaut dans le package. Elle repose sur des IDs de page — qui jouent un rôle clé dans Docusaurus et permettent d’éviter les chemins interminables. Il est donc essentiel de bien planifier l’architecture documentaire et de nommer soigneusement ces IDs !
-
La page d’accueil, la barre de menu et le CSS sont faciles à personnaliser — du moins si l’on reste dans le cadre par défaut. Sinon, il faudra plonger dans les fichiers React 🙂. Heureusement, la section Showcase prouve que presque tout est possible !
De belles options de style
J’ai beaucoup apprécié la contribution d’Infima à l’aspect visuel de la V2. Les variables Infima peuvent être surchargées en CSS, ce qui donne accès à une palette de couleurs infinie. La CSS principale peut aussi être étendue pour modifier de nombreux styles.
Le seul bémol : le style par défaut des tableaux — bandes colorées alternées sans bordures — ne se modifie que si l’on plonge profondément dans le code. À éviter si possible !
J’ai particulièrement aimé le support des admonitions via le plugin MDX. Un codage couleur moderne, une syntaxe simple — bien plus agréable que le classique > note en Markdown.
Et bien sûr, le bouton pour activer le mode sombre est un joli plus.
Un plugin ReDoc
Dernier point fort : la V2 permet l’intégration d’un plugin ReDoc, offrant un accès direct à la documentation d'API depuis le site Docusaurus.
Cela crée un portail unique pour toute la documentation — utilisateur et référence. (Évidemment, la documentation de Lineberty est DOCful 😄)
Petite note sur le Markdown en V2 : alors que la V1 tolérait les balises HTML dans le Markdown (comme un <br> pour un saut de ligne), la V2 adopte une approche “puriste” et ne permet plus ce mélange. Il faut donc bien réfléchir à la mise en page du contenu — mais ce n’est pas la faute de Docusaurus.