Docusaurus, un site de documentation basé sur du markdown

Docusaurus est une solution de création de site basé sur des fichiers markdown.

Initialement créée par Facebook, c'est un système totalement open source qui permet de compiler et déployer rapidement des pages navigables.

Il est notamment très apprécié pour la documentation, car une fois versionné sur un repository GitLab avec une pipeline de CI/CD adaptée, ça permet à plusieurs développeurs de travailler ensemble sur la doc, et de présenter un site qui peut disposer de nombreux plugins.

Que ce soit pour une documentation interne dédiée à une équipe ou pour Documenter un produit IT avec la gestion des langues et des versions, Docusaurus s'adapte très bien. Les développeurs n'ont pas besoin d'utiliser un CMS, ni d'apprendre à manipuler du HTML : ils peuvent directement, dans un environnement proche de code, écrire une documentation bien rendue et bien intégrée. Des développeurs Java, C# ou Python pas forcément orientés web peuvent directement rédiger de la documentation dans leur environnement habituel.

Cela permet aussi d'avoir une traçabilité et un historique des modifications, vu qu'en principe, celles-ci sont versionnées dans l'outil de code source.

Docusaurus excelle dans tout ce qui est lié à la technique car il permet de présenter, des extraits de code avec coloration syntaxique, des schémas (format mermaid), et tout ce qu'offre le markdown (images, liens, tableaux...)

N.B.: Depuis 2025, ce blog qui était initialement sur Wordpress est passé sur Docusaurus. Les raisons principales, c'est d'une part que ce site est très orienté "code", et d'autre part, c'est beaucoup plus simple dans Docusaurus de gérer des blocs de code, des schémas techniques et autres.

Comment ça marche?

Le principe de base est d'avoir une série de fichiers de textes et de configuration, qui vont déterminer le contenu et la présentation du site.

Après avoir lancé la compilation, un site en react est généré dans un répertoire /build. Le contenu de ce site peut alors être deployé sur un serveur, sur des pages GitLab ou GitHub, etc., et ainsi être disponible pour les lecteurs potentiels.

Plus de détails sur la partie technique après une petite présentation de la structure.

Exemple de structure de site Docusaurus

Tout le contenu d'un site Docusaurus est basé sur des fichiers Markdown présents dans un répertoire /docs. Il existe aussi une partie /blog pour du contenu éditorial, des news, et il est également de faire des landing pages.

Créer des répertoires permet de créer des rubriques et sous-rubriques, par défaut, l'arborescence du site sera calquée sur l'arborescence des fichiers.

Docusaurus
├───blog                        # Les articles de blog
│   ├───2026-06-28-articleA.md  # Un article publié le 28 juin 2026
│   └───2026-06-30-articleB.md  # Un article publié le 30 juin 2026
├───docs                        # Endroit principal où les pages de doc sont stockées.
│   ├───_category_.json         # Définition en Json de la catégorie (nom...)
│   ├───howto                   # Répertoire définissant
│   │   ├───create-item.md      # Une page de document dans une rubrique docs / howto
│   │   └───change-settings.md  # Autre page de documentation dans la même rubrique
│   └───installation
│       └───prerequis.md
├───static                      # Fichier contenant des resources statiques, notamment images et favicon.
└───docusaurus.config.js        # Fichier de configuration Docusaurus: thèmes, plugins...

Chaque fichier markdown correspond au rendu d'une page. Il est également possible d'utiliser du MDX, une sorte de Markdown plus élaboré avec des styles et un peu d'interactivité.

Front-matter au début du fichier (Metadata de la doc)

Les pages peuvent être précédées de frontmatter, des metadata écrites en langages Yaml qui permettent notamment d'ordonner les fichiers, de changer un peu le comportement de la page, etc. C'est comme ça également qu'on peut choisir l'ordonnancement de fichiers dans une même catégorie.

---
title: How to create items?
sidebar_label: Create items
sidebar_position: 20
description: How to create items in my applications?
tags: [items,exploitation]
---

L'ajout de ce front-matter au début de chacune des pages permet de gérer finement la manière dont les pages s'affiche.

Voir la documentation qui concerne les docs : Markdown front matter, il en existe aussi pour les pages et les articles de blog.

Un autre point à noter : il y a la syntaxe prise en charge nativement par Docusaurus, mais ce n'est pas limitatif. Vous pouvez étendre le fonctionnement avec des plugins ou du scripting maison.

De quoi a-t-on besoin?

Le Getting Started de Docusaurus est assez complet : Docusaurus - Installation, mais voici en quelques mots les pré-requis:

1. Node.js installer sur la machine - pour récupérer les packages Docusaurus, compiler le site et même lancer un serveur en local pour le tester
2. Un IDE qui peut gérer du markdown et pourquoi pas du Node. Visual Studio Code fonctionne très bien.
3. Un espace où déployer le site : par exemple un site web, un conteneur Kubernetes, ou un gestionnaire de code source avec un espace dédié à la publication (GitLab Pages, GitHub Pages)

Quelle est la première étape, en local ?

Au début, dans un répertoire dédié, vous aller installer un site par défaut (le site classique de Docusaurus).

À ce stade, vous aurez la structure créée en locale et vous pouvez commencer à modifier tout ce que vous voulez : le contenu et la structure des pages, le fichier docusaurus.config.js, etc.

Vu que vous avez installé Node.js, vous pouvez à tout moment compiler le site et démarrer un serveur en lançant les commandes suivantes dans le terminal : build pour compiler le site (et éventuellement avoir les erreurs), et serve pour démarrer un serveur web local et tester le site (vous permettant notamment de vérifier sa présentation).

