3 Markdown

Historique

Markdown est donc un langage de balisage léger. Il été co-créé par Aaron Swartz et John Gruber en 2004[1] afin de générer facilement du code HTML pour le web. Markdown est prévu pour être facile à lire et facile à écrire (Mpondo-Dicka, 2020). Comme les commandes Markdown sont assez simples, on peut les maîtriser en dix minutes (Ball, 2018).

Depuis sa création, il a été étendu pour être utilisé pour produire d’autres types de documents dont le pdf qui n’est pas vraiment un format ouvert mais qui est le plus utilisé actuellement. L’utilisation de Pandoc[2] qui fait appel à LaTeX[3] permet maintenant de produire des documents avec une qualité identique à celle des documents produits directement avec LaTeX (Pierre, 2017).

Utiliser Markdown ne doit pas être considéré comme une complication supplémentaire mais fait au contraire partie d’un mouvement Low-Tech. Ce manuel (sous la forme d’un site Web mais également exporté au format pdf et epub) a été rédigé avec un simple éditeur de texte (Gedit[4]). Il permet de se concentrer sur la rédaction du texte sans se préoccuper de sa forme finale (Dehut, 2018). Il rassemble les fonctions de base présentes dans tous les bons manuels (Mailund, 2019) ou des fonctions plus “pratiques” glanées au fil de lectures.

Markdown fait partie de ces solutions Single Source publishing évoquées en introduction, c’est à dire qu’avec un (ou plusieurs) même(s) fichier(s) source(s) ont peut produire des documents dans différents formats (essentiellement HTML, ePub et pdf).

Toutes les fonctions présentées dans ce chapitre illustrent l’utilisation de la variante “Pandoc” de Markdown (il existe d’autres déclinaisons de Markdown[5] comme MultiMarkdown et GitHub Flavored Markdown qui ne sont pas décrites ici) pour la création de documents pdf.

Principe

Avec Markdown, il y a de nombreuses fonctions proposées par les traitements de texte impossibles à reproduire. Le fait qu’elles existent n’en fait d’ailleurs pas des fonctions indispensables. L’objectif est bien de proposer une méthode simple, ouverte et durable pour rédiger et produire de beaux documents numériques (Audet et al., 2018).

Le principe de base est de séparer le fond de la forme. Le fond, c’est le texte, une suite de caractères, qui se lit en dehors de toute mise en forme. La forme, c’est la traduction graphique, enrichie, du texte. Elle peut être différente d’un support à l’autre.

Pratiquement, il faut créer un fichier texte avec n’importe quel éditeur (voir les outils) et l’enregistrer avec l’extension “.md”. Vous trouverez le lien pour télécharger un modèle de document dans le chapitre “Télécharger”.

Autour du fond et du texte, nous avons cinq éléments à prendre en compte :

  1. la structure du document (parties, chapitres, titres et paragraphes) ;
  2. la mise en forme du texte ;
  3. les compléments du texte (notes, liens, figures, tableaux et citations) ;
  4. les éléments de mise en forme du document ;
  5. la description du document (les métadonnées).

Les éléments de mise en forme du document (langue du document, taille du papier, taille des caractères, présence ou non d’une table des matières…) et la description du document, ses métadonnées, sont intégrées dans l’entête du document dans une partie appelée YAML.

La structure du document

Les titres

Pour être correctement structuré, un texte doit être divisé en parties, chapitres, sous-chapitres, etc. Le niveau des titres va déterminer cette structure. Avec Mardown, ces niveaux sont simplement indiqués avec les balises “#” dont le nombre détermine la profondeur du titre :

# Titre de niveau 1
## Titre de niveau 2
### Titre de niveau 3
#### Titre de niveau 4
##### Titre de niveau 5
###### Titre de niveau 6

Pour un document de type article, le niveau 1 représente les chapitres. Pour un document de type book ou reports, le niveau 1 représente les parties et chaque titre de partie est précédé par un saut de page.

Les titres peuvent être numérotés automatiquement via une instruction présente dans l’entête YAML : numbersections: true. Pour empêcher la numérotation d’un titre en particulier, il faut ajouter “{-}” à la suite du titre, sur la même ligne.

