Débuter avec docusaurus

Mise à jour : 13/09/2024

Vous devez écrire, maintenir et publier une documentation sur votre produit ? Dans ce billet, nous allons voir comment nous appuyer sur le générateur de sites statiques Docusaurus.

Présentation de Docusaurus

En tant que Devops, nous devons écrire beaucoup de documentations. Docusaurus est sans doute l’une des meilleures solutions pour le réaliser. Il suffit de déposer le code dans un dépôt git et d’y ajouter une pipeline CI/CD pour construire et déployer le site. C’est ce qu’on appelle de la doc as code.

Docusaurus ↗ est donc un générateur de sites statiques développé par Meta Open Source sous licence MIT et basé sur React. Les générateurs de sites statiques permettent de construire des sites web légers faciles à maintenir sans nécessiter de base de données. Il intègre également un moteur de blog et c’est pour cette raison que j’en parle. Je compte migrer mon blog de Hugo, mon générateur actuel, vers Docusaurus.

Pour vous convaincre de sa popularité, je vous invite à jeter un long coup d’œil sur le showcase ↗ de Docusaurus. D’ailleurs, c’est un bon moyen pour trouver des exemples de code, car si vous cliquez sur le filtre Open-Source, vous accéderez à une centaine de sites dont le code source est disponible.

Docusaurus est très simple à installer, cela ne prend que quelques minutes. Dans ce tutoriel, nous allons construire un site de documentation et un blog que nous allons personnaliser. Dans de prochains billets, nous verrons comment lui ajouter des fonctionnalités grâce à ses plugins, à optimiser le référencement avec la partie SEO et à le déployer sur un bucket S3 et le rendre accessible via cloudfront d’AWS.

Installation de Docusaurus

Docusaurus nécessite la version 16.14 de Node.js ou une plus récente. Je vais utiliser la version LTS 18.18.0, même si au moment où j’écris ce billet la version 20 devrait bientôt devenir la version LTS.

Comme dans beaucoup de mes billets, je vais utiliser asdf pour installer nodejs :

asdf plugin add nodejs
asdf install nodejs 18.18.0
asdf global 18.18.0
node --version
v18.18.0

Création du site avec Docusaurus

Nous allons créer la structure du site avec la commande npx. Le premier paramètre indique que nous demandons à créer un site docusaurus, le second paramètre est le nom du dossier dans lequel sera stocké le projet, le troisième paramètre est le nom du thème et le quatrième le langage du thème. J’utilise le thème classique, car il est très facile de le personnaliser par la suite.

npx create-docusaurus@latest my-website classic --typescript

Cela prend quelques minutes…

Structure d’un site Docusaurus

Une fois la commande précédente terminée, vous pourrez vous déplacer dans le dossier.

cd my-website

Voici à quoi ressemble la structure des fichiers :

blog-sr
├── static
│   └── img
├── babel.config.js
├── src
│   ├── pages
│   ├── components
│   └── css
├── docs
│   ├── intro.md
│   ├── tutorial-basics
│   └── tutorial-extras
├── package.json
├── blog
│   ├── 2021-08-26-welcome
│   ├── 2019-05-29-long-blog-post.md
│   ├── 2019-05-28-first-blog-post.md
│   ├── authors.yml
│   └── 2021-08-01-mdx-blog-post.mdx
├── node_modules
|
├── tsconfig.json
├── sidebars.js
├── package-lock.json
├── docusaurus.config.js
└── README.md

Voici quelques détails concernant quelques-uns de ces fichiers et dossiers composant cette structure :

/blog : Contient tous les fichiers de votre blog.
/docs : Contient tous les fichiers de vos docs.
/src : Contient des pages ou des composants personnalisés.
/src/pages : Tous les fichiers JSX/TSX/MDX seront transformés en pages.
/static : Les fichiers statiques qui seront copiés dans le dossier de construction final. On y déposera les images ou des fichiers statiques (par exemple le fichier robots.txt)
docusaurus.config.js : Le fichier de configuration de Docusaurus.
sidebar.js : Configuration de la barre latérale.
README.md : La documentation du projet. En bon DevOps, on doit le mettre à jour régulièrement.

