Markdown on Zwindler's Reflection

J'ai enfin migré de Wordpress vers Hugo - partie 2

Mon, 29 Nov 2021 08:00:00 +0000

Cette article fait partie d’une suite d’articles :

Extraire les données de WordPress

Normalement si vous avez lu la première partie, vous savez qu’on a un Hugo fonctionnel (mais vide). Et que dans mon cas, l’objectif était de migrer 12 ans d’historique (350 articles tout de même) de Wordpress vers notre Hugo.

Vous vous en doutez, le but n’est pas de reprendre les articles uns par uns (sauf si vous n’en avez qu’une dizaine, ça doit se faire) mais bien de trouver une méthode pour exporter le contenu existant en markdown pour repartir comme si de rien n’était.

La documentation officielle de Hugo donne plusieurs pistes pour migrer depuis Wordpress et c’est la première que j’avais utilisé en 2019 (la première fois que j’avais tenté de migrer, sans succès). J’ai re-installé l’extension wordpress-to-hugo-exporter (je vous invite quand même à regarder les alternatives car il n’est pas impossible que ça ait évolué depuis).

wordpress-to-hugo-exporter

La première chose à faire pour installer cette extension est de vérifier que votre serveur qui héberge le WordPress dispose bien de l’extension PHP zip.so.

cat /etc/php.d/40-zip.ini
; Enable ZIP extension module
extension=zip.so

On peut ensuite cloner le projet git du plugin directement dans le dossier plugin de WordPress

cd PATH_TO_WORDPRESS/wp-content/plugins/
git clone https://github.com/SchumacherFM/wordpress-to-hugo-exporter

A partir de là, il est possible de démarrer un export soit depuis l’interface, soit via un script en PHP lancé depuis le serveur en ligne de commandes. Évidemment, dans ce genre de procédures, on arrive toujours à un moment où on se tape un timeout quelque part. Dans mon cas, les données exportées (articles + medias, environ ~1.5 Go) prenaient 500 Mo de RAM et 20 minutes d’exécution.

On oublie donc le clic dans l’interface (sauf à tuner votre nginx pour autoriser des requêtes clients avec un timeout > 60s) et on lance depuis la ligne de commande. Et bien entendu, on augmente toutes les limites possibles et imaginables, notamment celle de wordpress via le fichier wp-config.php.

// Set initial default constants including WP_MEMORY_LIMIT, WP_MAX_MEMORY_LIMIT, WP_DEBUG, SCRIPT_DEBUG, WP_CONTENT_DIR and WP_CACHE.
wp_initial_constants();
define( 'WP_MEMORY_LIMIT', '2048M' );
define( 'WP_MAX_MEMORY_LIMIT', '2048M' );

cd PATH_TO_WORDPRESS/wp-content/plugins/wordpress-to-hugo-exporter/
php hugo-export-cli.php memory_limit=-1

Qui devrait se terminer, si tout se passe bien, par un :

This is your file!
/tmp/wp-hugo.zip

Note: on peut également exporter les commentaires, il faut modifier manuellement une ligne dans le fichier hugo-export.php (voir la doc)

A partir de là, on a une archive qui contient vos posts, vos pages et vos médias importés (grosso modo tout wp-content).

L’archive a l’arborescence suivante :

un dossier posts qui contient tous les articles (posts dans la terminologie wordpress) dans un mélange de markdown + html brut (ce qui n’aura pas été correctement converti, on y reviendra)
un dossier wp-content qui contient tous les médias
des dossiers pour chacune de vos “pages (“à propos”, “mentions légales”, etc).

Importer dans Hugo

L’arborescence de Hugo est elle un peu différente. De base, tout ce qui est markdown doit être dans content, avec des sous dossiers en fonction du type de page (post ou page).

La première petite “blaguounette” est que les posts doivent être déposés dans le sous-dossier content/post (sans S à la fin !!!).

Chaque post commence par des métadonnées encadrées par des triples tirets “—” avant et après. Ca donne quelque chose comme ça :

---
title: 'ESXi 4.0 : Explorons l&rsquo;Hidden Console Part 1'
authors:
 - zwindler
