--- 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} ![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 ## 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 : [@gruberMarkdown2004]. - Le site *flus* propose Une documentation en français et très claire : [@fressinaudGuideMarkdown2022]. - Il y a plusieurs variantes de la syntaxe et un site essaie de proposer un standard. Il met à disposition un tutoriel interactif : [@commonmarkCommonMark]. - Arthur Perret a traduit en français ce même tutoriel, disponible sur sa page qui explique ce qu'est markdown : [@perretMarkdown2022]. Pour les tableaux, il est fortement conseillé : - D'utiliser un générateur, par exemple . - 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. ![Interface de GhostWriter][gw] **GhostWriter** est libre et gratuit, pour Windows et Linux principalement.[^2] Il est très complet et supporte les principales déclinaisons de markdown. **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. ![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 accumuler des notes sur un sujet ou rédiger une 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 .