Les paragraphes

Dans le texte, la séparation en paragraphes est réalisée par un double saut de ligne.

Il est cependant possible, en ajoutant “\” à la fin de la ligne, de provoquer un saut de ligne sans créer un nouveau paragraphe.

Les listes

Markdown permet de créer des listes simples et des listes numérotées.

Pour les listes simples, il faut utiliser le tiret (ou le +) suivi d’une espace.

Ceci :

– item 1
– item 2
+ item 3

 

Donnera :

— item 1
— item 2
— item 2

Notez au passage que les bullets sont ici remplacés par des tirets longs (quadratins)[6].

Pour les listes numérotées, il faut mettre un chiffre (peu importe le chiffre mais le premier indique le début de la numérotation), suivi d’un point et d’une espace.

Ceci :

1. item 1
1. item 2
1. item 3

Donnera :

  1. item 1
  2. item 2
  3. item 3

Les listes doivent être précédées d’un saut de ligne. Il est possible de combiner les deux types de listes.

Peut-être moins utile, il est aussi possible de créer des cases à cocher.

Ceci :

– [x] item 1, coché
– [ ] item 2, non-coché
– [x] item 2.1, coché
– [ ] item 2.2, non-coché
– [ ] item 3, non-coché
– [X] item 4, coché

Donnera :

image

La mise en forme du texte

Les styles

Les fonctions de base sont l’italique et le gras. Il est aussi possible de barrer un texte.

Ce passage :

*Ceci est un texte italique*, **Ceci est un texte gras** et ~~Ceci est un texte barré~~

Donnera :

Ceci est un texte italique, Ceci est un texte gras et Ceci est un texte barré

(il est possible de les combiner).

Les indices et les exposants sont réalisés avec ~ et ^ donc : H~2O et X^2 pour : H2O et X2

Les tirets longs (cadratin) et demi-longs (demi-cadratin) sont créés avec trois et deux tirets (le signe moins) : — et –

Les mises en évidence

Pour citer et mettre en évidence un passage de texte, il faut utiliser le caractère “>” en début de paragraphe.

 

Ce passage :

> « But here’s the most important bit, saved for last: none of this matters if you want to write a book. Quite a few people have told me that they want to write a book, but they’re not sure about which tools to use. My advice: all you need to write a book is a program that allows you to write text into a file [@ball2018]. »

Donnera :

“But here’s the most important bit, saved for last: none of this matters if you want to write a book. Quite a few people have told me that they want to write a book, but they’re not sure about which tools to use. My advice: all you need to write a book is a program that allows you to write text into a file (Ball, 2018).”

Le texte est centré dans la page avec une justification gauche et droite (comme le reste du texte).

Notez au passage l’ajout de la citation à l’auteur du texte qui va reproduire le renvoi à la bibliographie suivant la norme sélectionnée dans l’entête YAML et ajouter la référence dans la bibliographie en fin de document (voir plus loin pour plus d’explications à propos des possibilités en matière de bibliographie).

Les codes et textes non formatés

Pour afficher du code sans formatage (comme fait à plusieurs reprises plus haut), il faut :

  • soit encadrer le texte (ligne précédente et ligne suivante) avec trois accents graves consécutifs ;
  • soit, pour une seule ligne par exemple, faire précéder le texte par une tabulation ou au moins trois espaces.

Autres codes utiles pour la mise en forme

