· 6 min read

Une documentation avec Docusaurus et GitLab Pages

Objectifs

  • Nous allons voir ensemble comment publier hyper simplement une documentation avec Docusaurus et GitLab Pages.

  • Nous verons Ă©galement comment ajouter un moteur de recherche sans utiliser une solution externe d’indexation.

Création d’un nouveau projet Docusaurus en local

Vous devez disposer de Node.js sur votre poste pour la suite.

  • CrĂ©ons tout d’abord un nouveau projet Docusaurus
npx create-docusaurus@latest yoandev-doc classic
  • Entrons dans le repertoire du projet
cd yoandev-doc
  • Et lançons le serveur de dĂ©veloppement
npx docusaurus start

Personalisons du projet

Le fichier docusaurus.config.js

Une très grande partie de la configuration de notre Docusaurus va être effectuée dans le fichier docusaurus.config.js.

Nous y reviendrons plus tard quand nous allons héberger notre Doc sur GitLab Pages.

  • Commençons par modifier le titre et le slogan
const config = {
  title: 'YoanDev Doc',
  tagline: 'Documenter c\'est cool !',
  • Puis changeons le nom dans le menu
navbar: {
  title: 'YoanDev Doc',
  logo: {
    alt: 'My Site Logo',
    src: 'img/logo.svg',
  },
  • Nous pouvons aussi changer la phrase dans le footer
copyright: `Copyright © ${new Date().getFullYear()} YoanDev Doc. Built with Docusaurus.`,

Le fichier src/css/custom.css

Nous allons changer la charte graphique de notre Docusaurus. Pour cela nous allons nous aider du générateur de style de Docusaurus.

L’avantage d’utiliser le générateur c’est qu’il nous affiche notre note sur le contraste et permet de rendre notresite plus accessible.

  • Commençons par customiser la version dark
[data-theme='dark'] {
  --ifm-color-primary: #b3dde6;
  --ifm-color-primary-dark: #94cfdc;
  --ifm-color-primary-darker: #85c8d7;
  --ifm-color-primary-darkest: #57b4c8;
  --ifm-color-primary-light: #d2ebf0;
  --ifm-color-primary-lighter: #e1f2f5;
  --ifm-color-primary-lightest: #ffffff;
}
  • Et la version light
:root {
  --ifm-color-primary: #043c48;
  --ifm-color-primary-dark: #043641;
  --ifm-color-primary-darker: #03333d;
  --ifm-color-primary-darkest: #032a32;
  --ifm-color-primary-light: #04424f;
  --ifm-color-primary-lighter: #054553;
  --ifm-color-primary-lightest: #054e5e;
}

Le contenu de notre documentation

Supression de la section Blog

Pour notre exemple, nous allons désactiver la partie blog.

  • Supprimons la partie Blog en deux Ă©tapes
    • Supprimons le repertoire blog
    • Supprimons le lien Blog de nos menus dans le fichier docusaurus.config.js
// La ligne Ă  supprimer pour le Menu du Header !
{to: '/blog', label: 'Blog', position: 'left'},

// Les lignes Ă  suppriler pour le footer :)
{
  label: 'Blog',
  to: '/blog',
},

Produire du contenu

L’objectif de Docusaurus c’est bien de produire de la documentation et de la rendre accessible dans une belle interface ! Allons-y !

L’un, si ce n’est le plus grand, avantage de Docusaurus c’est ça capacité à générer un site statique à partir de simple fichier Markdown !

Par defaut, le projet vous montre quelques exemple de fichiers, et les quelques spécificités de syntaxe propre à Docusaurus, n’hesitez pas à y jetter uncoup d’oeil !

Ajoutons un nouvelle section dans notre documentation

  • Ajoutons un nouveau repertoire docs/yoandev-doc
  • CrĂ©ons un fichier _category_.json Ă  la racine de ce repertoire et ajoutons-y quelques informations
{
  "label": "YoanDev - Doc",
  "position": 4
}
  • Dans ce repertoire crĂ©ons un fichier demo.md
  ---
  sidebar_position: 1
  ---

  # Ceci est un H1

  ## Ceci est un H2

  ### Ceci est un H3

  **Texte en gras**

  *Texte en italique*

  Ceci est une liste :

  * Lorem
  * ipsum

  > Ceci est un citation

  :::danger Ceci est le titre du bloc !
  Ceci est un blog de **danger**
  :::

  :::success
  Ceci est un blog de **success**
  :::
  • Nous constatons que notre documentation est dèja disponible dans notre Docusaurus !

Ajoutons la prise en charge de PHP pour les blocks de code

  • Pour constater le problème que nous allons rĂ©soudre, ajoutons Ă  la fin de notre fichier demo.md deux blocs de codes
    ```js
    // Ceci est un extrait de code JS
    const foo = {
      bar: 'John Doe',
    }

// Ceci est un extrait de code PHP
$foo = ['bar' => 'John Doe'];


* Nous constatons que la coloration syntaxique n'est présente que pour le block de code **JS** et pour PHP.

![](./img/2022-02-19-19-12-54.png)

* Ouvrons le fichier ```docusaurus.config.js``` et ajoutons-y la configurations suivante

```js
prism: {
  theme: lightCodeTheme,
  darkTheme: darkCodeTheme,
  // Ajoutons le php avec cette ligne
  additionalLanguages: ['php'],
},
  • Cette fois-ci, plus de problèmes avecle PHP !

La mise en place sur GitLab Pages

Création du repo

Pour la suite de l’article, un compte gratuit sur GitLab.com est nécessaire

Deux étapes indispensables (non documentées ici) avant de passer à la suite:

  • CrĂ©er votre repo GitLab
  • Faites un git push du projet sur le repo sans aucune modifications pour le moment

Ajout d’un pipeline pour le déploiement

La publication de notre Docusaurus sera piloter par un pipeline GitLab CI (Et si les pipeline CI/CD vous interesse, vous pouvez jetter un cop d’oeil à ma formation sur le sujet)

  • CrĂ©ation d’un fichier .gitlab-ci.yml Ă  la racine du projet, avec le contenu suivant :
image: node:15.12-alpine3.13

stages:
  - test
  - deploy

test:
  stage: test
  script:
    - npm install --force
    - npm run build

pages:
  stage: deploy
  script:
    - npm install --force
    - npm run build
    - mv ./build ./public
  artifacts:
    paths:
    - public
  only:
    - pages

  • Ce fichier, va faire les choses suivantes :

    • Lors d’un push: lancer un npm run build pour vĂ©rifier que le build fonctionne bien
    • Lors d’un push, ou merge request sur la branche pages: lancer le build et gĂ©nĂ©rer un artefact avec la version statique de notre Docusaurus

  • On commit et on push

La branche pages

  • CrĂ©ons la branche pages depuis GitLab (cela devrait immĂ©diatement lancer le pipeline de dĂ©ploiement)

  • Une fois la CI/CD exĂ©cutĂ©e, dans Settings > Pages, activons le https et faisons un save changes

  • Et testons la page (l’obtebtion du certificat pour le HTTPS peut ne pas ĂŞtre immĂ©diat !)

Adpatons le projet à notre dépot GitLab

  • Modifions notre fichier docusaurus.config.js avec les adresses de notre dĂ©pot
const config = {
  title: 'YoanDev Doc',
  tagline: 'Documenter c\'est cool !',
  url: 'https://yoandev.co.gitlab.io',
  baseUrl: '/yoandev-doc-prepa/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'yoandev', // Usually your GitHub org/user name.
  projectName: 'yoandev-doc-prepa', // Usually your repo name.

  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          // Please change this to your repo.
          editUrl: 'https://gitlab.com/yoandev.co/yoandev-doc-prepa/-/edit/master/',
        },
        blog: {
          showReadingTime: true,
          // Please change this to your repo.
          editUrl:
            'https://gitlab.com/yoandev.co/yoandev-doc-prepa/-/edit/master/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],
  ],
  • Et faisons une Merge Request de Master vers Pages, et constatons le rĂ©sultat 🚀

BONUS : Ajoutons un moteur de recherche

Il existe des solutions plus performante pour mettre en place un moteur de recherche, mais celle-ci à le bon gout de fonctionner simplement, rapidement, y compris pour un dépot privé (et donc un GitLab Pages non accessible à tous le monde)

npm install
npm install @cmfcmf/docusaurus-search-local
  • Ajoutons la recherche dans le fichier docusaurus.config.js
// ...
plugins: [
    [
      require.resolve("@cmfcmf/docusaurus-search-local"),
      {
        language: "fr",
      }
    ],
  ],
themeConfig:
// ...
  • Et finalement testons
npm run build
npm run serve

  • Il ne nous reste qu’à commit + push + MR sur la branche pages !

Conclusions

Nous venons de voir comment mettre en ligne hyper simplement un site statique de documentation à l’aide de plusieurs outils : Docusaurus, Gitlab CI et GitLab Pages !

Vous n’avez plus aucunes excuse pour ne pas écrire et partager de la documentations avec vos collègues (vous devriez vous faire des plateformes de doc !), pour vos clients ou vos utilisateurs !

Nous allons poursuivre prochainement notre découverte des outils de génération de sites statique (jamstack) avec un générateur super cool pour un blog… rendez vous bientôt !

Share:
Back to Blog