rdv-info-markdown/intro/intro.md

---
title: Introduction à la prise de note avec markdown
author: 
- Igor Milhit^[Uni CMU]
date: Printemps 2024
creation_date: 2023-04-19T11:35:14+02:00
id: 20230419113601
tags: [note, markdown]
logo: 
- ../static/logo-md.svg
lang: fr
bibliography: ../static/references.bib
citation-style: ../static/heg-iso-690.csl 
link-citations: true
toc-title: Table des matières
---

## Objectifs

- Avantages et inconvénients.
- Aperçu de la syntaxe de base.
- Les fonctionnalités minimales d’un éditeur.
- Bref aperçu des possibilités avancées :
  - Ensemble de notes.
  - Conversion dans d’autres formats.
  - Insertion de références bibliographiques.

:::{#licence}
![Logo de la licence CC BY-SA 4.0](../static/by-sa.svg) \
[CC BY-SA 4.0][cc-by-sa] --- [Sources][sources]
:::

[cc-by-sa]: https://creativecommons.org/licenses/by-sa/4.0/deed.fr "Texte de la licence en français"
[sources]: https://git.milhit.ch/igor/rdv-info-markdown

## Définition, avantages et inconvénients[^0]  {#first-section}

Le plus important est de trouver des méthodes et des outils adaptés à *ses
besoins*. Ci-dessous sont listés quelques arguments en faveur de l'usage de
fichiers au format texte et  de la syntaxe markdown, mais aucune méthode ou
outil n'est *la* solution miracle pertinente dans *tous* les contextes.

### Définition

L'information numérique est utile si elle est **structurée**. La table des
matières d'un document numérique devrait être constituée de liens vers les
sections. Cette structure peut s'obtenir par l'usage des styles et des niveaux
de titre dans un traitement de texte (Microsoft Word, Libreoffice Writer,
etc.). La syntaxe markdown est une autre méthode, très efficace.[^1]

Markdown est *un langage de balisage léger*. Concrètement, il s'agit d'une
syntaxe qui permet, **uniquement avec des éléments textuels**, de structurer
(niveau de titres) et de mettre en forme du texte. Cette structure et cette
mise en forme sont compréhensibles par des êtres humains ou par des programmes
informatiques. Aussi, les documents rédigés à l'aide de markdown peuvent soit
être lus tels quels, soit être traités par un programme pour afficher un
« rendu » sous forme de page web, de document PDF ou DOCX.

La syntaxe markdown est relativement simple à apprendre et mémoriser. Aussi, la
rédaction au format markdown repose sur très peu de fonctionnalités du
logiciel. Le bloc note suffit, même si un peu plus de confort est souhaitable.

Cette syntaxe est utilisée par de nombreux logiciels ou services en lignes pour
la rédaction. C'est le cas des notes dans Zotero ou d'éditeurs en ligne adaptés
au travail collaboratif ([HedgeDoc][1], [HackMD][2], etc.).

### Avantages

Les fichiers utilisés ne sont composés que de caractères textuels. Aussi, ils
sont :

- Simples et légers :
  - Ne dépendent pas d'un logiciel spécifique, ni d'un système d'exploitation.
  - Pourront être ouverts et édités dans n'importe quel contexte, et
    probablement dans un avenir éloigné (pérennité).
  - Rapides à ouvrir. Avec n'importe quel éditeur de texte (bloc note Windows,
    Notepad++, TextEdit, Gedit, VIM, EMACS, etc.)
  - Faciles à sauvegarder, copier, synchroniser, partager.

Toujours grâce à leur nature textuelle, il est facile d'avoir des outils pour
rechercher (et remplacer) rapidement du texte au sein non seulement du fichier
ouvert, mais d'un ensemble de fichier dans un répertoire. \
Il est même possible d'écrire des programmes pour modifier ou utiliser
automatiquement ces fichiers. Et il en existe justement beaucoup !

Grâce à ces propriétés, il est possible :

- De prendre des notes au clavier rapidement, de manière structurée, et avec
  une recherche interne efficace.
- De rédiger des documents simples (une note) ou complexes (une thèse).
- De regrouper un ensemble de notes dans un « bloc note » numérique et de
  naviguer dans cet ensemble, de rechercher de l'information .
- De manière similaire, de regrouper un ensemble de fichiers pour constituer un
  document complexe, comme un livre ou un article scientifique.
