Écrire en Markdown

Le site génial Programming Historian avait publié en 2014 (déjà !) un excellent article de Dennis Tenen et Grant Wythoff, intitulé Rédaction durable avec Pandoc et Markdown. Voici ce qu'en disent les auteurs :

Markdown est une syntaxe qui permet le marquage sémantique des éléments à l’intérieur du document de manière explicite, et non dans une couche dissimulée sous la surface. Il s’agit d’identifier les unités porteuses de sens pour les humains, comme les titres, sections, sous-sections, notes de bas de page et illustrations. Ainsi, vos fichiers resteront à tout le moins lisibles pour vous, même si le logiciel que vous utilisez actuellement cesse de fonctionner ou « met la clé sous la porte ».

Écrire ce cette façon libère l’auteur(e) de son outil. Vous pouvez écrire en Markdown dans n’importe quel éditeur de texte brut, et la syntaxe dispose d’un riche écosystème de logiciels qui peuvent transformer ces textes en de magnifiques documents. C’est pour cette raison que Markdown connaît actuellement une hausse de popularité, non seulement comme outil de rédaction d’articles scientifiques, mais aussi comme norme pour l’édition en général.

Apprendre le langage de balisage Markdown est vraiment très facile.

Prenez votre éditeur de texte. Sous Linux Mint, il se trouve dans la partie Accessoires des programmes installés par défaut. Rangé sous le nom « Éditeur de texte », son vrai nom est Xed.

Entrez ce texte et enregistrez-le sous le nom martin.md :

# Cours du professeur Martin

Le cours portait aujourd'hui sur le droit romain et plus
 exactement **l'ordre de la chevalerie romaine**. 
Bien qu'inférieur à _l'ordre sénatorial_, cet ordre a
 un poids électoral très important, en plus de constituer
 une classe militaire. Les membres sont cependant exclus
 du _cursus honorum_ réservé aux sénateurs.
 Il faut cependant posséder certains biens. 

Pour citer Tite Live :

> La première classe était composée de ceux qui 
> possédaient un cens de cent mille as et au-delà; 
> elle était partagée en quatre-vingts centuries, 
> quarante de jeunes gens et quarante d'hommes plus mûrs.
> 
> -- Tite Live, _Histoire romaine_ (I, 43)

Vous avez compris que l'extension .md est lue par le système comme une extension d'un fichier texte formaté en markdown. Dès lors votre éditeur, équipé d'un système de coloration syntaxique reconnaît tout seul les éléments, les colorise, ce qui produit pour vous une vision hiérarchisée des informations. L'esthétique fonctionnelle des éditeurs spécialisés pour le Markdown produira bien entendu un meilleur confort que ce que peut produire votre éditeur de texte basique.

La syntaxe¶

Pour reprendre la définition de Wikipédia :

Markdown est un langage de balisage léger créé en 2004 par John Gruber, avec l'aide d'Aaron Swartz, avec l'objectif d'offrir une syntaxe, facile à lire et à écrire, en l'état, sans formatage.

La syntaxe Markdown originelle se trouve sur le site personnel de John Gruber. Mais il y a d'autres enrichissements possibles, comme ceux fournis par Pandoc, un logiciel de conversion dont nous reparlerons plus tard.

Voici un aperçu du balisage Markdown.

Paragraphes¶

