281 lines
12 KiB
Markdown
281 lines
12 KiB
Markdown
---
|
||
title: Introduction à la prise de note avec markdown
|
||
author:
|
||
- Igor Milhit^[Uni CMU]
|
||
date: Printemps 2023
|
||
creation_date: 2023-04-19T11:35:14+02:00
|
||
id: 20230419113601
|
||
tags: [note, markdown]
|
||
logo:
|
||
- logo-md.svg
|
||
lang: fr
|
||
bibliography: references.bib
|
||
csl: heg-iso-690.csl
|
||
link-citations: true
|
||
toc-title: Table des matières
|
||
---
|
||
|
||
## Objectifs
|
||
|
||
- Quel intérêt ? Pourquoi se mettre à rédiger avec markdown ?
|
||
- Comment : aperçu de la syntaxe de base.
|
||
- Qu'attendre d'un éditeur de texte (pour rédiger avec markdown) ?
|
||
- Bref aperçu des possibilités avancées :
|
||
- Ensemble de notes.
|
||
- Conversion.
|
||
|
||
:::{#licence}
|
||
 \
|
||
[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
|
||
|
||
## Pourquoi ? [^0] {#1st-section}
|
||
|
||
Le plus important pour *ses* propres habitudes de travail 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 la syntaxe markdown, mais aucune méthode ou
|
||
outil n'est *la* solution miracle pertinente dans *tous* les contextes.
|
||
|
||
L'information numérique est utile si elle est **structurée**. Un fichier PDF
|
||
bien conçu donne accès dans la barre latérale à la table des matières pour
|
||
faciliter la navigation. Cette structure s'obtient, par exemple, avec l'usage
|
||
cohérent des styles et des niveaux de titre dans un traitement de texte. La
|
||
syntaxe markdown est une autre méthode, surprenante au début, mais qui s'avère
|
||
particulièrement efficace.[^1]
|
||
|
||
Markdown est une syntaxe qui permet, **simplement 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 et
|
||
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][hd], [HackMD][hm], etc.).
|
||
|
||
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 lus 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 ou complexes, petits comme une fiche de
|
||
notes ou volumineux comme une thèse.
|
||
- De regrouper un ensemble de notes dans un « bloc note » numérique et de
|
||
naviguer rapidement dans cet ensemble, de rechercher de l'information
|
||
facilement.
|
||
- 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ême fichiers le document dans plusieurs
|
||
formats pour une diffusion sur le web, la lecture dans un PDF ou un ePub.
|
||
|
||
Enfin, il y a deux arguments de *geek* :
|
||
|
||
- Les fichiers textuels sont particulièrement adaptés pour en suivre
|
||
l'historique des modification (*versioning*), par exemple avec le logiciel
|
||
[Git][git].
|
||
- Jouer avec markdown et les conversions dans de multiples format est vraiment
|
||
amusant, bien que parfois source de complications inutiles. 😅
|
||
|
||
[text]: https://www.arthurperret.fr/cours/format-texte.html
|
||
[hd]: https://hedgedoc.org/
|
||
[hm]: https://hackmd.io/
|
||
[git]: https://fr.wikipedia.org/wiki/Git "Article Wikipedia en français"
|
||
|
||
## Comment ?
|
||
|
||
La syntaxe markdown est très souvent expliqué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 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
|
||
qui explique 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 {#ed}
|
||
|
||
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 sour la forme d'un *rendu* HTML.
|
||
- La possibilité de naviguer dans une arborescence de fichiers.
|
||
- 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
|
||
assez 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][gw]
|
||
|
||
**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][zettlr]
|
||
|
||
**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][hm] ou le logiciel
|
||
[HedgeDoc][hd] qui permet non seulement d'éditer des fichiers mardkown avec une
|
||
prévisualisation, mais également de le faire à plusieurs, de disposer d'un
|
||
suivi des modfications et de commenter.
|
||
|
||
![Interface de l'éditeur HackMD][interface-hd]
|
||
|
||
[interface-hd]: ../static/hackmd.png
|
||
[zettlr]: ../static/zettlr.png
|
||
[gw]: ../static/ghostwriter.png
|
||
|
||
### É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*, en général utilisés
|
||
par des développeurs pour écrire du code informatique. Normalement, 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][vscode]
|
||
|
||
[vscode]: ../static/vscode.png
|
||
|
||
## 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*. 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`][lienEntreFichiers]
|
||
|
||
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][rechCode]
|
||
|
||
### 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.
|
||
|
||
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]
|
||
|
||
[lienEntreFichiers]: ../static/lien-entre-fichiers.png
|
||
[rechCode]: ../static/recherche-vscode.png
|
||
|
||
## Bibliographie
|
||
|
||
[^0]: Cette section repose beaucoup sur la page [Format texte][text]
|
||
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>.
|