- Enfin de convertir à partir des mêmes fichiers le document dans plusieurs
  formats pour une diffusion sur le web, la lecture dans un PDF ou un ePub
  (compatible avec une liseuse électronique).

Enfin, les fichiers textuels sont particulièrement adaptés au suivi de
l'historique des modification (*versioning*), par exemple avec le logiciel
[Git][3].

### Inconvénients

Pour un usage simple, l'apprentissage n'est pas très difficile. La syntaxe de
base s'acquiert rapidement. Pour parvenir à rédiger des documents relativement
complexes (notes, citations et bibliographies, etc.), cet apprentissage est un
peu plus long. Afin de maîtriser la conversion dans différents formats, tout en
personnalisant la mise en forme des documents obtenus, il devient vite
nécessaire d'apprendre à utiliser d'autres outils, à modifier des modèles dans
les formats désirés (HTML, DOCX, peut-être LaTeX, etc.).

Certains éditeurs intègrent la fonction de conversion, mais elle repose sur
l'installation de logiciels annexes, principalement `pandoc`, mais aussi une
distribution LaTeX pour obtenir une conversion en PDF. Ces outils ne sont pas
si difficiles à installer. Surtout, ils sont libres, gratuits et disponibles
pour Windows, Mac OS ou Linux.

Pour utiliser `pandoc`, qui est l'outil de conversion le plus complet, il est
nécessaire de le faire « en ligne de commande » plutôt que dans une interface
graphique, avec la souris. C'est un élément en plus à apprendre, mais qui ouvre
beaucoup de possibilités.

Le travail collaboratif à plusieurs est toujours possible, mais selon les cas
avec une certaine friction. La situation la plus simple est d'utiliser un
éditeur en ligne qui offre des fonctionnalités d'édition à plusieurs. Souvent
cela est au prix de ne pouvoir disposer de toute la puissance de `pandoc`, du
moins directement.

Toujours dans le cas où toutes les personnes qui collaborent sont capables de
travailler avec les mêmes outils, elles peuvent toujours travailler ensemble en
se mettant d'accord sur un « workflow », par exemple grâce à `git` mentionné
plus haut. Mais c'est un outil de plus à apprendre. Et de nouvelles
possibilités à découvrir.

Enfin, si les personnes avec qui on collabore ne veulent ou ne peuvent pas
utiliser les mêmes méthodes, alors il faudra mettre en place un processus
d'export et d'import un peu complexe, mais en partie automatisable
[@perretMarkdownTraitementTexte2022]. 

## La syntaxe markdown 

La syntaxe markdown est très bien documentée sur le web :

- La documentation « officielle » est disponible sur le site personnel d'un des
  concepteurs de la syntaxe : <https://daringfireball.net/projects/markdown/>
  [@gruberMarkdown2004].
- Le site *flus* propose Une documentation en français et très claire :
  <https://flus.fr/carnet/markdown.html> [@fressinaudGuideMarkdown2022].
- Il y a plusieurs variantes (ou extensions) de la syntaxe et un site essaie de
  proposer un standard. Il met à disposition un tutoriel interactif :
  <https://commonmark.org/help/> [@commonmarkCommonMark].
- Arthur Perret a traduit en français ce même tutoriel, disponible sur sa page
  expliquant ce qu'est markdown :
  <https://www.arthurperret.fr/cours/markdown.html> [@perretMarkdown2022].

Pour les tableaux, il est fortement conseillé :

- D'utiliser un générateur, par exemple
  <https://www.tablesgenerator.com/markdown_tables>.
- Ou de disposer dans son éditeur d'un générateur de tableaux.

Le plus souvent les fichiers contenant du markdown ont pour extension `.md`,
mais c'est une convention. Rien n'interdit d'utiliser d'autres extensions comme
`.mkdn` ou `.markdown`, pour autant que l'éditeur que vous utilisez les
reconnaissent comme du markdown.

## Éditeurs

Il existe beaucoup d'éditeurs pour rédiger en markdown. On peut les regrouper
en deux grandes catégories :

1. Les éditeurs dédiés.
1. Les éditeurs généralistes.

Dans les deux cas, des fonctionnalités de base qui sont presque
incontournables :

