Markdown
Texte brut dont quelques signes indiquent la mise en forme
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 :
Le transfert a pris **une soirée**, en trois étapes :
- arrêter les écritures
- copier les données avec `pg_dump`
- diriger l’[application](https://example.com/app/) vers le nouvel hôteUn 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.

Photo : Darkmoon_Art / Pixabay 
Photo : iniesta44 / Pixabay
Utilisez le concept pour prendre une décision
Utilisez « Qu’est-ce que Markdown ? » pour éclairer une décision réelle. Nous pouvons vous aider à relier ce concept au système que vous construisez ou achetez. Un site rapide, facile à trouver et modifiable par votre équipe, sans facture à chaque changement de texte.
Vérifiez les hypothèses derrière le terme
Appuyez-vous sur l'explication et les réalisations liées pour formuler les questions de votre projet. Nous pouvons examiner les hypothèses avec vous avant le choix d'un outil. 100 applications web avec HTML/HTML5 — 100 applications web développées
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 :
curl -sL https://engineer.company/ai-ready/index.mdEnviron 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
charsetobligatoire et son paramètrevariant.

