From b95a5a819c21516d0ff618cc20bc36890b8fc7cc Mon Sep 17 00:00:00 2001 From: iGor milhit Date: Mon, 31 Oct 2022 12:37:08 +0100 Subject: [PATCH] documentation: write the first version of REAME - Writes the first version of the README.md file, which tries to describe and explain the project. - Closes #3. Co-Authored-by: iGor milhit --- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 89dd862..28f9b37 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,51 @@ -# make-pandoc +# [make-pandoc][mp] -Utiliser `make` et `pandoc` pour représenter au format HTML une arborescence de fichiers au format markdown. \ No newline at end of file +## 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 + +Pour l'instant [`make-pandoc`][mp] 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. + +## 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