make-pandoc

Pourquoi ?

Depuis 2016, dans mes différents contextes professionnels, j'ai pris l'habitude de prendre mes notes au format Markdown. La configuration de mon éditeur a constamment évolué depuis, ainsi que mes habitudes : tentative d'harmoniser la syntaxe, usage d'un en-tête avec des métadonnées au format YAML, liens internes, etc.

Comme j'utilise git pour document l'historique des modifications et pouvoir travailler sur ces notes sur différents postes, j'ai également un rendu HTML lorsqu'il est proposé par les forges git les plus utilisées, comme GitHub, les différentes instances Gitlab ou Gitea. Sur le moment, je peux également afficher une visualisation dynamique HTML grâce à l'extension markdown-preview.

Mais depuis quelques temps, j'éprouve le besoin d'avoir une version HTML complète de l'ensemble des notes, pas forcément de manière publique, qui donnerait également accès aux fichiers annexes et qui permette de naviguer que ce soit par la logique de l'arborescence, celle des liens internes ou encore des métadonnées (id et tags).

Après avoir exploré un peu les différentes possibilités (générateurs de sites statiques, cosma), j'en suis arrivé à la conclusion que je voulais arriver à mes fins en utilisant principalement les outils pandoc et make, notamment pour pouvoir gérer les citations et les références avec Zotero.

Fonctionnalités

Pour l'instant make-pandoc ne fait strictement rien. Mais dans un avenir incertain il devrait être en mesure de générer une version HTML d'une arborescence de fichiers Markdown, en offrant une navigation, la mise en forme des citations et des références, des notes.

Requis

• Un système *nix-like, comme une distribution Linux¹ ou Mac OS.
• La commande make. GNU Make est en général disponible dans les dépôts des distribution Linux ainsi que pour Mac OS.
• L'utilitaire awk, lui aussi facilement disponible sur Linux ou Mac OS.

Usage

Il faut d'abord cloner le projet, par exemple avec la commande suivante :

git clone https://git.milhit.ch/igor/make-pandoc.git

Cette commande va créer un dossier nommé make-pandoc à l'endroit où elle a été lancée. Une fois le projet cloné, naviguer dans ce dossier.

cd make-pandoc

Une fois dans le bon dossier, lancer la commande make ou make help. Elle devrait afficher l'aide.

❯ make help

Usage:
  make <target>

Targets:
  help        Display this help
  deps        Check dependencies

Feuille de route

La liste des tickets permet de se faire une idée. C'est peu ambitieux, l'idée étant d'avancer pas à pas, au rythme d'un escargot agile. 😀

Tu noteras peut-être qu'il y a un ticket au sujet de la contribution.

---

1. J'imagine que c'est valable également pour l'univers BSD, mais je ne le sais pas. Si tu connais BSD, tu devrais le savoir mieux que moi je pense. ↩︎