Et oui un DevOps se doit de documenter tout ce qu’il fait !

Lancement local

Maintenant que le site est prêt, voyons comment lancer le site localement. Mais avant cela, nous allons créer un certificat.

Création d’un certificat local

Pourquoi ? Parce que dans certaines entreprises, la navigation avec le protocole http est parfois désactivé.

Comme d’habitude j’utilise mkcert :

mkcert localhost

Vous devriez retrouver 2 fichiers :

ls localhost*

localhost-key.pem  localhost.pem

Définir des variables du projet avec direnv

Pour faciliter le lancement, nous allons utiliser direnv pour fixer nos variables d’environnement :

vi .envrc

Mettez-y ces valeurs :

export HTTPS=true
export SSL_CRT_FILE=localhost.pem
export SSL_KEY_FILE=localhost-key.pem

Sauvegardez et quittez. Ensuite, autorisez direnv d’utiliser ces valeurs :

direnv allow
direnv: loading ~/Projets/perso/my-website/.envrc
direnv: export +HTTPS +SSL_CRT_FILE +SSL_KEY_FILE

Tout est prêt :

Lancement du site en local

npm start

Vous devriez voir le site se construire et un onglet s’ouvrir dans votre navigateur :

install docusaurus start

Nous pouvons passer à la personnalisation de votre site.

Personnalisation de Docusaurus

La configuration de Docusaurus est stockée dans le fichier docusaurus.config.js.

Modification du Nom et de la description

Pour modifier le nom et la description, éditez le fichier de configuration :

vim docusaurus.config.js

Voici un exemple de contenu :

