Utiliser `make` et `pandoc` pour représenter au format HTML une arborescence de fichiers au format markdown.

Go to file

iGor milhit 803ad9ce15 make: create a new file - Creates a templates and a notes directory. - Creates a default template used to create new files. It contains a minimal frontmatter with the creation date and an ID. - Adds the new recipe which creates a new file in the notes directory, based on the default template, replacing the creation date and ID variables with according values. - Updates the README file with the new recipe. - Improves the documentation of the code with comments. - Fixes #9. Co-Authored-by: iGor milhit <igor@milhit.ch>		2022-12-22 11:19:58 +01:00
templates	make: create a new file	2022-12-22 11:19:58 +01:00
LICENSE	Initial commit	2022-10-09 21:00:39 +02:00
Makefile	make: create a new file	2022-12-22 11:19:58 +01:00
README.md	make: create a new file	2022-12-22 11:19:58 +01:00

README.md

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

make-pandoc est en mesure :

D'afficher une aide (make ou make help).
De vérifier si les dépendances sont bien installées (make deps).
De créer un nouveau fichier dans le répertoire de notes (make new).

Pour l'instant make-pandoc ne fait pas grand chose de plus. 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
  new         Create a new file

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.

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. ↩︎

README.md Unescape Escape