- Une prévisualisation, le plus souvent sous la forme d'un *rendu* HTML. Cette
  fonctionnalité a l'avantage de permettre de se faire une idée du résultat
  sans devoir générer le fichier final.
- La possibilité de naviguer dans une arborescence de fichiers, en général dans
  une barre sur le côté de l'interface.
- Une autocomplétion, pour faciliter l'entrée de syntaxe avec des `[]` ou des
  `()`.

D'autres fonctionnalités ne sont pas indispensables, mais deviennent rapidement
utiles :

- La correction orthographique pour les langues dans lesquelles vous rédigez.
- Un formatage automatique des tableaux.
- La possibilité de suivre les liens internes, au sein du même fichier ou entre
  les fichiers d'un même répertoire.

### Éditeurs dédiés

Ce sont des logiciels conçu spécifiquement pour éditer des fichiers avec la
syntaxe markdown. Ils peuvent être sous la forme d'un logiciel à installer sur
votre appareil (ordinateur, tablette, téléphone) ou d'un service web.

**Typora** est éditeur qui met l'accent sur son interface épurée. Il est disponible
pour tous les systèmes d'exploitation, payant. <https://typora.io/>

![Interface de GhostWriter][6]

**GhostWriter** est libre et gratuit, pour Windows et Linux
principalement.[^2] <https://ghostwriter.kde.org/fr/>

**Abricotine** est libre et gratuit, pour toutes les plateformes.
<http://abricotine.brrd.fr/>

**iA Writer** est payant, pour MacOS et Windows, mais est très apprécié pour la
rédaction. Il permet de lier des notes entre elles et offre ainsi une
navigation dans un ensemble de fichiers. <https://ia.net/writer>

**Obsidian** est un logiciel propriétaire, pour toutes les plateformes. Il ne
se limite pas à l'édition de fichiers markdown, mais permet de constituer une
base de connaissance basée sur des notes, et cela de manière très complète.
<https://obsidian.md/>

![Interface de Zettlr][5]

**Zettlr** est libre et disponible pour tous les systèmes d'exploitation. Il
est destiné à un usage académique, que ce soit pour construire une base de
connaissance à partir de notes ou pour rédiger un travail de mémoire ou un
article scientifique. Il intègre Zotero pour la gestion des références.

En ligne, on peut mentionner à nouveau le service [HackMD][2] ou le logiciel
[HedgeDoc][1] qui permet non seulement d'éditer des fichiers markdown avec une
prévisualisation, mais également de le faire à plusieurs, de disposer d'un
suivi des modifications et de commenter.

