Pourquoi se compliquer la vie ?

Dernièrement je me suis motivé à écrire un petit talk (que je n’ai encore proposé nulle part mais là n’est pas la question) et pour faire ça je me suis dit que, utilisant déjà du Markdown de partout, je pourrais essayer de faire toute ma présentation avec ça ? J’ai donc creusé l’internet tout entier aucune exagération ici pour trouver les différents moyens de le réaliser et ensuite choisir celui qui me convient le mieux. Après une micro-veille je suis tombé sur :

• Marp
• Pandoc
• Markdown Slides

Il en existe bien évidemment plein d’autres, mais c’étaient les trois qui semblaient sortir du lot pour répondre à mon besoin. Sachant que j’avais déjà écrit une bonne partie de ma présentation, je cherchais plus une sorte de convertisseur qu’un éditeur Markdown pur. Finalement à cause de détails dont je ne me souviens pas trop de la teneur, c’est Markdown Slides que j’ai sélectionné !

Pour voir à quoi cela peut ressembler voici le lien vers la démo.

Bref, cette longue introduction pour vous dire qu’aujourd’hui, pour la postérité (et pour moi-même), je vais vous faire un tutoriel sur ce “logiciel” (en vrai c’est un module Python mais ça compte quand même non ?).

Attention ce tutoriel ne couvre que les éléments que j’ai utilisé, il n’est donc pas exhaustif !

Installation

Le module nécessite Python dans une version supérieure ou égale à la 3.8 installée sur votre ordinateur. Si tout est en place alors une simple exécution de la ligne de commande suivante suffira :

python -m pip install git+https://gitlab.com/da_doomer/markdown-slides.git

Pour aller plus loin

L’installation du module se fera avec Reveal.js en version 4.1.3. Si vous souhaitez profiter des dernières nouveautés alors il vous faudra faire la manipulation suivante :

1. Téléchargez le code source de la dernière release de reveal.js.
2. Rendez vous dans le dossier d’installation du module (souvent $PYTHON_PATH\Lib\site-packages\mdslides).
3. Rendez vous dans le dossier reveal.js.
4. Remplacez l’intégralité du contenu du dossier par celui du dossier téléchargé juste avant (le code source).

Et voilà ! Chaque utilisation du script utilisera désormais la dernière version de Reveal.js.

Utiliser le script

Pour utiliser le script la commande ressemble à cela :

python -m mdslides [-h] [--include RESOURCE] [--pdf] [--output_dir OUTPUT_DIR] FILE

Tous les élements entre crochets sont optionnels. Voilà leurs significations :

• -h permet d’afficher l’aide du module.
• --include RESOURCE permet d’ajouter un dossier ou un fichier à inclure dans la présentation. Il peut y avoir plusieurs fois cette option si vous avez plusieurs dossiers par exemple.
• --pdf permet d’exporter en pdf (nécessite Chromium d’installer sur votre machine). Je n’ai jamais réussi à faire marcher cette option, du coup je vous donnerai une autre manière de faire plus loin dans l’article
• --output_dir permet de préciser le dossier dans lequel la présentation sera générée, par défaut un dossier au nom du fichier d’entrée.

La sortie de cette commande sera un dossier dans lequel il y aura tous les éléments nécessaires et notamment un fichier index.html qui vous permettra d’ouvrir votre présentation dans le navigateur de votre choix.

Voici un exemple simple pour mieux se représenter ça :

python -m mdslides .\presentation.md --include media

Ici le fichier entrant est presentation.md , la sortie sera dans un dossier intitulé presentation et les éléments inclus dans le dossier media, qui est au même niveau que le fichier initiale, seront ajoutés dans la présentation finale.

Écrire sa présentation

Nous rentrons enfin dans le vif du sujet ! Comment faire de votre si beau fichier Markdown une présentation encore plus belle ? Les éléments nécessaires au fonctionnement du script sont ajoutés sous forme de commentaire, donc pas d’inquiétude, votre fichier final restera propre et lisible dans une visionneuse.

Paramètres initiaux pour Reveal.js

Les paramètres entrants pour reveal.js sont insérés en début de présentation sous forme de commentaires. Il s’agit des paramètres qui se trouvent dans la doc de reveal.js sans avoir besoin d’apporter de modifications.

