Markdown

Historique

Markdown est donc un langage de balisage léger. Il été co-créé par Aaron Swartz et John Gruber en 2004 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.

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 qui fait appel à LaTeX 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 document (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). 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 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 pouvez télécharger un modèle de document dans l'onglet "Télécharger".

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

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êche 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.

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 :

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 :

Les listes doivent être précédées d'un saut de ligne. Il est possible de combiner les deux types de listes comme par exemple :

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 :

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 :

(il est possible de les combiner).

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

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

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 :

Autres codes utiles pour la mise en forme

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

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 le 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 :

À 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 :

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.

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 :

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.

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 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 :

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. Vous pouvez aussi utiliser un éditeur en ligne 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.

L'entête YAML

Pandoc prend en charge les entêtes YAML pour les fichiers Markdown. Cet acronyme n'est pas simple à traduire, il vient de YAML Ain’t Markup Language telle que le définit le site yaml.org.

L'entê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'entête YAML n'est pas indispensable pour produire un document mais une entê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 la page YAML.

... en résumé

Schéma de synthèse du workflow