const config = {
  title: 'ROBERT Stéphane - Devops',
  tagline: 'Blog de Stéphane, Spécialiste des plateformes web et des pratiques DevOps basées sur des solutions OpenSource telles que, kubernetes, ansible, gitlab, python',
  favicon: 'img/favicon.ico',

  // Set the production url of your site here
  url: '',
  // Set the /<baseUrl>/ pathname under which your site is served
  // For GitHub pages deployment, it is often '/<projectName>/'
  baseUrl: '/',

  // GitHub pages deployment config.
  // If you aren't using GitHub pages, you don't need these.
  organizationName: 'Stéphane ROBERT', // Usually your GitHub org/user name.
  projectName: 'my_website', // Usually your repo name.

  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',

  // Even if you don't use internalization, you can use this field to set useful
  // metadata like html lang. For example, if your site is Chinese, you may want
  // to replace "en" with "zh-Hans".
  i18n: {
    defaultLocale: 'fr',
    locales: ['fr'],
  },

Les informations importantes :

title : Le titre de la page d’accueil du site.
tagline : La meta-description de votre site.
favicon.ico : L’icône de votre site, c’est celle que l’on retrouvera par dans les moteurs de recherches.
url : L’url du site.
baseUrl : La partie de l’url entre l’url et le reste de l’adresse complète.
organizationName : Le nom de votre entreprise ou le vôtre.
projectName : Le nom du projet git. Sert à la construction du lien pointant vers le projet.
i18n : Permet de définir la langue du site. Très important pour le référencement du site.

Modifiez simplement ces détails pour les adapter à vos besoins, puis enregistrez le fichier. Normalement si vous n’avez pas arrêté la commande npm start, vous devriez voir la mise à jour de celui-ci. Trop cool !

install docusaurus update

La page d’accueil affiche le nouveau titre et sa description.

Pour modifier la barre de navigation de votre site, localisez la variable navbar dans le fichier docusaurus.config.js.

Nous allons modifier le lien Tutorial en Documentations et modifier le logo également.

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      // Replace with your project's social card
      image: 'img/docusaurus-social-card.jpg',
      navbar: {
        title: 'Home',
        logo: {
          alt: 'Stéphane ROBERT',
          src: 'img/logo-sr.svg',
        },
        items: [
          {
            type: 'docSidebar',
            sidebarId: 'docSidebar',
            position: 'left',
            label: 'Documentation',
          },
          {to: '/blog', label: 'Blog', position: 'left'},
          {
            href: 'https://github.com/stephrobert',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },

Si vous sauvegardez, vous devriez voir une erreur, car Docusaurus ne trouve pas la navbar docSidebar. Cela vient du fait que nous avons renommé tutorialSidebar en docSidebar.

Pour corriger l’erreur, éditez le fichier navbar.js :

vim navbar.js

Modifiez tutorialSidebar en docSidebar et sauvegardez et quittez comme ci-dessous.

const sidebars = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
  docSidebar: [{type: 'autogenerated', dirName: '.'}],

Sauvegardez et quittez. Le site se relance à nouveau correctement.

install docusaurus navbar

Modification du pied de page

L’essentiel du contenu de votre pied de page se trouve dans le variable footer du fichier docusaurus.config.js. Editez le et modifiez-le comme suit :

      footer: {
        style: 'dark',
        links: [
          {
            title: 'Documentations',
            items: [
              {
                label: 'Documentations',
                // Le lien vers la page hébergeant votre documentation. On doit retrouver le ficher `/docs/intro.xxx`
                to: '/docs/intro',
              },
            ],
          },
          {
            title: 'Communauté',
            items: [
              {
                label: 'Linkedin',
                href: 'https://www.linkedin.com/in/stephanerobert1/',
              },
              {
                label: 'Twitter',
                href: 'https://twitter.com/RobertStphane19',
              },
            ],
          },
          {
            title: 'More',
            items: [
              {
                label: 'Blog',
                // Il es possible de modifier le paramètre to pour par exemple conserver son référencement.
                // Attention! Modifier les liens pointant dessus.
                to: '/blog',
              },
              {
                label: 'GitHub',
                href: 'https://github.com/stephrobert',
              },
            ],
          },
        ],
        copyright: `Copyright © ${new Date().getFullYear()} Stéphane ROBERT. Built with Docusaurus.`,
      },

Sauvegardez et quittez. Le site se met à jour et en bas de page, vous devriez voir les modifications.

install Docusaurus navbar

Modification du style de votre site Docusaurus

Le style classique de Docusaurus utilise le framework CSS Infima. Pour en faciliter les modifications, les créateurs de Docusaurus ont créé un outil en ligne ↗ très utile pour vous aider à modifier facilement les couleurs et leurs déclarations CSS.

Une fois que vous aurez adapté votre style, l’outil génèrera du code personnalisé. Vous pouvez ensuite copier ces valeurs dans le fichier /src/css/custom.css en remplaçant les valeurs existantes. Faites-le pour le mode ligth et le mode dark.

Un exemple :

:root {
  --ifm-color-primary: #000770;
  --ifm-color-primary-dark: #000665;
  --ifm-color-primary-darker: #00065f;
  --ifm-color-primary-darkest: #00054e;
  --ifm-color-primary-light: #00087b;
  --ifm-color-primary-lighter: #000881;
  --ifm-color-primary-lightest: #000992;

}

/* For readability concerns, you should choose a lighter palette in dark mode. */
[data-theme='dark'] {
  --ifm-color-primary: #7e8bbe;
  --ifm-color-primary-dark: #6978b3;
  --ifm-color-primary-darker: #5e6fae;
  --ifm-color-primary-darkest: #4a5993;
  --ifm-color-primary-light: #939ec9;
  --ifm-color-primary-lighter: #9ea7ce;
  --ifm-color-primary-lightest: #bdc4de;
}

Ce qui donne :

install docusaurus navbar

Modification de la page d’accueil de Docusaurus

La page d’accueil se trouve dans le fichier /src/pages/index.tsx. Comme dit plus haut, Docusaurus est basé sur le framework React. Si vous n’êtes pas à l’aise avec le TypeScript, vous pouvez renommer ce fichier en .old et créer un fichier index.md. Mettez-y à l’intérieur un peu de markdown ou du mdx, pour MarkDown eXtended. ↗. C’est du markdown intégrant du JSX supportant la syntaxe CommonMark ↗ du markdown.

## Mon site de Documentation

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.

Ce qui donne :

install docusaurus navbar

Si vous voulez des exemples de pages d’accueil, jetez un coup d’œil sur le showcase ↗ de Docusaurus. Cliquez sur le filtre Open-Source.

Gestion des pages de documentation

Par défaut, toute la documentation de votre nouveau site est stockée dans le dossier /docs. À moins que vous l’ayez modifié son nom dans le fichier de configuration docusaurus.config.js. Je vous conseille d’écrire toutes les pages avec du MDX.

Dans un prochain billet, nous verrons comment créer de la documentation versionnée.

Classement des sections de la documentation

Vous pouvez créer des structures de dossiers pour stocker vos pages de documentation. Pour les classer, il suffit d’ajouter au dossier un fichier portant le nom _category_.json dont le contenu est le suivant :

{
  "label": "Terraform",
  "position": 3,
  "link": {
    "type": "generated-index",
    "description": "Documentations Terraform"
  }
}

label : Le nom de la section
position : L’ordre d’apparition dans la section du niveau supérieur. S’il est absent l’ordre se fait suivant celui de l’alphabétique ascendant.
link.type : Le contenu des liens. Ici autogénéré avec le contenu du dossier de la section.

Entête (frontmatter) des fichiers de documentations

Maintenant, intéressons aux informations stockées dans chacune des pages de documentations écrites en MDx, MD et permettant de l’enrichir avec des meta-data. C’est ce qu’on appelle le frontmatter.

---
id: 1
title: Titre de la page de doucumentation
---
# Ma documentation

Par défaut, Docusaurus construit les URL des articles de ce sous-dossier en se basant sur l’ID : domaine.com/docs/{id}. En ajoutant l’option slug vous pouvez forcer ce lien à autres choses. Personnellement, je l’utilise pour ma future migration de mon blog afin de ne pas perdre mon référencement.

Ecrire un Blog avec docusaurus

Docusaurus comprend un module de blog. Disposer d’un blog à côté de votre site de documentations peut s’avérer très utile pour informer vos utilisateurs des changements survenus dans votre projet.

Les pages de votre blog sont stockées dans le dossier /blog. Comme pour les pages de documentations, elles sont écrites en markdown étendue (MDX). Le nom doit être de la forme suivante : yyyy-mm-dd-titre.md. Docusaurus utilise les informations de dates pour classer les billets de blog.

Un exemple :

├── blog
│   ├── 2021-08-26-welcome
│   ├── 2019-05-29-long-blog-post.md
│   ├── 2019-05-28-first-blog-post.md
│   ├── authors.yml
│   └── 2021-08-01-mdx-blog-post.mdx

L’entête des pages de blog de Docusausrus

Chaque article se compose d’une partie entête (frontmatter), de cette forme :

---
title: Introduction à Ansible
authors: srobert

---

## Titre de niveau 2

On retrouve certains des champs des pages de documentations, avec en plus :

Title : Le titre de la page. Il faudra donc commencer directement dans votre billet par un titre de niveau 2 pour respecter la norme.
authors : Qui peut être une référence à un ou plusieurs auteurs se trouvant dans le fichier authors.yml.
tags :

Liste des auteurs

Docusaurus permet d’ajouter les auteurs aux billets de blog. Il suffit de créer un fichier nommé /blog/authors.yml avec ce genre de contenu :

srobert:
  name: Stéphane ROBERT
  title: Consultant DevOps
  url: https://github.com/stephrobert
  image_url: https://github.com/stephrobert.png

auter2:
  name: son nom
  title: son titre
  url: https://github.com/sonprojet
  image_url: https://github.com/sonimage.png

Ce qui donne :

install docusaurus navbar

Débuter avec docusaurus

Présentation de Docusaurus

Installation de Docusaurus

Création du site avec Docusaurus

Structure d’un site Docusaurus

Lancement local

Création d’un certificat local

Définir des variables du projet avec direnv

Lancement du site en local

Personnalisation de Docusaurus

Modification du Nom et de la description

Modification de la barre de navigation

Modification du pied de page

Modification du style de votre site Docusaurus

Modification de la page d’accueil de Docusaurus

Gestion des pages de documentation

Classement des sections de la documentation

Entête (frontmatter) des fichiers de documentations

Ecrire un Blog avec docusaurus

L’entête des pages de blog de Docusausrus

Liste des auteurs