make-pandoc/README.md

# [make-pandoc][mp]

## 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][neovim] 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][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][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][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`][mp] 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[^1] ou Mac OS.
- La commande `make`. [GNU Make][gm] 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 :

```bash
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.

```bash
cd make-pandoc
```

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

```bash
❯ 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][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][contribution].

[mp]: https://git.milhit.ch/igor/make-pandoc
[neovim]: https://git.milhit.ch/igor/neovim "Dépôt git de ma configuration"
[preview]: https://github.com/iamcco/markdown-preview.nvim "Dépôt git du plugin"
[cosma]: https://cosma.graphlab.fr/ "Site officiel du logiciel cosma"
[zotero]: https://zotero.org "Site officiel de Zotero"
[tickets]: https://git.milhit.ch/igor/make-pandoc/issues
[contribution]: https://git.milhit.ch/igor/make-pandoc/issues/4
[gm]: https://www.gnu.org/software/make/ "Site officiel"

[^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.