Les paragraphes sont des lignes de texte consécutives, séparées par une ou plusieurs lignes blanches (vides, ou qui ne contient rien d'autre que des espaces).

Titres¶

Les titres sont créés avec le symbole #. Plus il y a de #, plus le niveau de titre est bas.

# Titre de niveau 1 (Titre du document)
## Titre de niveau 2 (Grandes sections)
### Titre de niveau 3 (Sous-sections)
etc.

Mise en forme des caractères¶

Le Markdown utilise des symboles simples pour enrichir le texte sans lever les mains du clavier.

Gras : **texte en gras** ou __texte en gras__
Italique : *italique* ou _italique_
~~Barré~~ : ~~texte barré~~
Gras et italique : ***gras et italique***

Listes¶

Listes à puces (non ordonnées) :

- Utilisez l'astérisque *    
- Ou le tiret - 
    - On crée une sous-liste avec une tabulation.

Listes numérotées (ordonnées) :

(un éditeur Markdown gère l'incrémentation automatiquement)

1. Premier élément
2. Deuxième élément
etc.

Liens et Images¶

La syntaxe est proche pour les deux, l'image commençant par un point d'exclamation.

Lien hypertexte : [Texte du lien](https://www.exemple.com)
Image : ![Légende de l'image](chemin/vers/image.jpg)

Notes de bas de page¶

Pour insérer des notes, il suffit d'écrire ainsi :

Comme le disait le professeur Martin[^1], il ne suffit pas de franchir le Rubicon pour se déclarer empereur.

Et placer la note formulée ainsi à n'importe quel endroit du document. Peu importe que vous utilisiez [^1] ou [n1] ou [truc], l'essentiel est que l'appel de note soit le même que celui de la note.

[^1]: Nous avons déjà parlé du professeur Martin au début de ce chapitre.

Citations¶

> On utilise le signe > pour créer un bloc de citation.
> 
> « C'est ainsi que l'on met en valeur une source. »

Références bibliographiques¶

Les références bibliographiques doivent pouvoir être lues lors de la conversion de votre fichier Markdown et compilées selon le modèle que vous aurez choisi. Si vous avez l'habitude d'utiliser Zotero, vous savez que l'extension Zotero dans votre logiciel de traitement de texte se configure. C'est là que vous choisissez le modèle CSL (Citation Style Language) parmi ceux répertoriés sur le dépôt de Zotero.

Écrire en Markdown implique de privilégier la rapidité et la malléabilité. Un même texte devra pouvoir être converti par la suite en utilisant n'importe quel style de bibliographie. Ainsi on n'emprisonne pas son texte dans un style donné.

Pour faire des références bibliographiques en Markdown, on utilise une syntaxe spécifique qui permet à un moteur (comme Pandoc) de faire le lien entre votre texte et une base de données de livres ou d'articles.

Nous verrons plus loin comment gérer sa bibliographie dans notre système de production. Pour l'instant je me contente d'expliquer comment appeler une source dans le texte (.md).

Pour citer une source on utilise le signe @.

Style de citation	Syntaxe Markdown	Rendu
Simple	`[@foucault1975]`	(Foucault, 1975)
À la page	`[@foucault1975, p. 42]`	(Foucault, 1975, p. 42)
Auteur déjà cité dans le texte	`bla bla Foucault [-@foucault1975]`	Foucault (1975)
Citations multiples	`[@foucault1975; @deleuze1980]`	(Foucault, 1975 ; Deleuze, 1980)

Évidement, selon le style que vous utiliserez par la suite, vos citations seront présentées différemment. Le style (auteur, date) n'est utilisé ici « pour vous » dans le texte que vous écrivez. Par la suite, vous pourrez choisir par exemple de reporter vos citations en notes de bas de page, en fin de chapitre, etc.

Par défaut, Pandoc génère la liste complète des références citées tout à la fin de votre document. Il vous suffit de terminer votre fichier Markdown par un titre de section :

# Bibliographie

Le logiciel insérera automatiquement toutes les notices bibliographiques sous ce titre, classées par ordre alphabétique et formatées selon le style choisi (ISO, APA, etc.).

Enfin, sachez que des logiciels comme Zettlr (nativement) ou Obsidian (avec le plugin Citations) automatisent cela :

Vous liez votre fichier .bib dans les réglages du logiciel.
En tapant @ dans votre texte, une liste déroulante de vos références apparaît.
Vous n'avez plus qu'à choisir l'ouvrage, et le logiciel s'occupe du reste.

Pour résumer la syntaxe :

@clé : citation simple.
[@clé] : entre parenthèses.
[-@clé] : supprimer l'auteur (si déjà cité dans la phrase).
[voir @clé, p. 12] : avec du texte avant/après.

Les en-têtes¶

Pour qu'un fichier Markdown soit traité avec « intelligence » et puisse être traité correctement par Pandoc (voir chapitre suivant) ou par des logiciels comme Zettlr, et afin d'être exploitable, par exemple dans une base de données, il a besoin d'une carte d'identité. C'est le rôle de l'en-tête YAML.

1. Qu'est-ce que le YAML ?¶

Le YAML (YAML Ain't Markup Language) est un format de données très lisible dont on peut placer un bloc tout en haut d'un fichier Markdown. Dans ce cas, il sert à définir les métadonnées du document : ce sont des informations sur le texte qui ne font pas partie du corps du texte lui-même.

L'en-tête doit impérativement commencer et se terminer par trois tirets (---).

2. Exemple d'un en-tête standard¶

Voici à quoi ressemble un en-tête classique :

---
title: "L'impact de la technologie sur les SHS"
subtitle: "Rapport d'étape 2025"
author: "Jean Dupont"
date: "21 décembre 2025"
lang: fr-FR
keywords: [Linux, Markdown, Recherche]
---

3. Pourquoi est-ce indispensable ?¶

Le YAML transforme votre simple note de texte en un objet structuré.

Anecdote : je converti mon fichier markdown de manière simple avec la commande pandoc monfichier.md -o monnouveaufichier.odt. J'ouvre ensuite mon fichier avec Libre Office et, Ô stupeur, tout est souligné en rouge parce que la langue par défaut est en fait en anglais et j'ai écrit en français.

L'explication est simple : pour transformer mon document, Pandoc utilise un modèle (template) qu'il a par défaut. Si je ne renseigne pas la langue de mon document soit dans l'en-tête YAML soit dans ligne de commande, c'est la langue par défaut qui sera utilisée dans le fichier de sortie.

L'en-tête YAML automatise la mise en page lors de la conversion, mais pas uniquement :

Pour le format Word/ODT : Pandoc utilisera les champs title et author pour remplir automatiquement les propriétés du document et créer un titre au début.
Pour le format PDF : ces informations peuvent servir à générer la page de garde.
Pour la gestion de fichiers : des logiciels comme Zettlr, Logseq ou Obsidian utilisent les keywords (ou tags) pour classer vos notes, permettre d'effectuer des recherches, voire faire des bases de données.

4. Exemple avancé avec bibliographie¶

C'est ici que le YAML devient puissant. Au lieu de taper de longues commandes dans le terminal, vous pouvez inscrire vos préférences directement dans le fichier :

---
title: "Analyse des systèmes complexes"
author: "Claire Martin"
bibliography: "ma_base_de_donnees.bib"
csl: "iso690-fr-numeric.csl"
link-citations: true
abstract: "Ce document présente les résultats préliminaires de notre enquête de terrain menée entre 2024 et 2025."
lang: fr-FR
keywords: |
  - informatique
  - ingénierie
  - enquête
---

Ici nous avons renseigné plusieurs éléments qui non seulement décrivent le document mais donnent aussi des informations sur des fichiers complémentaires : la bibliographie et le style de références (CSL). Notez que link-citations: true rend vos citations cliquables dans le PDF final (elles renvoient à la bibliographie en fin de page).

Au sujet de la syntaxe YAML¶

L'espace après les deux-points : elle est obligatoire. Écrivez title: "Mon titre" et non title:"Mon titre".
Les guillemets : ils ne sont pas toujours obligatoires, mais vivement conseillés si votre titre contient des caractères spéciaux (comme : ou ?).
L'indentation : si vous faites des listes dans le YAML, utilisez deux espaces pour décaler les éléments.