Cet été, j’ai eu le plaisir de travailler de nouveau pour 🔗 Lineberty : j’ai eu pour mission de documenter leur nouvelle API mais aussi de migrer toute la documentation vers Docusaurus V2.

En 2019, nous avions opté pour un template Hugo “Documentation” qui remplissait très bien son rôle (fichiers Markdown pour le contenu, fichiers YAML pour le framework, structure en trois volets, Home Page actuelle, responsive) mais qui avait ses limites pour les futures évolution de la documentation de Lineberty.

Lineberty a donc fait le choix de Docusaurus (basé sur React) et de la V2 en particulier.

Pourquoi pas la V1 me direz-vous ? V1 que j’ai eu l’opportunité de tester au 1er semestre 2020 en aidant 3DVia à migrer sa documentation du HTML vers Docusaurus.

➡️ Tout simplement parce que la V2, bien que toujours en version alpha, est maintenant parfaitement stable. Cette version est très aboutie et propose un certain nombres d’innovations très séduisantes.

🔸 Une très bonne structure

Le moteur de recherche est un des points forts de Docusaurus, ainsi que la navigation et la gestion des langues i18N qui est annoncée pour cette V2. La prise en main est facile, d’autant que la 🔗 V2 de Docusaurus est très bien documentée.

La sidebar s’élabore facilement à partir du fichier par défaut fourni dans le package. Elle fait appel aux IDs des pages qui jouent un rôle clé dans Docusausus et qui permettent d’éviter de saisir des chemins d’accès interminables. Il faut donc bien penser son architecture et ses dénominations !

La Home page, la barre de menu et la CSS sont aisément modifiables, d’autant plus si on reste dans le cadre du framework par défaut. Sinon, il faudra aller chercher plus loin dans les fichier React :-) mais de nombreux exemples présentés dans la section Showcase nous montre que tout ou presque est possible !

🔸 Des options de mise en forme vraiment bien

Pour ma part, j’ai apprécié l’apport Infima pour toutes les améliorations visuelles dans cette V2. Les variables Infima peuvent être surchargées dans la CSS, ce qui offre un nuancier infini. La CSS principale peut également être complétée pour surcharger un certain nombre de sytle. Seul bémol, l’aspect visuel des tableaux (une alternance de bandes de couleur, sans bordures) qui ne se modifie qu’à condition de plonger très très loin dans les fichiers. A éviter, du coup !

J’ai encore plus apprécié la prise en charge des “admonitions” via le plugin MDX avec leurs codes couleurs très actuels et une très grande simplicité d’écriture. C’est plus sympa que les > note par défaut de Markdown.

Enfin, “last but not least”, le toggle button pour activer le dark mode !

⭐ Un plugin ReDoc

Excellent point enfin pour terminer, l’intégration d’un plugin ReDoc dans la V2 ce qui permet d’accéder, dans le cas de Lineberty, directement à la documentation des API depuis le site Docusaurus. On obtient alors un portail unique vers toute la documentation, utilisateur et de référence (bien sûr, la documentation de Lineberty est 🔗 DOCful 😃)

Petite remarque concernant l’utilisation de Markdown dans la V2 : là où la V1 tolérait fort bien le recours à des balises HTML dans le Markdown (un simple ‘break’ par exemple pour forcer un retour à la ligne), la V2 est passé en mode “puriste” car cela n’est plus possible. Il faut donc également très bien penser son contenu, mais ça ce n’est pas du ressort de Docusaurus !

Admirez le résultat en visitant mon 🔗 Portfolio