Déployer ses présentations sur gitlab pages, avec reveal.js, docker et gitlab-ci

Comme souvent quand je commence un support de formation, je passe (perd ?) du temps à modifier mon process pour gérer mes slides. Après un site drupal me permettant de gérer mes support, j'ai testé une nouvelle approche, plus véloce encore.

Je fais maintenant mes slides directement dans un fichier markdown, qui est ensuite interprété directement par reveal.js et publié sur gitlab page. Cette approche est entièrement gratuite, très rapide, et assez pratique dans le cadre de la réutilisation d'une présentation et mise à jour. Évidement c'est complètement overkill par rapport à une simple présentation powerpoint ou google slides mais bon... ¯\_(ツ)_/¯

Comment cela fonctionne ?

Première chose : création d'un « groupe » sur gitlab, j'ai appelé le mien « Formations Kgaut.NET » : https://gitlab.com/formations-kgaut, je l'ai mis en public mais cela marche aussi en privé.

La partie template

J'ai ensuite créé un dépôt « template » : https://gitlab.com/formations-kgaut/template-reveal-js, qui va s'occuper de créer une image docker en récupérant la dernière version de reveal.js, ajouter mon fichier css personnel et publier une image docker sur le registry de gitlab : https://gitlab.com/formations-kgaut/template-reveal-js/container_regist…

Voici les différents fichiers de ce dépôt.

Le Dockerfile qui générera l'image :

FROM alpine:latest

# Récupération de la dernière version de reveal.js
RUN wget -O reveal.zip https://github.com/hakimel/reveal.js/archive/master.zip

# Extraction de l'archive
RUN unzip reveal.zip -d reveal

# Création d'un dossier public pour stocker notre future présentation
RUN mkdir /public

# Copie des assets nécessaires reveal.js
RUN mv reveal/reveal.js-master/dist /public/
RUN mv reveal/reveal.js-master/plugin /public/

# Copie du fichier index.html modifié (gestion du markdown, et lien vers le fichier css custom)
COPY ./index.html /public/

# Copie des styles custom
RUN mkdir /public/custom
COPY ./custom.css /public/custom/

Fichier index.html de reveal.js pour prendre en compte le markdown et lier le fichier css custom : https://gitlab.com/formations-kgaut/template-reveal-js/-/blob/main/inde…

Image

À noter :

le jeton [TITLE] qui sera remplacé par le nom du dépôt de la présentation cible
le lien vers un fichier custom.css me permettant de surcharger un peu les styles (https://gitlab.com/formations-kgaut/template-reveal-js/-/blob/main/cust…)

le fichier .gitlab-ci.yml qui va construire l'image en utilisant le Dockerfile et la pousser dans le registry du projet :

image: docker:latest
services:
- docker:dind

build-image:
  script:
    - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
    - docker build -t $CI_REGISTRY_IMAGE .
    - docker push $CI_REGISTRY_IMAGE

L'ensemble des variables sont des variables prédéfinies par gitlab, nous n'avons rien à configurer.

Une fois tout ça poussé dans votre dépôt, vous pouvez vérifier que la ci s'est bien passée :

Image

Et l'on peut aussi vérifier dans « Packages & Registries / Container Registry » que l'image est bien présente :

Image

Cette image sera maintenant utilisé par l'ensemble des présentations que nous allons créer.

Création d'une présentation

Chaque présentation sera un dépôt, avec au minimum deux fichiers :

slides.md : Fichier markdown contenant le contenu de la présentation

.gitlab-ci.yaml : Configuration de la CI qui va récupérer l'image précédement créée, copier le fichier slides.md, modifier le titre, puis publier la présentation sur gitlab pages.

le fichier slides.md (https://gitlab.com/formations-kgaut/poc-presentation/-/blob/main/slides…)

# Présentation Reveal.js
## Gitlab-CI + Gitlab Pages

--

# Une slide verticale

Juste par exemple

---

# Comment ça marche ?
1. Un projet template qui intègre reveal js dans une image docker : https://gitlab.com/formations-kgaut/template-reveal-js
2. Un sous projet, comme celui là, qui contient les slides et utilise l'image docker précédemment crée
3. La CI de ce projet publie la présentation automatiquement à chaque modification sur gitlab page.

--

# Intéret ?
- Rédaction de présentation très rapide
- Historique des modifications
- Fork pour réutiliser / faire une nouvelle version de présentation

Les séparateurs des slides sont -- pour une slide verticale et --- pour une slide horizontale (nouveau chapitre), ces séparateurs sont définis dans le template, lignes 22 et : https://gitlab.com/formations-kgaut/template-reveal-js/-/blob/main/inde…

Le fichier .gitlab-ci.yaml

stages:
  - pages

pages:
  image: registry.gitlab.com/formations-kgaut/template-reveal-js:latest
  stage: pages
  script:
    - mv /public public
    - mv slides.md public/slides.md
    - sed -i "s/\[TITLE\]/$CI_PROJECT_TITLE/g" public/index.html
  artifacts:
    paths:
      - public

La partie image fait référence à l'image construite précédemment dans le registry, on peut retrouver l'url ici :

Image

Les autres commandes copient le fichier slides.md dans l'image, modifie la balise title du fichier html en utilisant le nom du dépôt.

Et le résultat est publié sur gitlab page. Pour trouver l'url du site déployé, rendez-vous dans « Settings / Pages » :

Image

Dans mon cas, la présentation est visible à l'adresse : https://formations-kgaut.gitlab.io/poc-presentation elle est librement accessible à tous car le dépôt est public, s'il avait été privé, uniquement les utilisateurs ayant accès au dépôt auraient accès au site.

Ensuite, dès qu'une modification est faite sur les slides, la nouvelle version de la présentation est déployée, c'est ultra rapide, généralement moins d'une minute.

Pour récapituler

Le dépôt du template : https://gitlab.com/formations-kgaut/template-reveal-js

Le dépôt d'une présentation d'exemple : https://gitlab.com/formations-kgaut/poc-presentation

La présentation sur Gitlab Page : https://formations-kgaut.gitlab.io/poc-presentation/

On peut faire ainsi autant de présentations que l'on veut qui se baseront sur la même image, certaines peuvent être privée et d'autres librement accessibles en fonction des paramètres du dépôt.

Pour réaliser ça je me suis grandement inspiré de ce post : https://blog.jdriven.com/2020/10/automating-hosting-revealjs-slides-on-…