Sortie de Docusaurus v3

Sébastien Lorber vient d’annoncer la disponibilité de la nouvelle version stable de Docusaurus : la v3. Il s’agit d’une version majeure, car elle introduit des changements importants. Pour ceux qui ne connaissent pas Docusaurus je vous renvoie à la page de documentation que j’ai écrite sur cet outil de documentation.

Quels sont les changements ?

Parmi les changements majeurs, nous retrouvons :

• la mise à niveau vers MDX v3 est probablement le plus gros changement de cette version, parce que pour éviter trop de travail pour les rédacteurs, les développeurs ont décidé d’intégrer des options de rétro-compatibilité de la v1.
• la mise à niveau vers React 18 permettant l’intégration des fonctionnalités concurrent React.
• la mise à niveau vers TypeScript 5
• la mise à niveau vers prism-react-render v2 qui permet d’obtenir de meilleurs rendus des blocs de code !

Les nouvelles fonctionnalités

L’Option unlisted

Cette version introduit une nouvelle option unlisted qui permet de masquer une page. Cette page sera exclue du fichier sitemap.xml et rendue interdite aux robots de moteurs de recherches. Pour les pages de blogs, elles ne seront pas intégrées au flux RSS. Elle ne sera accessible que si vous connaissez l’URL de cette page. C’est donc fini de jongler avec la mise en commentaire dans les barres latérale de celles-ci.

De nouveaux types diagrammes supportés par mermaid

Le passage à mermaid v10.4 permet de créer désormais des cartes mentales (mind map) et des graphiques en quadrants.

Optimisation du SEO

Cette version ajoute la prise en charge des éléments de référencement SEO manquants dans les meta-données.

Migration vers Docusaurus v3

Le site annonce que pour les sites les plus simples, comme le mien, n’auront besoin de mettre à niveau que quelques packages npm.

Pour les sites plus complexes, les développeurs proposent des stratégies pour aider à effectuer cette mise à niveau ↗. On retrouve par exemple la commande npx docusaurus-mdx-checker qui permet d’avoir une estimation des travaux à réaliser pour réaliser avec succès cette migration.

Le lien vers la page expliquant comment migrer en douceur ↗.

Je n’ai aucune page complexe sur mon site, normalement tout devrait être transparent lors de la migration. Je ne l’ai pas encore faite, j’attends toujours la sortie de la première version corrective d’une version majeure avant de l’effectuer. Par contre, je me pose des questions sur la compatibilité des plugins externes que j’utilise. Je vous ferai un retour de mon expérience quand je ferai cette migration.

Support de la v2

Attention

Docusaurus v2 est désormais entré en mode maintenance . Il ne bénéficiera d’une prise en charge pour les problèmes de sécurité majeurs que pendant 3 mois, jusqu’au 31 janvier 2024. Il est recommandé de passer à la v3 avant cette date.

Conclusion

Finalement, on remarque que cette nouvelle version est surtout une mise à niveau des dépendances vers des versions plus récentes. On a finalement que peu de nouvelles fonctionnalités.