Markdown

Ce que c'est

Markdown permet d’écrire un document dans un fichier texte ordinaire
où quelques conventions d’écriture — astérisques autour d’un mot
pour l’emphase, croisillon devant un titre, tiret devant une entrée
de liste et crochets suivis de parenthèses pour un lien — indiquent
au convertisseur le HTML à produire. Le nom désigne la syntaxe, le
programme qui l’accompagnait à sa création et les dialectes dérivés,
dont CommonMark et GitHub Flavored Markdown (GFM). Les fichiers se
terminent généralement par `.md` ou `.markdown`.

John Gruber l’a développé en 2004 avec Aaron Swartz et a écrit le
premier convertisseur en Perl ; sa dernière version, Markdown 1.0.1,
date du 17 décembre 2004. Son objectif déclaré était avant tout la
lisibilité : un document Markdown devait être publiable tel quel, en
texte brut, sans paraître balisé par des étiquettes ou instructions
de mise en forme. La principale influence sur la syntaxe,
écrivait-il, était la manière dont on mettait déjà en forme les
courriels en texte brut. Ce que la syntaxe ne couvre pas s’écrit en
HTML au milieu du texte, sans commutateur ni délimiteur : pour lui,
Markdown est un format d’écriture, HTML un format de publication.

Quelques lignes en montrent l’essentiel :

```markdown
Le transfert a pris **une soirée**, en trois étapes :

i- arrêter les écritures		engineer.company	70
i- copier les données avec `pg_dump`		engineer.company	70
i- diriger l’[application](https://example.com/app/) vers le nouvel hôte		engineer.company	70
```

Un convertisseur en fait un paragraphe avec un élément `strong`, une
liste à trois entrées, un fragment de code et un lien ; la source se
lit toujours comme une note tapée par quelqu’un.

Pourquoi c'est important

La source est le document et le texte brut survit à tous les outils
qui l’entourent. Un fichier Markdown s’ouvre dans tout éditeur, se
compare ligne par ligne en gestion de versions et se relit
proprement dans une demande de fusion. Aucun fournisseur ne peut
faire disparaître le format ; déplacer des écrits entre systèmes
revient à copier des fichiers.

Le prix est l’ambiguïté. CommonMark le dit clairement : la
description de Gruber ne définit pas la syntaxe sans équivoque, son
script comportait des bogues et sa dernière mise à jour datait de
décembre 2004. En 2014, des dizaines d’implémentations comblaient
donc chacune les lacunes à leur manière. Son exemple est un document
rendu différemment dans un wiki GitHub et en DocBook avec Pandoc.
Comme Markdown ne rejette aucune entrée pour erreur de syntaxe,
seule l’observation du résultat révèle la divergence. Le projet
renvoie à Babelmark 3, qui passe une même entrée dans plus de vingt
implémentations pour comparer leurs résultats.

CommonMark, lancé en 2014, répond par une spécification de John
MacFarlane associant chaque règle à des exemples d’entrée et au HTML
exact attendu : 652 dans la version 0.31.2 du 28 janvier 2024.
GitHub définit GFM comme un sur-ensemble strict de CommonMark,
ajoutant tableaux, entrées de tâches à cocher, texte barré, liens
automatiques étendus et filtre neutralisant une courte liste de
balises HTML brutes. Goldmark, convertisseur Markdown de Hugo,
respecte CommonMark et est compatible avec GFM.

Markdown a aussi un nom sur le réseau. Depuis mars 2016, la RFC 7763
enregistre `text/markdown` pour toute la famille de syntaxes, avec
un `charset` obligatoire et un paramètre `variant` facultatif
indiquant le dialecte du fichier.

À quoi cela ressemble en pratique

Les pages écrites à la main de ce site sont en Markdown, mises en
page par des modèles Go ; les crédits citent les deux parmi les
outils de fabrication, à côté du générateur de site statique Hugo.
La même page nomme markdownlint parmi les linters gardant la source
correcte, dans un contrôle qualité où tout diagnostic est une
erreur.

La page rendant un site lisible par les agents d’IA inverse le sens
du format : chaque page possède ici un jumeau Markdown à la même
adresse, obtenu en ajoutant `index.md` ou en demandant
`text/markdown`. La construction lit chaque jumeau pour trouver du
balisage résiduel et refuse la publication si l’un est incorrect.
Une seule requête suffit pour obtenir le jumeau de cette page :

```sh
curl -sL https://engineer.company/ai-ready/index.md
```