Quelques petites commandes peuvent encore se révéler utiles :

  • utilisation de commandes LaTeX pour :
    • insérer un saut de page : \newpage
    • cadre de texte : {texte texte texte}[7]
    • texte en couleur : \textcolor{red}{texte en rouge}
    • réduire la taille des caractères : \small (\normalsize pour revenir à la taille normale)
    • augmenter la taille des caractères : \large (\normalsize pour revenir à la taille normale)[8]
    • texte en petites capitales : [Texte texte texte]{.smallcaps}
  • insérer une ligne horizontale : *** ou —
  • insérer la date du jour (dans un titre ou dans le texte) avec la variable \today
  • insérer des espaces insécables (pour insérer une ligne vide ou empêcher le positionnement en début de ligne de “?”, “:” ou “;”) :  
  • échappement avec \ pour afficher des caractères (comme [ ou #) qui sont interprétés par Pandoc comme des commandes

Les compléments du texte

Les notes de bas de page

Les notes sont créées avec l’ajout d’un “^” et le texte de la note est encadré de “[” et “]” :

ceci est le texte^[Et ceci est la note.].

Les notes de bas de page sont numérotées automatiquement. Cette méthode est spécifique à la création de documents pdf. On peut aussi utiliser cette méthode pour ajouter une note dans les éléments de l’entête (pour le titre, le résumé ou un auteur).

Il y a une méthode un peu plus complexe (et compatible ePub et HTML) qui se fait en deux temps, avec l’appel de note :

ceci est le texte[^numéro de la note].

et avec toutes les notes regroupées à la fin du document .md :

[^numéro de la note]: Et ceci est la note.

Les liens

Pour créer un lien vers une page Web, il faut utiliser la séquence [ ](). Entre les crochets, on va placer le texte à afficher et, entre les parenthèses, l’URL cible :

[texte à afficher](https://url_cible.org)

Il est aussi possible de créer des liens à l’intérieur d’un document. Pour cela :

  • il faut ajouter une ancre (ici, après un titre) : # chapitre 10 {#chap10}
  • créer le lien avec la même séquence : texte texte texte, voir [chapitre 10](#chap10)

À noter que cela ne fonctionne pas si les liens sont transformés en notes en bas de page avec l’instruction links-as-notes: true dans l’entête YAML.

Les figures

La syntaxe pour insérer une figure est comparable à celle de la création d’un lien. Il faut seulement faire précéder l’instruction d’un “!”. L’image “appelée” peut être un fichier présent sur l’ordinateur (attention à appeler le fichier au bon endroit sur le disque dur) ou une image quelque part sur Internet (il faut alors entrer une URL correcte).

S’il y a une légende (texte entre le [ et ]), les images sont centrées et automatiquement numérotées avec “Figure x :” + la légende. Pandoc va éventuellement déplacer le texte avant et après les figures pour optimiser le remplissage des pages.

Ceci :

![Le logo de *Markdown*](markdown-large.png)

Donnera :

image

S’il n’y a pas de légende (texte entre le [ et ]), la figure sera alignée à gauche et la mise en forme ne sera peut-être pas optimale.

Il est possible de modifier la taille de l’image en ajoutant { width=50% } derrière l’appel d’image (ici, réduction de la taille de 50%).

Les tableaux

Markdown gère plutôt bien les tableaux. Il faut utiliser le “|” pour séparer les colonnes et le saut de ligne pour séparer les lignes.

Pour aligner à gauche (les colonnes sont alignées à gauche par défaut), centrer ou aligner à droite le contenu d’une colonne, il faut le déclarer dans la deuxième ligne en ajoutant “:” à gauche, “:” des deux côtés ou “:” à droite des trois “-”. Le nombre de tirets (“-”) va déterminer la largeur de la colonne.

 

La séquence suivante :

| **gauche** | **centre** | **droite** |
|:—|:—:|—:|
| cellule 1.1 | cellule 2.1 | cellule 3.1 |
| cellule 1.2 | cellule 2.2 | cellule 3.2 |
| cellule 1.3 | cellule 2.3 | cellule 3.3 |
: Titre du tableau

Donnera :

image

Les enrichissements (gras, italique…) sont autorisés pour toutes les cellules du tableau. Le titre du tableau apparaît au-dessus, numéroté, comme pour les figures. Il n’est pas possible avec Markdown de fusionner des cellules.

Il existe sur le Web un générateur de tables[9] Markdown qui facilite leur création (y compris la transformation de fichiers .csv).

Les équations mathématiques

Il est aussi possible d’intégrer des équations mathématiques avec la syntaxe TeX Math de LaTeX. Elles seront correctement reproduites dans le fichier pdf exporté. Ces équations sont encadrées par “$$”.

La séquence suivante :

$$x = \frac {-b \pm \sqrt{b^2 – 4ac}}{2a}$$

donnera :

image

Encore une fois, l’objectif reste juste de montrer ce qui est possible et non de détailler cette syntaxe. Il y a un tutoriel très complet sur WikiBooks[10]. Vous pouvez aussi utiliser un éditeur en ligne[11] pour écrire vos équations.

Les citations et la bibliographie

Un élément puissant de l’utilisation de Markdown et Pandoc est la facilité d’insertion de citations dans le texte et de génération d’une bibliographie à la fin du document (pdf mais aussi html, epub, odt, docx…).

Pour que cela fonctionne :

    1. il faut que deux fichiers soient présents dans le même répertoire que le document .md :
      • un fichier BibTex créé avec un gestionnaire bibliographique. Avec Zotero, il faut utiliser la fonction “exporter les documents” et choisir le format BibTex pour créer un fichier .bib ;
      • copier le fichier .csl (Citation Stype Langugage) correspondant au style bibliographique que vous souhaitez utiliser ;
    2. que ces deux fichiers soient renseignés dans l’entête YAML (voir ci-dessous) ;
    3. insérer les citations :
      • soit avec l’appel [@auteur0000] pour une citation avec des parenthèses : “texte texte texte (Auteur, 0000)”. @auteur0000 est la clé de citation enregistrée dans le gestionnaire bibliographique ;
      • soit avec l’appel @auteur0000 pour une citation directe : “texte texte texte Auteur (0000)” ;
    4. ajouter le titre “Bibliographie” en fin de document ;
    5. ajouter “–citeproc” dans la commande pandoc : pandoc –citeproc source.md -o destination.pdf

    Vous trouverez une explication plus complète sur le blog Zotero francophone[12].

L’en-tête YAML

Pandoc prend en charge les en-têtes YAML pour les fichiers Markdown.

L’en-tête YAML se situe au début du fichier (elle peut également se trouver dans un fichier à part) et est encadrée de trois tirets au début et à la fin.

L’en-tête YAML n’est pas indispensable pour produire un document mais une en-tête YAML minimale permet de modifier les valeurs par défaut et d’améliorer la qualité du document (mise en page et métadonnées du document).

Ci-dessous un exemple d’une courte entête YAML qui contient quelque instructions de mise en forme et les métadonnées du document produit (ici pdf).

– – –
documentclass: article
header-includes:
– \usepackage[french]{babel}
– \usepackage[utf8]{inputenc}
– \usepackage[a4paper, top=2.5cm, bottom=2.5cm, left=2.5cm, right=2.5cm]{geometry}
title: Titre du document
subtitle: Sous-titre du document
author: Nom, Prénom
date: 2021
abstract: Ce court document est destiné à démontrer les possibilités de *Markdown* …
fontsize: 11pt
bibliography: library.bib
csl: apa.csl
– – –

Pour des explications sur ces instructions et pour découvrir toutes les possibilités, voir le chapitre suivant.

… en résumé

image
Schéma de synthèse du workflow

 

  1. http://www.aaronsw.com/weblog/001189 ↵
  2. https://github.com/jgm/pandoc/wiki/Pandoc-User's-Manual-in-French ↵
  3. https://fr.wikibooks.org/wiki/LaTeX ↵
  4. https://fr.wikipedia.org/wiki/Gedit ↵
  5. https://www.iana.org/assignments/markdown-variants/markdown-variants.xhtml ↵
  6. Spécifique pour les documents déclarés en français (voir le chapitre YAML). ↵
  7. limité à une ligne de texte. ↵
  8. voir un manuel LaTeX pour voir toutes les possibilités. ↵
  9. https://www.tablesgenerator.com/markdown_tables ↵
  10. https://en.wikibooks.org/wiki/LaTeX/Mathematics ↵
  11. http://www.hostmath.com/ ↵
  12. https://zotero.hypotheses.org/2258 ↵

Licence

Symbole de Licence Creative Commons Attribution 4.0 International

Markdown & vous Copyright © 2023 by Bernard Pochet is licensed under a Licence Creative Commons Attribution 4.0 International, except where otherwise noted.

Partagez ce livre