![Interface de l'éditeur HackMD][4]


### Éditeurs généralistes

*Généralistes* car ces éditeurs ne sont pas limités à l'édition de fichier
markdown. Le plus souvent, ce sont des *éditeurs de texte* utilisés
par des développeurs pour écrire du code informatique. Le plus souvent, ils
disposent d'un écosystème d'extensions afin de s'adapter à des besoins
spécifiques. De ce fait, ils sont très puissants.

Ainsi, il est possible d'adapter à l'édition du markdown les éditeurs de texte
suivant, notamment :

- Notepad++, libre et gratuit, pour Windows.
- Visual Studio Code, gratuit, pour Windows, MacOS, Linux. Un des logiciels les
  plus utilisés actuellement.
- VIM ou neovim, libre et gratuit, pour tous les systèmes d'exploitation.
- EMACS, libre et gratuit.

![Interface de Visual Studio Code][7]

## Aperçu des possibilités avancées

### Ensemble de notes

Afin d'organiser ses notes, il est possible de réunir un ensemble de fichiers
dans le même répertoires (y compris avec des sous répertoires) et de faire des
liens entre les fichiers (et même au sein d'un seul fichier).

Certains éditeurs, ou certaines extensions d'éditeurs, proposent des facilités
pour générer ces liens, au prix d'une syntaxe *ad hoc* (« wiki links »). Mais
il est parfaitement possible de le faire avec la syntaxe « normale » du lien.

![Lien depuis le fichier `README.md` vers le fichier `points-a-ameliorer.md`][8]

La figure 5 montre sur la gauche une arborescence de fichiers, avec
des sous-répertoires, et dans le fichier affiché (`README.md`), un lien vers le
fichier `points-a-ameliorer.md`. Dans cet éditeur, en plaçant le curseur sur le
lien et en tapant la touche « entrée », on ouvre le fichier cible.

La figure 6 montre la recherche du terme `rdv-info` lancée sur la même
arborescence de fichiers que la figure 5, au moyen du logiciel Visual Studio
Code. Il y a 13 occurrences du terme dans 7 fichiers. Ce type de recherche est
facilité par le fait que ce sont des fichiers au format texte et se retrouve
dans la plupart des éditeurs généralistes de qualité.

![Recherche dans Visual Studio Code][9]

### Export vers d'autres formats

La conversion d'un document markdown en un autre format, plus simple à partager
devient assez vite utile. Pour les conversions, `pandoc` est l'outil le plus
souvent utilisé. Il est soit utilisé par votre éditeur pour faire les exports
(par exemple avec Zettlr), soit par vous même en ligne de commande. C'est un
logiciel libre et gratuit, développé très activement.

Il est capable de lire et d'écrire dans un grand nombre de formats différents,
parfois à l'aide de logiciels spécifiques. Par exemple, pour produire un
fichier PDF, il peut utiliser plusieurs méthodes, dont LaTeX, ce qui suppose
d'en avoir une version installée.

La commande pour une conversion simple est de la forme suivante :

```bash
pandoc --output fichier.docx fichier.md
```

Le format obtenu correspond à celui qui est indiqué en extension du nom de
fichier de sortie `--output`, ici du DOCX. Mais il est possible de
l'expliciter :

```bash
pandoc --to docx --output fichier.docx fichier.md
```

Le support de cours de cette introduction à markdown a été rédigée en markdown
et est exportée en PDF grâce à `pandoc` et à *Paged.js*.[^3]

### Citations et Bibliographie

Pour insérer des citations et générer une bibliographie, il est nécessaire
d'avoir au moins une collection de références bibliographiques, par exemple
sous la forme d'un fichier `.bib`. Pour obtenir ce fichier, il est possible de
passer par Zotero et d'exporter une collection dans le format BibTex (ou Better
BibTex avec l'extension Zotero du même nom.)

Dans ce fichier (et dans Zotero), on trouve pour chaque référence une « clé de
citation » qui permet de l'identifier de manière unique. C'est cette clé que
l'on va insérer dans notre fichier markdown pour indiquer une citation. Elle
est insérée avec la syntaxe suivante : `[@clé-de-citation]`.

On peut encore ajouter à la fin de notre fichier un titre de deuxième niveau
avec le texte bibliographie, pour que `pandoc` puisse y insérer la
bibliographie.

Pour être en mesure de traiter ces informations, il faut utiliser l'option de
`--citeproc` intégrée dans `pandoc` :

```bash
pandoc --citeproc \
       --to=pdf --pdf-engine=xelatex \
       --bibliography=references.bib \
       --output fichier.pdf fichier.md
```

Dans l'exemple ci-dessus, nous voyons l'option `--citeproc` et l'option
`--bibliography=` qui indique où se trouve le fichier des références
bibliographiques. Par défaut le style est Chicago, de type auteur-date.

Pour aller plus loin, le mieux est de consulter la [documentation
officielle][10] de `pandoc.`

## Bibliographie {#bibliography}

<!-- liens -->

[0]: https://www.arthurperret.fr/cours/format-texte.html
[1]: https://hedgedoc.org/
[2]: https://hackmd.io/
[3]: https://fr.wikipedia.org/wiki/Git "Article Wikipedia en français"
[4]: ../static/hackmd.png
[5]: ../static/zettlr.png
[6]: ../static/ghostwriter.png
[7]: ../static/vscode.png
[8]: ../static/lien-entre-fichiers.png
[9]: ../static/recherche-vscode.png
[10]: https://pandoc.org/MANUAL.html#citations 

<!-- notes -->

[^0]: Cette section repose beaucoup sur la page [Format texte][0] d'Arthur
Perret [@perretFormatTexte2022].
[^1]: Markdown n'est pas le seul langage de balisage léger existant, bien que
ce soit le plus répandu. D'autres sont encore plus robustes ou puissants, comme
*RestructuredText* ou *AsciiDoc*.
[^2]: Il semble possible de l'installer sur MacOS, mais n'est pas recommandé.
[^3]: Les sources et la méthode de conversion est disponible sur
<https://git.milhit.ch/igor/rdv-info-markdown>.