Guide Markdown : premiers pas

Markdown est une syntaxe de mise en forme en texte brut qui transforme des symboles tapés au clavier en documents structurés, et son noyau s'apprend en 10 minutes environ. John Gruber l'a publié en mars 2004 avec la contribution d'Aaron Swartz, et 22 ans plus tard, il met en forme les fichiers README sur GitHub, les notes dans Obsidian et les publications sur Reddit. Le système repose sur deux éléments : un fichier texte enregistré avec l'extension .md et un processeur qui convertit ce texte en HTML. Tout ce qui suit s'appuie sur ces deux éléments.

Qu'est-ce que Markdown ?

Markdown est un langage de balisage léger créé en 2004 qui ajoute des instructions de mise en forme au texte brut grâce à des caractères visibles comme #, * et >. Un # en début de ligne crée un titre. Deux astérisques autour d'un mot le mettent en gras. Un tiret court démarre une puce. La version d'origine était un simple script Perl, Markdown.pl, publié sur le site Daring Fireball de Gruber.

Les langages de balisage plus lourds, HTML et LaTeX en tête, enferment le contenu dans des balises et des commandes qui encombrent le fichier source. Markdown a pris le chemin inverse. Gruber a conçu la syntaxe autour d'un objectif unique : un fichier markdown doit se lire clairement en texte brut avant toute conversion. La ligne ## Pricing est visiblement un titre, même pour quelqu'un qui n'a jamais entendu parler de markdown. C'est cette lisibilité qui a permis au format de passer des blogs en 2004 à GitHub en 2008, à Stack Overflow en 2010, puis aux applications de notes comme Obsidian et Joplin au fil des années 2010.

En quoi Markdown diffère des éditeurs WYSIWYG

Un éditeur WYSIWYG comme Microsoft Word ou Google Docs applique la mise en forme via des boutons de barre d'outils et masque les instructions ; markdown garde chaque instruction visible sous forme de caractères dans le fichier. WYSIWYG signifie "what you see is what you get" (ce que vous voyez est ce que vous obtenez). Dans Word, vous sélectionnez une phrase et cliquez sur le bouton Gras, et le fichier enregistre cette décision dans un XML binaire que vous ne voyez jamais. En markdown, vous tapez **launch date** et les deux paires d'astérisques constituent la mise en forme.

La différence apparaît au moment de l'enregistrement. Un fichier .docx s'ouvre correctement dans une courte liste de programmes, Word, LibreOffice et Pages principalement. Un fichier markdown s'ouvre dans n'importe quel éditeur de texte sorti depuis les années 1970, de Notepad à vim en passant par VS Code. De nombreux éditeurs markdown comblent l'écart visuel avec un aperçu en direct sur écran partagé : la syntaxe brute dans le volet de gauche, le rendu dans le volet de droite, actualisé à chaque frappe. Vous obtenez le retour immédiat de Word avec la transparence du texte brut.

Pourquoi utiliser Markdown ?

Les rédacteurs choisissent markdown pour quatre raisons pratiques : la portabilité, l'indépendance vis-à-vis des plateformes, la pérennité et la polyvalence. Chacune découle de sa base en texte brut.

• Portabilité. Un fichier markdown passe d'une application à l'autre sans conversion. Rédigez un article dans iA Writer, modifiez-le dans VS Code, publiez-le via Ghost. Le fichier ne change jamais de forme. Les formats propriétaires comme .docx et .pages enferment le contenu dans l'écosystème d'un seul éditeur.
• Indépendance vis-à-vis des plateformes. Markdown fonctionne à l'identique sous Windows 11, macOS, Linux, iOS et Android. Le fichier est du texte UTF-8, donc une note tapée sur un téléphone en 2026 s'ouvre à l'octet près sur un ordinateur de bureau.
• Pérennité. Les logiciels meurent ; les fichiers texte survivent. WordPerfect dominait le traitement de texte en 1990 et ses anciens fichiers relèvent aujourd'hui de la récupération de données. Un fichier markdown de 2004 s'ouvre toujours en moins d'une seconde, ce qui compte pour les thèses, les contrats et les manuscrits de livres pensés sur des horizons de 20 ans.
• Polyvalence. Des plateformes comme GitHub, GitLab, Reddit, Discord, Notion et Slack acceptent la saisie en markdown. Apprenez la syntaxe une fois et elle vous sert partout.

Comment fonctionne le traitement Markdown

Markdown devient un document mis en forme grâce à un pipeline en 4 étapes : vous écrivez un fichier .md, un processeur l'analyse, le processeur produit du HTML, puis un navigateur affiche ce HTML. Le processeur, aussi appelé parseur ou implémentation, est le moteur qui équipe chaque application markdown. Parmi les processeurs populaires figurent markdown-it, marked, cmark et Pandoc, et cmark convertit un document classique en moins de 10 millisecondes.

Chaque outil expose une portion différente de ce pipeline. Un éditeur en ligne avec aperçu en direct exécute les étapes 2 à 4 de façon invisible à chaque frappe. Un générateur de site statique comme Hugo exécute le même pipeline sur des centaines de fichiers en une seule commande de build. Le pipeline lui-même ne change jamais, et le HTML produit s'associe à n'importe quelle feuille de style CSS ou se convertit ensuite en PDF, EPUB ou .docx via un outil comme Pandoc.

À quoi sert Markdown ?

Markdown couvre sept usages courants : sites web, notes, documents, livres, présentations, e-mail et documentation technique. La même syntaxe apprise en 10 minutes couvre les sept.

Sites web

