Docusaurus - Des sites pour pousser du contenu rapidement.

Article sur la technologie. Avec le temps, les technologies évoluent : certaines informations peuvent être périmées.

Introduction à Docusaurus

https://docusaurus.io/

Docusaurus est un outil open source qui permet aux équipes techniques de créer, gérer et publier des documentations de qualité rapidement. La solution est maintenue par Meta.

Pourquoi utiliser Docusaurus ?

Dans quel contexte ?

Docusaurus est un générateur de site statique conçu spécifiquement pour la documentation de projets techniques. Il est couramment utilisé pour créer des sites de documentation clairs et attrayants pour les projets open source, les bibliothèques, les frameworks et autres projets logiciels.

Cependant, il serait dommage de le limiter aux usages "techniques". Il peut également être utilisé avec succès dans d'autres contextes, tels que :

• FAQ : Docusaurus permet de créer facilement des pages de FAQ (Foire aux Questions) bien structurées, offrant aux utilisateurs des réponses claires et concises à leurs questions les plus fréquentes.

• Documentation interne / métier / de processus d'entreprise : Docusaurus peut être utilisé pour documenter les processus métier d'une entreprise, en fournissant des instructions, des exemples et des bonnes pratiques. Cela permet d'assurer une compréhension uniforme des procédures et d'améliorer l'efficacité organisationnelle.

• Sites dédiés à la relation client : Docusaurus est également adapté pour créer des sites dédiés à la relation client, fournissant des informations essentielles, des guides d'utilisation, des tutoriels et des ressources pour aider les utilisateurs à tirer le meilleur parti d'un produit ou d'un service.

Pourquoi Docusaurus plutôt qu'un autre système ?

Ce que Docusaurus apporte face aux autres outils de documentation :

• Facilité d'utilisation : Docusaurus est facile à installer et à configurer. Vous pouvez mettre en place votre site de documentation en quelques minutes.

• Markdown support : Docusaurus utilise Markdown pour la rédaction du contenu, ce qui rend la rédaction et la mise à jour de votre documentation aussi simple que l'édition d'un fichier texte.

• Thématisation et personnalisation : Docusaurus est livré avec un thème par défaut élégant et professionnel, mais vous pouvez aussi personnaliser votre site pour qu'il corresponde à l'identité de votre marque.

• Recherche intégrée : Docusaurus intègre un système de recherche performant, ce qui permet à vos utilisateurs de trouver rapidement l'information qu'ils cherchent.

• JAMStack : Le site profite des avantages de la JAMStack, c'est-à-dire performant, peu gourmand en ressources, peu cher à héberger, etc.

Comment commencer avec Docusaurus ?

Pour commencer avec Docusaurus, vous aurez besoin de Node.js et Yarn (ou npm) installés sur votre machine.
Une fois que vous avez installé ces prérequis, vous pouvez installer Docusaurus en utilisant la commande suivante :

npx docusaurus init

Cela créera un nouveau site Docusaurus dans un répertoire de votre choix.
Vous pouvez ensuite naviguer dans ce répertoire et démarrer le serveur de développement:

cd my-docusaurus-site
npm run start

Votre site Docusaurus sera maintenant accessible à http://localhost:3000.

Utilisation de Docusaurus

Rédaction de vos documents

Pour écrire vos documents, vous allez utiliser le format Markdown.
Le Markdown est un langage de balisage léger qui vous permet d'ajouter des éléments de formatage comme des titres, du gras, des italiques, des liens, etc., à votre texte.
Vous pouvez trouver un guide complet sur l'utilisation du Markdown ici.

Les fichiers Markdown de votre documentation doivent être placés dans le dossier /docs de votre projet Docusaurus.
Par exemple, vous pourriez avoir une structure de fichiers qui ressemble à ceci :

my-website
└── docs
    ├── doc1.md
    ├── doc2.md
    └── doc3.md

Chaque fichier .md dans le dossier /docs correspond à une page de votre documentation.

Organisation de vos documents

L'organisation de vos documents dans le menu est gérée par le fichier sidebars.js dans votre projet.
Dans ce fichier, vous spécifiez l'ordre des documents dans la barre latérale.
Par exemple, si vous voulez que doc1.md apparaisse avant doc2.md, vous devrez l'organiser de cette manière dans votre fichier sidebars.js.

Déploiement de Docusaurus

Une fois que vous avez écrit et organisé vos documents, vous pouvez déployer votre site Docusaurus.
Pour cela, vous devez d'abord construire votre site en exécutant la commande de build.
Cela générera une version statique de votre site dans le dossier build de votre projet.

Ensuite, vous devez pousser le contenu de ce dossier build vers votre serveur.
La méthode exacte pour cela dépend de votre fournisseur d'hébergement.
Certains fournisseurs d'hébergement peuvent requérir que vous utilisiez une commande spécifique, ou que vous placiez vos fichiers dans un dossier spécifique.

Enfin, pour les documentations qui doivent être mises à jour régulièrement, l'intégration continue (CI) peut être une solution utile.
Avec CI, chaque fois que vous apportez des modifications à votre documentation et les poussez vers votre dépôt, la CI va automatiquement construire et déployer votre site.
De cette façon, votre documentation est toujours à jour.

Conclusion

Docusaurus est un outil puissant et flexible pour créer et gérer des documentations de haute qualité. Que vous cherchiez à créer une documentation technique, une FAQ, un guide client ou tout autre type de contenu d'aide, Docusaurus est une excellente option à considérer.

Dans certains contextes, Docusaurus peut être une bonne alternative : aux documentations PDF, au WordPress des SAVs ou encore au SharePoint de communication.