RoseLazuli!

Ce blog est généré avec Pandoc

Pandoc est génial. C'est un utilitaire qui permet de convertir des fichiers texte depuis à peu près n'importe quel format vers n'importe quel format.

Ce blog a eu bien des phases, souvent hors ligne ou archivé. Il est passé de PluXML à Jekyll, puis Lume. Le souci, c'est que toutes ces solutions ont un point commun : elles nécessitent toutes une dépendance. PluXML nécessite PHP, Jekyll Ruby et Lume Deno.

Alors c'est quoi le problème ?

Systématiquement, lorsque je déplace ce blog d'un serveur vers un autre, ou lorsque je l'installe localement pour écrire des articles, il y a des soucis de mise à jour des dépendances ou de l'installation des divers paquets. Certes, Docker peut simplifier énormément la chose, sauf que maintenant Docker devient une dépendance !.

Deno a la particularité de télécharger les dépendances au lancement d'une application puis de les mettre en cache. Le souci, c'est qu'il n'y a aucune gestion simple des versions des dépendances sans avoir de lockfile. Les mises à jour deviennent pénibles et difficiles à suivre.

Puis, je me suis dit : "Tout ce dont tu as besoin, c'est de convertir du markdown en HTML ? On s'en fiche un peu du reste, non ?". Alors, j'ai commencé à chercher une solution et je suis tombé sur Pandoc.

Le truc cool avec Pandoc, c'est qu'il tient dans un seul binaire !

Pandoc + BusyBox

Il ne restait plus qu'à écrire quelques scripts pour automatiser le tout. Pour générer un site statique, il faut principalement trois choses :

  1. Convertir les articles markdown en fichiers HTML
  2. Créer un index.html à partir de tous les articles générés
  3. Copier divers fichiers statiques (images, css, etc.)

Tout ça est facilement automatisable avec bash, voire même sh/ash. Ça tombe bien, j'adore Alpine Linux et ce blog est hébergé sur un Raspberry Pi 5 (tournant sur Alpine). Ce qui est aussi cool avec Alpine, c'est qu'il utilise BusyBox et BusyBox utilise ash comme shell par défaut.

./install.sh + ./build.sh

Il suffit de quelques scripts qui peuvent facilement être suivis via Git.

Un script ./install.sh qui s'occupe tout simplement de télécharger Pandoc en spécifiant la version. Le tar.gz peut être suivi dans Git comme dépendance (ou pas), il fait moins de 35 Mo ! (Bon d'accord, le binaire précompilé, lui, fait plus de 150 Mo...)

ls -lh build-tools/
total 34M
drwxr-xr-x    2 yadomi   yadomi      4.0K Feb 27 17:39 bin
-rw-r--r--    1 yadomi   yadomi     34.0M Feb 27 17:39 pandoc-3.6.3-linux-arm64.tar.gz
drwxr-xr-x    3 yadomi   yadomi      4.0K Feb 27 17:39 share
drwxr-xr-x    2 yadomi   yadomi      4.0K Mar  2 14:19 template

Ensuite, un script ./build.sh de quelques lignes s'occupe de tout le reste. Il convertit tous les fichiers .md en HTML, puis construit un index.html et un rss.xml.

Pandoc permet l'utilisation de templates, ce qui facilite l'ajout de header, footer ou même de style personnalisé. Il supporte aussi la coloration syntaxique du code sans l'ajout de dépendances additionnelles et ça, c'est vraiment chouette.

Les deux scripts sont disponibles sur ce Gist.

Ce que je trouve génial avec Pandoc, c'est sa flexibilité. Le fait de générer un blog avec Pandoc permet un contrôle total du résultat final. Ce sont vraiment juste des fichiers HTML placés au bon endroit, liés les uns aux autres avec des liens. Je crois même que ça porte un nom... le web ?

Limitations

C'est vrai, Pandoc ne fait pas tout. En réalité, Pandoc ne fait pas grand-chose dans l'optique de générer un blog, il s'occupe uniquement de la conversion markdown > HTML.

Voici une liste non exhaustive des limitations :

Cependant, tous ces problèmes semblent pouvoir être résolus sans trop de difficulté avec un peu plus de lignes dans le script ./build.sh.

Pour moi, la génération d'un site statique doit être simple, toujours en respectant le principe KISS, et cette solution me convient parfaitement actuellement.