Dans ce billet de blog, nous allons voir comment préparer des slides comme celles-ci à partir d’un contenu rédiger en markdown grâce à Pandoc et Reveal.js.

Cela permet de rédiger efficacement vos présentations, avec une facilité de mise à jour du thème dont les modifications sont prises en compte sur toutes les slides et la possibilité de créer des présentations modulaires aisément en compilant plusieurs fichiers de contenu précédemment rédigés en une nouvelle présentation.

1. Les outils - Pandoc et Reveal.js 🔗

Pandoc est un outil qui convertit des documents depuis un format source vers un format de destination différent. Il supporte de nombreux formats comme par exemple le Markdown, le LaTeX, le HTML et le PDF. La liste complète est disponible dans la documentation (man pandoc) ou via les commandes pandoc --list-input-formats et pandoc --list-output-formats. Nous nous servirons de Pandoc pour écrire le contenu de nos slides en markdown, mais vous l’aurez compris, d’autres formats sont supportés.

Reveal.js est une librairie de création de présentations semblables à PowerPoint mais au format web, grâce aux langages HTML, CSS et JavaScript. Sa particularité réside dans le défilement des slides vertical au sein de chaque section majeure, et un défilement horizontal pour passer de l’une à l’autre.

L’installation de Pandoc est requise sur votre machine d’édition, pour cela je vous renvoie vers la documentation officielle. Pour Reveal.js, l’installation ne sera utile que si vous souhaitez créer un thème personnalisé, nous en reparlerons plus loin.

2. Création d’une présentation simple 🔗

Pour créer une présentation, il suffit de rédiger un simple et unique fichier en markdown. Il est constitué d’une première partie contenant les metadata au format YAML entre deux lignes ---.

La suite du fichier contient le contenu, organisé par section via les titres de niveau 1.

Voici un premier exemple :

 1---
 2title:  Présentation d'exemple
 3subtitle: Depuis markdown jusqu'aux slides
 4author: Synoptik Labs
 5description: Exemple de présentation rédigée en markdown avec Pandoc et Reveal.js
 6---
 7
 8# Partie 1
 9
10## Partie 1 slide 1
11
12Contenu de la première slide
13
14---
15
16Contenu de la deuxième slide
17
18## Partie 1 slide 3
19
20Contenu de la troisième slide
21
22# Partie 2
23
24## Partie 2 slide 1
25
26Contenu de la première slide de la deuxième partie

Un second exemple plus complet est disponible sur notre github.

Pour transformer le fichier markdown au format reveal.js, il suffit alors d’utiliser Pandoc avec les options suivantes :

1pandoc -t revealjs -s exemple.md -o exemple.html

La présentation est prête à être visualisée via votre navigateur préféré.

Pour exporter la présentation au format PDF, une fois ouverte dans votre navigateur, ajoutez l’argument ?print-pdf à la fin de l’URL puis utiliser la fonction impression pour l’enregistrer.

3. Les options Pandoc et Reveal.js 🔗

3.1 Options en CLI 🔗

Il faut différencier les options pandoc et les options reveal.js. Nous allons voir seulement une fraction des options disponibles.

3.1.1 Options pandoc 🔗

1. --table-of-contents=true et --toc-depth=NUMBER

La première option permet d’activer la table des matières, qui sera présente sur une slide dédiée, tandis que la seconde permet de définir les niveaux de titre à inclure dans cette table des matières.

2. --embed-resources=true

Cette option permet d’intégrer toutes les ressources (CSS du thème, images, etc.) au fichier HTML de sortie. Le fichier sera inévitablement plus volumineux, mais la présentation restera fonctionnelle si ces ressources ne sont plus accessibles.

3.1.2 Options reveal.js 🔗

Les options reveal.js se passent via l’option pandoc --variable sous le format --variable VARIABLE=VALEUR.

1. --variable theme="white"

Cette option permet de définir le thème utilisé pour la présentation. Plusieurs templates par défaut sont disponibles.

2. --variable slideNumber="'c'"

Celle-ci active l’affichage du numéro de la slide.

3. --variable navigationMode="linear"

Permet de supprimer les slides verticales et avoir une présentation horizontale uniquement.

3.2. Fichier de configuration YAML 🔗

Les options sont nombreuses, elles peuvent être modifiées pour chacune des présentations selon les besoins, rendant l’usage et l’organisation plus complexe. C’est pourquoi nous allons voir comment simplifier l’usage de ces options via un fichier de configuration. L’option à utiliser est --default=FILE ou -d FILE. Nous allons également déplacer les metadata présentes au début du fichier markdown dans ce fichier de configuration.

Voici un exemple de fichier de configuration qui remplace l’usage des options présentées ci-dessus :

 1metadata:
 2  title: Présentation d'exemple
 3  author: Synoptik Labs
 4  date: 09 octobre 2023
 5input-file: exemple.md
 6output-file: exemple.html
 7table-of-contents: true
 8toc-depth: 1
 9variables:
10  theme: white
11  slideNumber: "'c'"
12standalone: true

L’appel à pandoc est alors fortement simplifié : pandoc -t revealjs -d configuration.yml

4. Organiser ses présentations en modules 🔗

Les présentations sont parfois complexes ou longues, peuvent reprendre ou partager du contenu avec d’autres présentations. Avec pandoc, il est possible de créer une présentation à partir de plusieurs fichiers sources markdown fournis en entrée. Il suffit alors de spécifier tous les fichiers à inclure en modifiant les lignes correspondantes dans le fichier de configuration :

1input-file:
2  - markdown/0-introduction.md
3  - markdown/1-partie1.md
4  - markdown/2-partie2.md
5  - markdown/3-conclusion.md

5. Personnalisation du template 🔗

Pour créer un template personnalisé, la démarche détaillée est expliquée ici.

Première étape, installez reveal.js en local en suivant les étapes suivantes :

1git clone https://github.com/hakimel/reveal.js.git
2cd reveal.js
3npm install

Créez un nouveau fichier SCSS en vous basant sur le thème de votre choix. Modifiez à souhait ce fichier pour créer un template sur mesure.

Ensuite, il vous faut compiler le SCSS en CSS : npm run build -- css-themes

Une fois le thème prêt, il ne vous reste plus qu’à générer la présentation avec celui-ci grâce aux options :

1. --variable theme="custom"
2. --variable revealjs-url:/PATH/TO/FOLDER/reveal.js

6. Conclusion 🔗

Nous avons pu voir comment créer une présentation en markdown. Nous avons vu une partie des options disponibles. Pour rappel, un exemple de présentation complète est disponible sur notre github et visible ici.

Pour aller plus loin, consultez les différentes documentations et n’hésitez pas à nous partager vos tips !