Les générateurs de sites statiques comme Hugo, Jekyll et Eleventy construisent des sites web entiers à partir de dossiers de fichiers markdown. Jekyll, sorti en 2008, propulse GitHub Pages et son hébergement gratuit. Les plateformes de contenu acceptent aussi markdown : Ghost intègre un éditeur markdown natif, et WordPress accepte markdown via son éditeur de blocs. Un article de blog tient dans un seul fichier .md, et les systèmes de gestion de versions comme Git en suivent chaque modification.

Notes et documents

Les applications de notes comme Obsidian, Joplin, Bear et Simplenote stockent chaque note au format markdown. Obsidian, par exemple, conserve chaque coffre sous forme de dossier de fichiers .md sur votre propre disque, si bien qu'une collection de 5 000 notes reste consultable avec des outils standards. Pour les documents ponctuels, courriers, comptes rendus de réunion et devoirs, un éditeur markdown exporte directement en PDF ou en HTML, et le PDF s'imprime, se joint à un e-mail ou se dépose n'importe où.

Livres et présentations

Leanpub transforme un dossier de fichiers markdown en ebook fini aux formats PDF et EPUB, et Pandoc fait de même en ligne de commande. Des auteurs ont publié des romans complets et des ouvrages techniques de 300 pages de cette manière. Pour les diapositives, des outils comme Marp et Remark convertissent un fichier markdown en présentation, avec un séparateur --- par diapositive, ce qui se révise plus vite qu'un fichier PowerPoint de 40 diapositives mises en forme à la main.

E-mail et documentation technique

Des extensions de navigateur comme Markdown Here convertissent le markdown en e-mail HTML mis en forme dans Gmail et d'autres messageries web. La documentation est le terrain de prédilection de markdown : GitHub affiche le rendu du README.md en tête de chaque dépôt, et des générateurs comme MkDocs, Docusaurus et Read the Docs construisent des sites de documentation complets à partir de fichiers sources .md. Docusaurus, publié par Meta en 2017, ajoute le versionnage et la recherche par-dessus de simples pages markdown.

Les variantes de Markdown : CommonMark et GFM

Une variante (ou "flavor") de markdown est une version spécifique de la syntaxe, et les deux qui comptent le plus sont CommonMark, spécifiée en 2014, et GitHub Flavored Markdown, spécifiée en 2017. La version de Gruber en 2004 laissait des cas limites sans définition, comme l'indentation des listes imbriquées, si bien que les premiers processeurs produisaient des résultats divergents. Le même fichier s'affichait différemment selon les outils.

CommonMark a corrigé cela. Publiée en septembre 2014 par un groupe de travail qui comprenait John MacFarlane et Jeff Atwood, la spécification CommonMark fixe chaque règle d'analyse à travers plus de 600 cas de test. Stack Overflow a migré son rendu vers CommonMark en juin 2020.

GitHub Flavored Markdown, ou GFM, est un sur-ensemble strict de CommonMark que GitHub a formalisé en mars 2017. Il ajoute cinq extensions : les tableaux, les listes de tâches, le texte barré, les liens automatiques et les blocs de code délimités avec étiquette de langage. Quand une fiche produit annonce qu'elle "supporte markdown", vérifiez de quelle variante il s'agit, car un tableau GFM s'affiche comme de simples caractères barre verticale dans un outil limité à CommonMark. GFM est le choix par défaut le plus sûr en 2026, et c'est la variante que l'éditeur de ce site restitue.

Comment débuter avec Markdown dès aujourd'hui

Ouvrez un éditeur markdown en ligne, tapez un # suivi d'un titre, et vous venez d'écrire votre premier markdown ; il n'y a rien à installer et aucun compte à créer. Un éditeur à double volet affiche le rendu pendant que vous tapez, ce qui constitue la boucle de retour la plus rapide pour apprendre la syntaxe.

Commencez par les cinq éléments les plus fréquents : # pour les titres, **bold** pour le gras, *italic* pour l'italique, - pour les listes et [text](url) pour les liens. Ces cinq éléments couvrent environ 90 % de la mise en forme quotidienne. Entraînez-vous en réécrivant quelque chose de réel, une note de réunion ou une liste de tâches, puis enregistrez le résultat dans un fichier .md. Ensuite, le guide de la syntaxe de base couvre les 9 éléments fondamentaux, et le guide de la syntaxe étendue ajoute les tableaux GFM, les notes de bas de page et les listes de tâches.

Questions fréquentes

Faut-il installer un logiciel pour écrire en markdown ?

Un navigateur web suffit ; un éditeur markdown en ligne gère la rédaction, l'aperçu et l'export sans aucune installation. Les applications de bureau comme Obsidian, iA Writer et VS Code ajoutent l'accès hors ligne et la gestion de fichiers locaux quand vous en aurez besoin.

Quelle extension de fichier utilise un fichier markdown ?

Les fichiers markdown utilisent l'extension .md, avec .markdown comme alternative moins courante. Les deux contiennent un texte brut identique, et chaque processeur markdown, de cmark à Pandoc, accepte l'une comme l'autre.

Combien de temps faut-il pour apprendre markdown ?

Les cinq éléments de base s'apprennent en 10 minutes environ, et la syntaxe de base complète de 9 éléments tient en une seule session. Les extensions GFM comme les tableaux et les listes de tâches demandent 15 minutes de plus. Comparez avec LaTeX, où une mise en forme correcte demande des semaines.

Quelle est la différence entre CommonMark et GFM ?

CommonMark est la spécification de base de 2014 qui standardise l'analyse du markdown fondamental, et GFM est le sur-ensemble de GitHub datant de 2017 qui ajoute les tableaux, les listes de tâches, le texte barré, les liens automatiques et les blocs de code délimités. Tout document CommonMark valide est aussi du GFM valide, donc écrire en GFM est le choix pratique.