Tuto : "produire une documentation de type Gitlab pages au format MKDocs"
Le 7 février 2024
Bonjour, nous allons vous montrer ici combien il est facile de documenter votre projet Gitlab avec des fichiers MKDocs et disposer ensuite d’un site Web respectant la charte de l’Etat et son système de Design.
Le seul prérequis est d’avoir ouvert un compte sur la plateforme Gitlab, tout simplement !
Dans notre cas, nous disposons de fichiers au format markdown que nous souhaitons reprendre et voir figurer sur notre site.
Comme indiqué à l’écran, nous disposons d’un répertoire dans lequel nous créons et mettons en forme nos fichiers spécifiques avec un éditeur de texte permettant de générer du format markdown. Ici, il s’agit du logiciel Zettlr.
Si nous prévoyons d’afficher des images, il faut penser à les stocker dans un sous-répertoire img.
Une fois nos fichiers markdown préparés, nous allons maintenant créer le projet sur GitLab.
Nous allons créer un projet vide, en prenant bien soin de décocher la case proposant d’initialiser le repository.
Ceci fait, nous allons nous rendre dans le menu de paramétrage CI/CD et autoriser notre projet à utiliser les runners partagés.
Il nous reste à cloner le projet exemple dont l’URL s’affiche à l’écran, ainsi que le QRCode :
https://gitlab-forge.din.developpement-durable.gouv.fr/pub/numeco/mkdocs-dsfr-exemple
Passons à présent à la génération du site Gitlab Pages à proprement parler.
Tout d’abord, nous allons copier nos fichiers mkdocs dans le repository local créé suite au clonage du projet exemple.
Nous allons ensuite apporter les modifications pour adapter le site à notre contexte, en personnalisant le fichier mkdocs.yml, pour changer le titre du site, ou la structuration du menu de navigation.
Après avoir effectué un commit des modifications souhaitées, nous pouvons revenir sur la page du projet Gitlab et visualiser la progression de nos jobs de déploiement, automatiquement lancés après mise à jour du repository.
Il nous reste à vérifier le résultat obtenu en accédant à notre site ainsi généré. Nous pouvons constater que le site généré respecte parfaitement la charte de l’Etat, sans aucune action de notre part ! Nous pouvons nous concentrer sur la mise à jour du contenu de notre documentation, sans nous soucier du rendu final puisque celui-ci sera automatiquement géré !