Exemple pour gérer les thèmes :

[comment]: # (THEME = moon)
[comment]: # (CODE_THEME = base16/zenburn)

Les thèmes sont trouvables ici pour les slides et ici pour le code inséré.

Exemple pour les paramètres optionnels :

[comment]: # (controls: true)
[comment]: # (keyboard: true)
[comment]: # (markdown: { smartypants: true })
[comment]: # (hash: false)
[comment]: # (respondToHashChanges: false)
[comment]: # (center: true)
[comment]: # (touch: true)
[comment]: # (width: 1440)
[comment]: # (height: 900)

Pour plus d’informations je vous renvoie à la documention de reveal.js à ce sujet et si vous ne souhaitez pas vous compliquer la vie, vous pouvez reprendre la configuration initiale présente dans l’exemple sur le Gitlab.

Séparer ses slides

Une nuance ici est que votre présentation peut avoir des slides horizontales ou des slides verticales. La navigation dans votre présentation sur le navigateur pourra se faire avec les touches du clavier par exemple.

Si vous avez des slides dans les deux sens, l’ordre pourrait ressembler à cela par exemple :

Slides horizontales

L’ajout de la ligne suivante dans votre fichier permet de marquer une séparation entre deux slides horizontales :

[comment]: # (!!!)

Slides verticales

L’ajout de la ligne suivante dans votre fichier permet de marquer une séparation entre deux slides verticales :

[comment]: # (|||)

Si je reprends l’exemple pour l’ordre, j’ai donc le fichier suivant :

Slide 1
[comment]: # (!!!)
Slide 2
[comment]: # (!!!)
Slide 3
[comment]: # (|||)
Slide 4
[comment]: # (!!!)

Styliser sa présentation

Tous les éléments standards du markdown sont utilisables et correctement interprétés sans casser la présentation. Vos titres, élements en gras ou liens par exemple seront donc affichés tel qu’ils le seraient par un interpréteur de markdown donc n’hésitez pas à vous en servir ! Ces parties là seront donc plutôt liées aux éléments externes au markdown, tel que l’arrière-plan ou les animations.

Changer l’arrière-plan

Pour changer l’arrière-plan d’une slide il faut ajouter des éléments data-background dans le commentaire qui marque la séparation avec la slide suivante. Qu’il s’agisse d’un commentaire pour une séparation horizontale ou verticale n’a pas d’importance.

Avec une couleur fixe

Ici c’est la propriété data-background-color qui nous intéresse. Elle peut être utilisée avec les couleurs standard du CSS, la codifications RGB rgb(R,G,B) et la codifications HSL hsl(H,S,L).

Exemples :

[comment]: # (!!! data-background-color="cornflowerblue")
ou
[comment]: # (!!! data-background-color="rgb(222, 88, 51)")

Avec un dégradé de couleur

Nécessite reveal.js > 4.4

La propriété à ajouter ici est data-background-gradient. Tous les gradients possibles en CSS sont faisables.

Exemples :

[comment]: # (!!! data-background-gradient="linear-gradient(to bottom, #283b95, #17b2c3)")
ou
[comment]: # (!!! data-background-gradient="radial-gradient(#283b95, #17b2c3)")

Avec une image

L’ajout d’une image en fond d’écran implique plusieurs propriétés. La principale est data-background-image qu’il faut accompagner du chemin vers l’image à utiliser. Il y a ensuite 4 options ajustables pour l’image :

Exemple avec une image background.png stocké dans un dossier media :

[comment]: # (||| data-background-image="media/background.png" data-background-size="contain" data-background-repeat="no-repeat")

Autres options

Il y a aussi possibilité d’utiliser des vidéos ou des iframes en arrière-plan, les infos sont ici.

Créer du mouvement

Modifier les transistions

La transition par défaut est slide mais d’autres sont possibles :

• slide
• none
• fade
• convex
• concave
• zoom

Il faudra ajouter la propriété data-transition dans le commentaire de séparation de slides pour ajuster la transition. Il est aussi possible de changer la vitesse de transition entre default, fast, slow grace à la propriété data-transition-speed.

Exemple :

[comment]: # (!!! data-transition="fade" data-transition-speed="slow")

Animer ses slides