type: post
date: 2010-04-28T08:32:20+00:00
url: /2010/04/28/esxi-4-0-explorons-lhidden-console-part-1/
featured_image: https://blog.example.org/wp-content/uploads/2014/10/vmware-220x162.jpg
categories:
 - Virtualisation
tags:
 - ESX(i)
 - Hidden Console
 - SSH
---

[L'article lui même...]

Ca peut différer un peu selon les thèmes je pense, mais grosso modo les markdown des pages iront eux dans content/page.

Enfin, tout ce qui est media (dossier wp-media) va dans un dossier static. On peut garder la même arborescence que wordpress (/année/mois/) mais rien ne nous y oblige.

So far, so good

Emile et Images

Enfin… so good, c’est vite dit…

Et oui parce que l’exporter n’exporte pas hyper bien un certain nombre de choses, à commencer par l’image de garde de chaque article :

featured_image: https://blog.example.org/wp-content/uploads/2014/10/vmware-220x162.jpg

On peut remarquer plusieurs soucis avec cette variable. D’abord, la variable utilisée pour indiquer le chemin de l’image dans les métadonnées générées est featured_image alors qu’Hugo attend image. Petit sed sur vos md pour corriger ça :

sed -i "s/featured_image/image/g" fichier.md

Mais bien sûr, ce n’est pas fini ;-)

Ensuite, on remarque qu’on a un chemin est une URL complète et non pas relative. Si vous gardez les média dans le chemin static/wp-content/uploads/YYYY/MM ça marchera, mais je trouve ça moche.

2 solutions :

on supprime /wp-content/uploads avec un bête sed -i "s!/wp-content/uploads!!g fichier.md
on passe en relatif en supprimant carrément toute la première partie de l’URL https://yourblog.example.org/wp-content/uploads

Si vous choisissez la 2ème solution (mon choix), faites quand même bien attention. En fonction de comment vous rédigez votre expression régulière, ça pourrait affecter aussi toutes les autres images que vous auriez en lien dans vos articles. Ce n’est pas forcément une mauvaise chose (moi j’aime mieux les liens relatifs car c’est plus flexible) mais ça demande un travail supplémentaire.

Images intermédiaires

Toujours dans les images, vous remarquerez aussi que l’image “mise en avant” (dans les métadonnées) possède un suffixe de type -111x222 juste avant l’extension. En fait, chaque fois que vous importez une image dans wordpress, celui ci la convertie en plusieurs tailles pour accélérer le chargement des pages.

Sauf que le wordpress-to-hugo-exporter choisi une des plus petites résolution pour l’image en tête de l’article. Ca sera souvent hyper moche…

Là encore, j’ai donc passé un gros sed pour virer tous les suffixes -111x222 avant l’extension, puis je n’ai copié QUE les images originales dans le dossier static (regex non triviale) :

cd PATH_TO_EXPORT/wp-content/uploads
for i in `seq 2010 1 2021`; do
 find $i -mindepth 1 -type f -regextype posix-egrep -not -iregex ".*/.*-[0-9]{1,4}x[0-9]{1,4}.*\..*" -exec cp {} PATH_TO_HUGO/static/{} \;;
done

Nettoyer les caractères spéciaux HTML

Si vous avez bien lu l’exemple de métadonnées exportées que j’ai donné, vous aurez peut être remarqué la présence d’un caractère spécial encodé ’ dans le titre.

Dans une page HTML, ce n’est pas grave, mais Hugo lui, ne les interprète pas comme tel dans le markdown. Il faut donc leur faire la chasse et tous les convertir 🤦. Et encore, il faut faire attention, car certains de ces caractères pourraient être légitimement écris en HTML (si vous faite un tuto sur HTML, ce n’est pas impossible par exemple)…

J’ai pour ma part lancé un gros sed (une fois de plus) sur tous mes articles mais prudence !

sed -i "s/&rsquo;/’/g" $1
sed -i "s/&#8211;/--/g" $1
sed -i "s/&#8230;/.../g" $1
sed -i "s/&gt;/>/g" $1
sed -i "s/&lt;/</g" $1
sed -i "s/&#8212;/-/g" $1
sed -i "s/&#8217;/'/g" $1
sed -i "s/&#215;/×/g" $1