npm run build
npm run serve

Pouvoir faire ces étapes en local est très utile car ça permet d'économiser du temps à compiler et déployer le site pour se rendre compte d'une erreur. Ça permet aussi de tester de nouvelles fonctionnalités et de lancer les commandes pour mettre à jour les dépendances, installer des plugins, etc.

attention

Si vous ne pouvez pas compiler votre docusaurus en local, cela doit vous alerter, c'est un signe que son état de santé n'est pas forcément bon en-dehors d'un contexte particulier lié à votre pipeline. Faites en sorte de le consolider et de supprimer la plupart des Warnings.

Comment déployer mon Docusaurus avec de bonnes pratiques DevOps ?

Il est tout d'abord possible de juste compiler le site, puis de copier tout le contenu généré dans le répertoire /build sur un serveur web. Mais avec une approche DevOps où le site est versionné via un repo centralisé de type Git, on va plutôt essayer d'automatiser le déploiement via une pipeline CI/CD.

Deux principes de fonctionnement :

1. Lors d'une merge request d'une branche de modifications vers la branche main, la pipeline CI/CD va tenter de compiler le site. Si cette étape échoue, le message d'erreur doit être clairement remonté pour résoudre le problème.
2. Après une merge request validée (et les éventuelles erreurs de compilation corrigées), le site se compile dans un répertoire et peut être déployé. Côté GitLab par exemple, un répertoire "public" va par défaut être pris, et GitLab lance un job spécifique pour déployer son contenu sur les GitLab pages. Dans d'autre cas, vous voudrez peut être ajouter un job pour envoyer les pages sur un ftp spécifique, ou encore packager votre build pour le déployer via Kubernetes, comme s'il s'agissait d'une web-app.

Quelques astuces utiles

La meilleure façon de s'approprier Docusaurus c'est de le tester, mais je finis tout de même en partageant quelques astuces qui m'ont été très utiles !

1. Moteur de recherche

Un indispensable selon moi, c'est le moteur de recherche. Ça permet à vos utilisateurs de trouver facilement l'article dont ils ont besoin, sans devoir comprendre comment est structurée votre documentation.

Ce n'est pas natif à Docusaurus, il faut utiliser un plugin. Plusieurs plugins sont disponibles, avec différentes options pour générer et utiliser l'index de recherche. Certaines solutions récentes intègrent même de l'IA, ce que je trouve plutôt superflu.

Pour les Docusaurus de petite ou moyenne taille, il est possible d'utiliser une recherche en locale. L'index du site est généré au moment du build du site, et il est mis en cache sur l'ordinateur de ceux qui visitent le site. Je conseille easyops-cn/docusaurus-search-local, mais le site officiel de Docusaurus propose une liste de plugins dédiés à la recherche.

2. Admnonitions

L'admonition, c'est un contenu en principe court (mais pas forcément) mis en avant par la mise en page. Par exemple une info, une astuce, un message plus ou moins important... Cette syntaxe n'est pas rendue par les preview markdown classique car c'est propre à Docusuarus, mais c'est une manière rapide de mettre du contenu en avant.

Vous pouvez voir la documentation de Docusaurus sur les Admonitions, mais en substance, la syntaxe est comme suit:

:::warning[Rollerblade]

Attention à la mousse !

:::

Voici le rendu correspondant :

Rollerblade

Attention à la mousse !

3. Personnalisation des menus, sidebars, etc.

Tout ce qui est à l'écran est personnalisable. La documentation officielle est bien fournie à ce sujet, mais une bonne manière d'apprendre est de chercher dans tout le code où apparaissent les liens que vous voulez remplacer.

Quelques infos pour vous aiguiller :

• La présentation globale du site est dans docusaurus.config.js, ce fichier contient le titre du site, les liens à afficher en haut, en bas, dans la sidebar, la personnalisation des images, etc.
• Le fichier sidebars.js permet de générer des sidebars, soit de manière complètement explicite (lien par lien), soit automatiquement en scannant le contenu d'un répertoire. Les sidebars peuvent être présentées dans l'en-tête du site.
• Dans src/, il y a du contenu pour faire des pages fixes, telles que la landing page. Docusaurus propose une landing page par défaut, qui peut être éditée via index.js et les fichiers du répertoire /components. C'est un peu moins direct que du markdown puisque c'est plus du langage web classique (html, css et javascript), mais rien d'insurmontable.

4. Coloration syntaxiques de langages spécifiques

En markdown, la coloration syntaxique se fait par trois fois le caractère \ (accent grave sans lettre, ou backtick). Sur un clavier AZERTY, on l'obtient en faisaint Alt Gr + 7-è et en mettant un espace.

Le code contenu entre ces séries de trois backticks n'est pas interprêté (ce qui permet de présenter une syntaxe xml ou html par exemple), et il peut être présenté avec la coloration syntaxique du langage. Voici un exemple de code Markdown avec du code C#.

Writing Hello! in C# to the consoles:

```csharp
Console.WriteLine("Hello!");
```

La coloration syntaxique est gérée par le module de rendu Prism. Plusieurs langages de code sont intégrés par défaut, comme expliqué dans la doc sur Code Blocks. Pour ajouter d'autres langages, il faut ajouter de la configuration dans le fichier docusaurus.config.js en ajoutant des langages parmi ceux pris en charge.

export default {
    // ...
    themeConfig:
    ({
    prism: {
            theme: prismThemes.github,
            darkTheme: prismThemes.dracula,
            additionalLanguages: ['csharp', 'powershell', 'regex'],
    },
    // ...
  })
}