Il est possible de créer des animations entre les slides via la propriété data-auto-animate. Pour utiliser cette dernière, il faut répéter les éléments sur plusieurs slides consécutives en ajoutant ou modifiant les éléments qui doivent être animés.
Le rendu est propre sur le fichier HTML mais lors de la transformation en PDF cela risque de faire apparaitre un grand nombre de slides transitoires. A vous de voir ce que vous souhaitez faire.

L’exemple ci-dessous permet l’affichage d’une liste avec révélation des éléments petit à petit :

# Liste à animer
- 1er élément

[comment]: # (!!! data-auto-animate)

# Liste à animer
- 1er élément
- 2ème élément

[comment]: # (!!! data-auto-animate)

# Liste à animer
- 1er élement
- 2ème élément
- 3ème élément

[comment]: # (!!! data-auto-animate)

Il est aussi possible d’ajouter une petite animation sur son code pour mettre en avant des lignes dans un ordre particulier. Dans l’exemple de Markdown Slides, les lignes 1 et 2 sont mises en avant ensemble, puis la ligne 3 et enfin la ligne 4.

```js [1-2|3|4]
let a = 1;
let b = 2;
let c = x => 1 + 2 + x;
c(3);
```

Pour plus de détails sur les animations et la puissance de auto-animate, je vous invite à consulter la documentation de Reveal.js à ce propos

Ajouter des notes

Il est possible d’ajouter des notes sur votre présentation. Ces notes seront accessibles en appuyant sur la touche s une fois la présentation ouverte dans votre navigateur.

Attention il vous faudra probablement autoriser les pop-ups et ensutie réappuyer sur s.

L’ajout de notes se fait simplement via le mot-clé Note, en respectant la casse et la disposition présentée dans l’exemple ci-dessous.

[comment]: # (!!!)

Ceci est ma slide.
Si j'appuie sur S je révèle es choses...
 
Note:
Insérer ici mon terrible secret
 
[comment]: # (!!!) 

Autres possibilités

Comme dit initialement, je n’aborde pas ici toutes les possibilités du module python et de reveal.js. Si vous souhaitez approfondir alors l’exemple fourni dans le gitlab vous donnera un peu d’inspiration et le reste se trouve dans la documentation de reveal.js !

Exporter en PDF

Via le module python

Comme présenté dans la partie Utiliser le script, il vous faudra installer Chromium et utiliser l’option --pdf dans la ligne de commande pour déclencher l’export en pdf de votre présentation.

Via Decktape

Comme évoqué plus haut, je n’ai pas réussi à faire fonctionner l’export pdf du module python, malgré mon installation de Chromium. Je vous présente donc ici Decktape.

Je vais aborder ici uniquement ce que j’ai utilisé, il y a de nombreuses options et possibilités que je vous laisserai découvrir par vous-même.

Pour utiliser ceci, il vous faudra la dernière version de Node.JS d’installer sur votre machine.
Une fois installée, ou si c’est déjà le cas alors la commande suivante permettra l’installation :

npm install -g decktape

C’est la commande decktape qui vous permettra désormais d’exporter vos présentations. Elle se présente sous la forme suivante :

decktape [options] [command] <url> <filename>

Les options sont nombreuses et toutes présentées dans le dépot Github ou en tapant decktape -h. J’utilise les suivantes :

• -s pour déterminer la taille des slides, par souci de cohérence je mets ici les mêmes valeurs que celles choisies dans les paramètres initiaux de ma présentation.
• --pdf-author & --pdf-title pour ajouter des métadonnées au PDF généré.

Voici un exemple pour plus de clarté :

decktape -s '1440x900' --pdf-author 'Thomas' --pdf-title 'Titre' .\index.html mapresentation.pdf

Dans cet exemple, on voit que la présentation à transformer est dans le dossier dans lequel je me trouve (.\index.html) et que la sortie devra être un fichier mapresentation.pdf dans ce même dossier.

Le mot de la fin

Vous avez désormais tous les éléments pour faire une superbe présentation avec cet outil !
Merci d’avoir lu ce tutoriel, j’espère vous avoir fait découvrir quelque chose et qu’il pourra vous être utile. De mon côté je vais essayer de mettre en ligne la présentation que j’ai réalisée pour pouvoir ajouter un exemple des possibles ! Amusez-vous bien !