Je n’ai pas osé modifier les caractères suivants, très souvent présents dans les URLs :

&#038
&#039
&quot;

Mais c’est quand même une bonne idée de faire une grosse recherche avec votre éditeur de texte favori pour voir s’il ne reste pas des &# qui traînent dans votre contenu.

HTML désactivé

Au delà des caractères spéciaux, il arrive aussi que l’exporter est un peu de mal avec les différents types d’éditeurs que Wordpress a pu avoir au fil du temps.

Typiquement, beaucoup du contenu “non texte” que j’ai ajouté au fil des années s’est retrouvé non converti par ce que j’ai rédigé s’est retrouvé exporté tel quel, en HTML brut inséré dans mon markdown.

C’est hyper traître car Hugo ne renvoie aucune erreur. Il manque “juste” des bouts ! On peut les retrouver en allant voir le code source de la page, qui affiche alors les commentaires HTML suivants :

<!-- raw HTML omitted -->

En attendant de nettoyer tout ça à grand coup de sed, on peut résoudre une partie des problèmes en “réactivant le support du code HTML dans le markdown dans votre config.yaml.

markup:
 goldmark:
 renderer:
 ## Set to true if you have HTML content inside Markdown
 unsafe: true

Ca permet de sauver les meubles mais ce n’est pas suffisant…

Markdown hates HTML

Même comme ça, on grosse partie du HTML sera HS… Tous les tableaux (table/tr/td) et listes (ul/li) HTML sont pétés car l’exporter laisse des sauts de lignes entre les blocs, que le markdown interprète mal. Il faudra supprimer tous les sauts de lignes en trop (ou réécrire en markdown)

<table class="Content" border="0" width="750">
<tr>
<td class="LargeBold">
SEND_CUSTOM_SVC_NOTIFICATION
</td>
</tr>
<tr>
<td class="MediumBold">
Command Format:
</td>
</tr>

Sachez également que toutes les “videos embedded” Youtube disparaîtront purement et simplement, et que pour les tweets, vous aurez une version très moche du tweet, sans l’image…

