La version 2.0 de Docusaurus, un générateur de site statique qui convertit les fichiers Markdown en site Web de documentation, est disponible,

Avec un système de plug-ins et la thématisation

Le 2 août 2022 à 15:00, par Bill Fassinou

21PARTAGES

L'équipe de développement de Docusaurus a publié lundi la deuxième version majeure du générateur de site Web statique. Docusaurus 2.0 est livré avec le support du format de fichier MDX pour permettre aux utilisateurs d'intercaler des composants React dans Markdown, la prise en charge des conventions de système de fichiers pour faciliter davantage l'ajout de nouvelles pages lors de la création d'une documentation, ainsi que l'ajout de nouveaux plug-ins. Une autre fonctionnalité clé de cette version est la thématisation qui, selon l'équipe, permet de créer une expérience cohérente dans une documentation.

Docusaurus est un générateur de site statique open source qui convertit les fichiers Markdown en site Web de documentation. Créé par Facebook (aujourd'hui Meta), Docusaurus est développé avec Node.js. « L'objectif principal de ce projet est de vous permettre de démarrer votre site Web en quelques secondes. Au-delà de la création du site, Docusaurus met l'accent sur la rapidité du développeur et de l'utilisateur final en suivant le modèle PRPL (Push, Render, Pre-cache, Lazy-load) et en s'appuyant sur une construction incrémentale pour les changements de contenu », a écrit l'entreprise à propos de son générateur de site Web statique.

Docusaurus permet aux développeurs d'utiliser des outils qu'ils connaissent déjà comme Markdown ou le format MDX pour rédiger de la documentation ou des blogues. Désormais, avec React comme colonne vertébrale de Docusaurus, les développeurs peuvent personnaliser leur site Web en fonction de leur cas d'utilisation. Cet outil de création de sites Web est également doté de fonctions de recherche et de localisation. Les projets construits avec Docusaurus tirent parti d'Algolia pour un moteur de recherche intégré et de Crowdin pour la prise en charge des langues. Docusaurus synchronise également automatiquement les modifications apportées au code.

Docusaurus a été mis à la disposition du public pour la première fois par l'équipe open source de Meta en 2017. Selon l'équipe, des milliers d'organisations utiliseraient à jour Docusaurus pour alimenter leurs sites Web de documentation. Le projet est disponible sous la licence MIT. Docusaurus 2.0 a été publié lundi avec de nombreuses nouvelles fonctionnalités et quelques corrections de bogue. Voici ci-dessous les nouveautés clés de cette version :

Prise en charge de MDX

MDX est un format de fichier standard qui combine Markdown et JSX. Cela signifie que vous pouvez utiliser la syntaxe laconique de Markdown pour une documentation et intégrer librement des blocs de composants JSX à n'importe quel endroit du fichier. Rappelons que JSX est une extension React de la syntaxe du langage JavaScript qui permet de structurer le rendu des composants à l'aide d'une syntaxe familière à de nombreux développeurs. Il est similaire en apparence au HTML.

Ainsi, avec la prise de MDX, Docusaurus 2.0 vous permet désormais d'entrelacer des composants React dans Markdown. Cela vous permet de construire facilement des expériences de documentation interactive de premier ordre. MDX dispose de son propre système de plug-ins. Vous pouvez personnaliser votre expérience de création Markdown, et même créer votre propre syntaxe Markdown.

Conventions du système de fichiers et plug-ins

« Notre objectif est de rendre l'utilisation de Docusaurus très intuitive », a déclaré l'équipe. Ainsi, elle a ajouté des conventions de système de fichiers qui, selon elle, rendent l'ajout d'une page à votre documentation aussi facile que de créer un fichier Markdown. En outre, l'équipe a également déclaré que Docusaurus a maintenant une architecture modulaire avec un système de plug-ins - les fonctions principales comme les documents, le blogue, les pages et la recherche sont toutes alimentées par des plug-ins individuels. Selon elle, cela permet à la communauté d'améliorer Docusaurus avec des fonctionnalités supplémentaires.

« L'API des plug-ins est très facile à utiliser et suffisamment puissante pour que je puisse porter l'exemple de code de rendu d'un site Web TypeScript en quelques heures », a déclaré Orta Therox, ancien membre de l'équipe TypeScript chez Microsoft. Voici quelques exemples :

redocusaurus : ce plug-in permet une intégration transparente avec OpenAPI et Redoc ;
docusaurus-preset-shiki-twoslash : il permet d'utiliser la coloration syntaxique des blocs de code Shiki avec les indices du compilateur TypeScript TwoSlash ;
docusaurus-search-local : il s'agit de l'une des diverses alternatives de recherche locale au plug-in Algolia intégré.

Thématisation (Theming)

Selon l'équipe, la thématisation est l'une des caractéristiques les plus importantes de Docusaurus 2.0. « Nous pensons qu'un site de documentation professionnel doit respecter l'image de marque de votre entreprise et créer une expérience cohérente », a-t-elle déclaré. Cela permet aux utilisateurs prêts à investir un peu plus de temps dans les personnalisations de créer des sites qui se distinguent des autres. Elle ajoute que la thématisation de Docusaurus offre une grande flexibilité à plusieurs niveaux :

personnalisez les variables CSS pour ajuster les couleurs, les polices, etc. ;
utilisez vos propres feuilles de style CSS ;
implémentez votre propre thème à partir de zéro ;
remplacez n'importe quel composant React fourni par le thème par défaut. L'équipe appelle cela "swizzling".

Autres fonctionnalités

Docusaurus 2.0 est livré avec une très longue liste de fonctionnalités utiles :

thème : mode sombre, amélioration de l'interface utilisateur et de l'ergonomie, options de configuration du thème flexibles, etc. ;
versionnage des documents : options de plug-in flexibles pour s'adapter à votre flux de travail ;
barre latérale des documents : catégorie repliable, pages d'index des catégories, etc. ;
blogue : auteurs multiples, carte des auteurs, page d'archives, etc. ;
Markdown : onglets, équations mathématiques, blocs de code dynamiques, liens, pages de garde flexibles, etc. ;
recherche : utilisez la nouvelle expérience Algolia DocSearch 3 ;
ressources : facilitez l'intégration d'images et d'autres types de fichiers ;
internationalisation : options de configuration, traductions du thème par défaut, etc. ;
accessibilité : attribut aria-label, contrastes de couleurs, saut au contenu, navigation au clavier, amélioration progressive, etc. ;
SEO : valeurs sensibles par défaut, facile à personnaliser, URL canonique, carte sociale, sitemap, microdata, hreflang, etc. ;
PWA : ajoutez le support hors ligne à votre site et rendez-le installable ;
fail fast : validation stricte de la configuration, détection des liens brisés et prévention des mauvais déploiements en production ;
support de TypeScript pour les fichiers de configuration, les plug-ins, les pages personnalisées et les auteurs de thèmes ;
etc.

Parmi les alternatives à Docusaurus, on peut citer GitBook, MkDocs, Docsify et Daux.io. GitBook est un outil permettant de créer des livres/documentations en utilisant Git et Markdown. Il peut générer votre livre en plusieurs formats. Selon certains, GitBook serait la meilleure alternative à Docusaurus. MkDocs est un générateur de site statique destiné à la création de documentation de projet. Les fichiers sources de la documentation sont écrits en Markdown, et configurés avec un seul fichier de configuration YAML. Quant à Docsify, il génère votre site Web de documentation à la volée. Contrairement à GitBook, il ne génère pas de fichiers HTML statiques.

Au lieu de cela, il charge et analyse intelligemment vos fichiers Markdown et les affiche sous forme de site Web. Tout ce que vous avez à faire est de créer un index. En outre, Daux.io est un générateur de documentation qui utilise une structure de dossiers simple et des fichiers Markdown pour créer une documentation personnalisée à la volée. Il vous aide à créer une documentation de grande qualité d'une manière conviviale pour les développeurs. Il y a également Gatsby, un générateur de site statique doté d'un grand nombre de fonctionnalités, d'un riche écosystème de plug-ins et est capable de faire tout ce que fait Docusaurus.

Cependant, l'on estime qu'il a une courbe d'apprentissage plus élevée. Gatsby fait beaucoup de choses bien et convient à la création de nombreux types de sites Web. Selon Meta, contrairement à Gatsby, Docusaurus essaie de bien faire une seule chose : "être le meilleur outil pour écrire et publier du contenu". GraphQL est également au cœur de Gatsby, même si vous n'avez pas nécessairement besoin de GraphQL pour créer un site Gatsby. Dans la plupart des cas, lorsque vous créez des sites Web statiques, vous n'avez pas besoin de la flexibilité offerte par GraphQL.

L'équipe de Docusaurus reconnaît toutefois que de nombreux aspects de Docusaurus 2.0 ont été inspirés par les meilleures choses de Gatsby. Enfin, comme alternative à Docusaurus, il y a également VuePress. Cet outil présente de nombreuses similitudes avec Docusaurus : tous deux sont fortement axés sur les sites Web centrés sur le contenu et offrent des fonctionnalités de documentation sur mesure. Toutefois, VuePress est basé sur Vue, tandis que Docusaurus est basé sur React. Si vous voulez une solution basée sur Vue, VuePress serait un choix décent.

Source : Docusaurus 2.0

Et vous ?