Environ 50 000 mots de documentation logicielle ont été écrits en
Markdown sur GitHub, Craft et Confluence, en grande partie à la
main. Cette documentation couvrait l’architecture, les processus et
les modes d’emploi sans cesse demandés, restait versionnée et
trouvable, et aidait les nouveaux à devenir opérationnels plus vite.

Où les problèmes surviennent

Le gras affiche des astérisques. Le lecteur voit deux astérisques de
chaque côté d’un mot censé être en gras et tous les contrôles
réussissent, car le HTML est valide et les liens fonctionnent.
CommonMark n’ouvre l’emphase que sur une suite d’astérisques dite
« left-flanking », dont la position permet d’ouvrir l’emphase ; si
une ponctuation suit, comme le crochet d’un lien, il faut une espace
ou une ponctuation devant. Une lettre devant garde les astérisques
littéraux, tout comme un ajout du moteur de modèles avant l’analyse
Markdown : Hugo remplace un shortcode par une marque de substitution
en lettres et chiffres. Le modèle du jumeau Markdown de ce site
consigne que supprimer l’espace entre un shortcode et le gras voisin
a cassé ce gras sur 60 puces dans trois langues. Gardez l’espace et
vérifiez la page rendue plutôt que la source : le contrôle qualité
lit le HTML construit pour repérer du Markdown parvenu au lecteur
comme ponctuation.

Le même fichier produit deux rendus. Une liste imbriquée s’aplatit
sur un système et s’imbrique sur un autre ; un croisillon en début
de ligne devient un titre dans un convertisseur et du texte dans un
autre. Rien ne le signale, car Markdown n’a pas d’erreurs de
syntaxe. Deux convertisseurs comblent différemment une lacune
initiale : leurs dialectes divergent. Nommez le dialecte du projet,
généralement CommonMark ou GFM, utilisez un linter qui l’impose et
passez les entrées douteuses par plusieurs implémentations avant de
vous y fier.

La copie Markdown transporte du HTML. Le lecteur de la version texte
rencontre du `svg` brut ou un numéro de téléphone commençant par une
référence numérique de caractère au lieu d’un plus. Un composant
produisant du HTML pour le web le produit aussi pour tous les autres
formats sans consigne contraire : Hugo cherche le modèle d’un
shortcode par format de sortie et se replie sur le HTML. Les modèles
de ce site consignent les deux cas : 49 éléments `svg` bruts dans la
copie Markdown des crédits et le numéro de contact échappé pour
HTML. Désormais, tout shortcode écrivant du balisage possède son
modèle Markdown. Le contrôle vérifie aussi l’absence de HTML brut et
d’entités HTML dans les jumeaux, hors code.

Le HTML brut disparaît. Un bloc HTML saisi dans le Markdown manque
dans la page construite, malgré une source apparemment correcte.
Gruber autorise le HTML partout, mais un convertisseur peut le
refuser : le réglage `unsafe` de Goldmark dans Hugo est désactivé
par défaut, empêchant le rendu du HTML brut mêlé au Markdown. GFM
échappe certaines balises comme `script` et `iframe` pour les
afficher en texte. Utilisez plutôt les moyens du générateur,
shortcode ou crochet de rendu dans Hugo, ou activez volontairement
le réglage en acceptant ce qu’il laisse passer.

Le linter accepte ce qu’on lui a dit d’ignorer. Un fichier mal
structuré passe la revue parce que markdownlint ne signale rien. Les
règles capables de le détecter ont été désactivées sans
justification. Les règles de développement de ce site consignent
qu’une configuration JSON désactivait six règles sans commentaire ;
leur examen a montré que deux masquaient de vrais défauts. Écrivez
la raison à côté de chaque règle désactivée, dans un format
acceptant les commentaires, pour que la personne suivante puisse la
contester.

Pour aller plus loin

  * Spécification CommonMark — les règles, chacune associée à des
entrées d’exemple et au HTML attendu.

  * CommonMark — le besoin d’une spécification, les divergences
entre implémentations et les personnes qui le maintiennent.

  * Markdown, par John Gruber — la description initiale, l’objectif
de conception et le script Perl.

  * Markdown : syntaxe — la présentation de Gruber, dont le HTML
intégré.

  * Spécification GitHub Flavored Markdown — le dialecte GitHub
comme sur-ensemble de CommonMark, chaque extension indiquée.

  * RFC 7763 : type de média text/markdown — le type de média, son
`charset` obligatoire et son paramètre `variant`.

hCette page sur le Web	URL:https://engineer.company/fr/glossary/markdown/	engineer.company	70