<blockquote class="twitter-tweet" data-width="550" data-lang="en" data-dnt="true" data-partner="jetpack">
 <p lang="fr" dir="ltr">
 [[#SAPHANA](ht tps://tw itter.com/hashtag/SAPHANA?src=hash&ref_src=twsrc%5Etfw)] Finies les mises à jour incompatibles avec votre plateforme, optez pour la simplicité et la tranquillité, chez SAP : on collecte, on connecte, ça marche : [t.co/2AdCCEQ97L](https://t.c o/2AdCCEQ97L) [pic.twi tter.com/yy7moMnZmC](ht tps://t.c o/yy7moMnZmC)
- SAP France (@SAPFrance)

 [October 8, 2018](ht tps://twiter.com/SAPFrance/status/1049286253533962241?ref_src=twsrc%5Etfw)
</blockquote>

J’en avais peu heureusement, j’ai donc pris des captures d’écran et ajouté des liens.

Balises de code, pre, etc.

Une autre grosse catégorie de code “mal exporté” est le “code”. Je donne souvent des bouts de scripts ou de code ou tout simplement des commandes à passer sur des serveurs. Et au fil des années, j’ai (& wordpress) changé plusieurs fois la façon d’afficher du code dans mes articles.

D’abord avec des balises HTML <pre></pre>, puis des balises <code></code>, puis via des extensions (pour avoir la coloration syntaxique), puis via du markdown via Jetpack, puis de nouveau via les extensions…

Autant dire que le HTML généré par Wordpress ne ressemble à rien…

Il a fallut faire un gros gros boulot pour détecter toutes les balises de code ouvrantes et fermantes pour les convertir en ``` de markdown…

Quelques exemples que j’ai rencontré :

<pre>

<pre class="brush: plain; title: ; notranslate" title="">
<pre class="brush: perl; collapse: false; title: ; wrap-lines: false; notranslate" title="">

<pre class="EnlighterJSRAW" data-enlighter-language="null">
<pre class="EnlighterJSRAW" data-enlighter-language="generic">
<pre class="EnlighterJSRAW" data-enlighter-language="generic" data-enlighter-theme="" >
... et bien d'autres encore

Final words

Je m’arrête là car l’article est déjà très long, mais il y a eu d’autres petits problèmes du même style, plus sporadiques…

Vous voyez donc qu’exporter le blog sur Hugo n’aura pas été de tout repos, dans mon cas. Et encore ! Je n’ai pas exporté les commentaires historiques (plus de 1600) !

Cependant, si vous avez un blog plus petit que celui ci, vous devriez avoir moins de mal et les conseils que je donne ici devraient vous permettre de régler rapidement 90% des problèmes.

Enjoy !

J'ai enfin migré de Wordpress vers Hugo - partie 1

Mon, 22 Nov 2021 08:00:00 +0000

Cette article fait partie d’une suite d’articles :

Plus de 2 ans et demi

Ca fait plus de 2 ans et demi que je râle que j’en ai ma claque de Wordpress.

Stack LEMP à maintenir, perfs bof (j’ai du mettre un cache pour passer sous la seconde, wtf…), plugins aux MAJs hasardeuses, failles de sécu, pas de support propre du markdown, éditeur à ch*** (Gutenberg, je te hais), … you name it.

Après 12 ans de blogging, il était temps de faire l’effort et de quitter Wordpress pour quelque chose qui me convient mieux : un moteur de blog statique (rien de dynamique dans ce que je poste) en markdown (parce que de toute façon c’est comme ça que j’écris mes articles à la base). Le tout dans git pour historiser tout ça.

Et j’ai choisi Hugo pour des raisons que je détaille dans l’article 2019 “Comment migrer de Wordpress à Hugo” si ça vous intéresse.

Forcément, c’est pas si facile

J’en parlais déjà dans l’article de 2019 : migrer de Wordpress à Hugo, forcément ce n’est pas si facile. D’ailleurs, j’avais même abandonné l’idée devant l’ampleur da tâche !

Ce n’est pas tant la partie technique (installation de Hugo, export du blog existant) le problème. En quelques minutes, on a un blog fonctionnel, l’export prend guère plus de temps. Rajouter l’outillage pour automatiser certaines tâches prend un peu de temps mais rien d’incroyable.

Mon problème était plutôt que je voulais obtenir au moins aussi bien que ce que j’avais avant, existant inclus.

Et c’est là que le bat blesse : wordpress, avec mes 12 ans (350 articles) d’historique, c’est au fil des années 15 façons différentes d’afficher du HTML… que le plugin d’export gère comme il peut ! Nous y reviendrons.

Je vais donc vous guider un peu sur la partie technique, puis j’aborderai ensuite les points pénibles du nettoyage du markdown, qui m’a pris un bonne partie de mes vacances (plusieurs journées à ~2-3 heures par jour). Il y aura aussi, plus tard, des articles sur l’outillage à mettre en place pour se faciliter la vie au quotidien.

Installation

L’installation en elle même est triviale. On a un binaire compilé en go packagé dans un .deb (ou les sources si vous voulez le builder vous même) disponible sur github. Fin.

sudo apt update
sudo apt upgrade

export VER="0.88.1"
wget https://github.com/gohugoio/hugo/releases/download/v${VER}/hugo_${VER}_Linux-64bit.deb
# ou https://github.com/gohugoio/hugo/releases/download/v${VER}/hugo_extended_${VER}_Linux-64bit.deb
sudo apt install ./hugo*_0.88.1_Linux-64bit.deb

A noter que dans mon cas, je n’ai pas téléchargé la version ci dessus, mais la version “extended”, nécessaire pour le thème que j’ai choisi, mais le principe est le même.

Initialisation du site et du dépôt git

Hugo est maintenant disponible sur votre machine.

A partir de là, je vous invite fortement à versionner tout ce que vous allez faire avec votre blog. C’est bien entendu optionnel mais pourquoi se priver de toute la puissance du couple markdown + git ?

On commence par créer un dossier puis on génère un squelette de site vierge avec hugo new site :

mkdir hugo && cd hugo
hugo new site toto
Congratulations! Your new Hugo site is created in toto.
Just a few more steps and you're ready to go:
1. Download a theme into the same-named folder.
Choose a theme from https://themes.gohugo.io/ or
create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".
Visit https://gohugo.io/ for quickstart guide and full documentation.

A partir de là, on va pouvoir initialiser notre dépôt git

cd toto
git init

Bon, si jamais vous lancez la génération du blog avec simplement la commande de preview hugo server, vous allez être assez déçus, ça donne une page blanche. Mais, ça marche !

hugo server
Start building sites …
hugo v0.88.1-5BC54738+extended linux/amd64 BuildDate=2021-09-04T09:39:19Z VendorInfo=gohugoio
WARN 2021/11/14 06:57:47 found no layout file for "HTML" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN 2021/11/14 06:57:47 found no layout file for "HTML" for kind "home": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN 2021/11/14 06:57:47 found no layout file for "HTML" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

 | EN
-------------------+-----
 Pages | 3
 Paginator pages | 0
 Non-page files | 0
 Static files | 0
 Processed images | 0
 Aliases | 0
 Sitemaps | 1
 Cleaned | 0

Built in 1 ms
Watching for changes in /toto/{archetypes,content,data,layouts,static}
Watching for config changes in /toto/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Ajout d’un thème

Avant même de commencer à ajouter du contenu, il est probable que vous allez vouloir choisir un thème. Il existe une liste de thèmes, plus fournie qu’en 2019, disponible ici.

Une fois le thème choisi, on va l’ajouter au site à l’aide de la (très utile) commande git git submodule qui va nous permettre de gérer notre thème et ses mises à jour avec git sans pour autant commiter tous les fichiers.

Dans mon cas j’ai choisi le thème “stack” mais le principe est grosso modo le même pour tous (à quelques détails d’implémentation près) :

cd themes/
git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git
cd ..

Avant le premier article !

Si on veut bosser un peu proprement, on va vouloir éviter de commiter n’importe quoi. Comme hugo est un générateur de blog statique, on va bien entendu éviter de commiter le code statique généré par la commande hugo.

On utilise simplement un fichier .gitignore à la racine du projet pour ignorer tout ce qui est technique ou qui n’est pas du code :

cat > .gitignore << EOF
themes
resources/_gen
assets/jsconfig.json
public
EOF

On va aussi vouloir paramétrer a minima notre site. Vous aurez peut être remarqué qu’il existe un fichier config.toml généré par défaut par la commande hugo new site. Il s’agit de “l’ancienne” manière de faire de la configuration Hugo, mais surtout d’un fichier agnostique du thème utilisée. Généralement, il vaut mieux le supprimer et repartir du fichier d’exemple inclus avec votre thème.

Dans mon cas, il s’agit du fichier theme/hugo-theme-stack/config.yaml que j’ai donc copié à la racine du projet et modifié pour correspondre à mon site et mes besoins.

baseurl: https://blog.zwindler.fr
languageCode: fr-fr
theme: hugo-theme-stack
title: "Zwindler's Reflection"
[...]

Le premier commit

C’est un petit moment agréable dans n’importe quel projet informatique. Le premier commit.

Bon moi, comme j’ai hébergé le dépôt sur Github et qu’ils ont décidé de renommer master en main dans le nom de la branche par défaut on a un peu de gymnastique à faire, mais pourquoi pas.

git add .
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:zwindler/example.org.git
git push -u origin main

Le “code” de notre (absence de) blog est publié Internet :)

Et en prod ?

Vous pouvez donc commencer à écrire (dans content/post), tester votre blog en local, puis pousser le code sur git. Mais si jamais vous voulez héberger votre site ailleurs que sur votre laptop (et je parie que c’est le cas) ?

Et bien c’est là où c’est chouette d’utiliser git et un dépôt accessible depuis Internet. Vous n’avez qu’à reproduire l’installation de hugo, ajouter votre dépôt, initialiser les submodules (notre thème) et le tour est joué !

export VER="0.88.1"
wget https://github.com/gohugoio/hugo/releases/download/v${VER}/hugo_${VER}_Linux-64bit.deb
# ou https://github.com/gohugoio/hugo/releases/download/v${VER}/hugo_extended_${VER}_Linux-64bit.deb
sudo apt install ./hugo*_0.88.1_Linux-64bit.deb

git clone https://github.com/zwindler/toto.git
git submodule init
git submodule update

hugo

Normalement, le site devrait se générer, comme en local. Si vous n’avez pas d’historique à migrer, comme moi, vous êtes donc l’heureux propriétaire d’un blog statique fonctionnel :-). La classe !

Sinon, dans le prochain article, j’aborderai un plus gros morceau, à savoir l’export et le nettoyage du markdown depuis un Wordpress existant.

Marp : présentations rapides et jolies avec Markdown

Mon, 13 Sep 2021 06:05:00 +0000

J’ai remplacé Powerpoint par Marp en 2019

Pendant des années, j’ai rédigé mes présentations professionnelles avec Powerpoint. J’étais un utilisateur correct de la suite Office en général (pas un roxxor, mais à l’aise).

Et là, c’est le drame, j’ai (enfin !) pu passer sous Linux sur ma machine pro. Ma vie est devenue tellement plus simple pour toutes mes tâches quotidiennes… SAUF… la rédaction de présentations.

J’ai vraiment pesté en passant à Libre Office. Je ne vais pas tacler ce dernier, beaucoup de la difficulté réside dans les formats ultras verrouillés de MS et le reverse engineering doit être horriblement complexe. J’ai donc commencé à chercher des alternatives.

It’s time to Duel…

J’ai donc demandé à mes petits collègues et copains speakers autour de moi ce qu’ils utilisaient comme moteur pour leurs présentations.

Grosso modo, les nerds m’ont répondu qu’ils n’avaient jamais quitté LaTeX et que pour les présentations ils utilisaient simplement Beamer, et les autres m’ont répondu Ascii doctor.

Pour la première, c’est une bonne alternative si vous n’êtes pas allergiques à la syntaxe de LaTeX (c’est mon cas). D’autant plus qu’on avait pas à l’époque d’aperçu en temps réel du code LaTeX (je ne sais pas si c’est toujours le cas) et qu’un néophyte passe beaucoup de temps à juste corriger les erreurs de syntaxe et de mise en page…

La seconde alternative est intéressante aussi. La syntaxe est plus digeste (je trouve) que LaTeX, il existe des éditeurs de texte capable de montrer un aperçu en temps réel du rendu final, et les formats d’export natifs incluent HTML 5, les manpages, les PDFs et ebooks,… bref, à peu près tout type de format récent qui peuvent intéresser un ingénieur en informatique qui partage quotidiennement sa connaissance. Sauf que la syntaxe d’AsciiDoctor est proche de celle de Markdown (au moins dans la philosophie) et pour avoir jonglé quelque temps entre les deux, il est facile de se prendre les pieds dans le tapis.

Or, j’utilisais déjà Markdown pour la rédaction de documentations de projets hébergés sur gitlab et accessoirement, pour rédiger une partie des articles de ce blog. Pour éviter mon auto-confusion et capitaliser sur mon habitude de Markdown, j’ai donc cherché une alternative à AsciiDoctor pour les présentations, mais en Markdown !

Entre alors Marp

Heureusement pour moi, j’ai trouvé très rapidement l’outil que je cherchais, et il s’appelle Marp. Pour être parfaitement précis, Marp est une collection d’outils open source (Marpit, Marp Core, Marp CLI, Marp for VSCode).

Ce que vous avez besoin de retenir c’est qu’en tant qu’utilisateur, vous n’aurez besoin que de Marp CLI si vous voulez générer vos decks de slides en ligne de commande. Un des gros intérêts de la CLI par rapport à une interface graphique est qu’elle va vous permettre d’automatiser la génération de vos decks de slide très facilement.

D’ailleurs, si ça vous intéresse, il se retrouve que Rémi Verchère a fait un article là-dessus il y a très peu de temps sur le compte Medium de LinkByNet : Making slides from anywhere for anyone using Marp, GitLab Pages and Gitpod.

Si en revanche vous préférez rédiger comme moi dans votre éditeur de texte et voir en live le support prendre forme, il existe donc aussi une extension VSCode pour Marp.

Comment ça marche ?

Grosso modo, Marp vient étendre le Markdown classique pour y ajouter :

La commande marp: true pour indiquer qu’il s’agit d’un document Marp et pas Markdown et une balise --- pour indiquer les nouvelles slides
des styles de slides et des thèmes customizables en CSS
un logiciel pour transformer le code Markdown en PDF ou HTML

Si vous êtes déjà à l’aise avec Markdown, vous remarquez donc que la prise en main est extrêmement simple. Finalement, si vous avez déjà un document Markdown, vous pouvez juste le transformer en présentation en ajoutant régulièrement des --- entre les paragraphes (j’exagère, mais vous voyez l’idée).

Et ce que j’apprécie particulièrement avec la preview Markdown, c’est qu’on a un visuel en temps réel de notre future documentation/présentation à partir de notre code.

Les styles

Out of the box, Marp propose 3 thèmes, qu’il est possible d’inverser (clair/sombre). La documentation sur ces thèmes est disponible ici.

En début de document, on indique qu’il ne s’agit pas d’un simple fichier Markdown, mais d’une présentation Marp de la façon suivante :

---
marp: true
theme: gaia
markdown.marp.enableHtml: true
paginate: true

Dans cet exemple, j’ai donc utilisé le thème Gaia, autorisé l’injection de HTML « perso » au milieu du code Markdown (on en reparlera) et ajouté le petit chiffre en fin de chaque slide avec « paginate: true ».

Bon… par défaut, c’est assez vite limité et pas super joli…

J’ai tout de suite voulu trouver d’autres thèmes (je n’en ai pas trouvé) et la documentation pour créer son propre thème est assez obscure.

Donc j’ai voulu customiser le mien, mais là aussi, la partie documentation sur la customisation/modification de thèmes existants est un peu légère, surtout si vous avez tout oublié en CSS comme moi.

Note: La documentation peu claire, c’est quasiment le seul reproche que je fais au projet Marp, tant j’en suis content. D’ailleurs, les développeurs de Marp travaillent à refaire la doc.

Grosso modo, la partie thème est gérée dans la partie « framework Marpit » (donc la partie la plus bas niveau du projet Marp). Vous trouverez ici la partie « customisation » via CSS Theme CSS (marp.app).

Ma personnalisation à moi

Je ne vais donc pas vous cacher mes petits secrets de speaker, je me suis donc fait un thème « par défaut » que j’utilise pour toutes mes conférences en tant que speaker et mes présentations internes (quand elles n’ont pas « besoin » du thème corporate).

En tout début de chaque deck, avant la première slide et après la partie Marp pure, j’ajoute ceci :

<style>
section {
background-color: #fefefe;
color: #333;
}
img[alt~="center"] {
display: block;
margin: 0 auto;
}
blockquote {
background: #ffedcc;
border-left: 10px solid #d1bf9d;
margin: 1.5em 10px;
padding: 0.5em 10px;
}
blockquote:before{
content: unset;
}
blockquote:after{
content: unset;
}
</style>

Le premier bloc change la couleur du fond des slides.
Le second me permet d’ajouter un paramètre « center » dans les images en Markdown pour la centrer (souvent très pratique quand on fait un peu de mise en page pour faire joli).
Les derniers me permettent de customiser l’apparence des blocs de « quotes ».

Ajouter des vidéos, du JS, etc

Si vous avez tout bien lu, vous vous souvenez peut-être que j’ai dit qu’on allait ajouter une option markdown.marp.enableHtml: true dans en début de fichier.

Ça va nous permettre de rajouter des bidouilles en HTML pour étendre un peu le Markdown et réaliser les 2-3% qui ne sont pas couverts par le langage.

Je l’utilise notamment de temps en temps pour rajouter un sauf de ligne pour faciliter la lecture, mais aussi lorsque j’ai besoin d’intégrer une vidéo dans un support.

Dans ce cas-là, j’ajoute la balise HTML suivante :

<div id=video><video controls="controls" width="800" src="binaries/microsoft_dance.mp4"></video></div>

Un exemple

Je ne vais pas continuer plus longtemps la liste des features de Marp, mais si vous voulez un exemple, j’ai mis à disposition le code Markdown ma conférence « Ciel ! Mon Kubernetes mine des Bitcoins ! »

Have fun !