Prévisualisation Markdown en ligne, gratuite

Aide-mémoire Markdown

À propos de Markdown

Markdown a été créé par John Gruber, l’auteur derrière le blog Daring Fireball, avec un retour de conception substantiel d’Aaron Swartz. La première version publique, 1.0, a été annoncée sur le site de Gruber le 9 mars 2004 ; la version 1.0.1, la version de référence canonique, a suivi le 17 décembre 2004 et reste la version liée depuis daringfireball.net/projects/markdown. Markdown est deux choses à la fois : une syntaxe de formatage en texte brut et le script Perl original qui convertit cette syntaxe en HTML. L’objectif déclaré de Gruber était que le texte source soit lisible tel quel, un document Markdown ouvert dans un éditeur de texte brut devrait ressembler à un e-mail soigneusement formaté, pas à une soupe de balises. Cette contrainte de lisibilité est la ligne philosophique qui sépare Markdown des formats basés sur XML et des balisages plus lourds comme LaTeX, et c’est la raison pour laquelle chaque extension ultérieure a dû se justifier en termes de gravité de la perturbation de la source.

Gruber crédite longuement Swartz dans les remerciements de Markdown : « Aaron Swartz mérite énormément de crédit pour ses retours sur la conception de la syntaxe de formatage de Markdown. » Swartz avait écrit auparavant un balisage léger apparenté appelé atx (2002), qui a contribué au style de titre désormais familier # et ##: parfois encore appelé « atx-style headings » dans les specs de parsers. L’implication de Swartz fait partie de son héritage plus large : il a co-construit RSS 1.0 alors qu’il était adolescent, a été co-propriétaire de Reddit jusqu’en 2007, et a continué d’influencer les standards du web ouvert jusqu’à sa mort en 2013. Une anecdote à bien comprendre : l’extension de fichier .md est désormais quasi universelle, mais l’outil original de Gruber utilisait .text: la migration vers .md a été une convention communautaire qui s’est imposée une fois que Markdown a quitté la niche du blogging.

Pourquoi Markdown a gagné le web

Un langage de balisage gagne en étant adopté par les plateformes qui publient la majorité du texte mondial. Dans une fenêtre serrée de cinq ans, Markdown a été adopté par les plateformes qui en sont venues à dominer la discussion longue, la collaboration de code et la documentation pour développeurs. Stack Overflow a été lancé le 15 septembre 2008 avec Markdown comme syntaxe de formatage pour les questions, réponses et commentaires, en utilisant un éditeur appelé WMD (Wysiwym Markdown) par John Fraser d’AttackLab ; l’équipe de Stack Overflow l’a ensuite réécrit en éditeur open-source PageDown maintenu sur github.com/StackExchange/pagedown. Reddit, fondé par Steve Huffman et Alexis Ohanian en 2005 avec Aaron Swartz qui a rejoint peu après, a livré Markdown pour les commentaires peu après le lancement et a porté la syntaxe vers un public bien plus large, non développeur. GitHub a été lancé en 2008 et en moins d’un an rendait Markdown dans README.md et les commentaires d’issues ; en 2009 il a commencé à documenter et à livrer son propre dialecte, GitHub Flavored Markdown. Discord, lancé en mai 2015, a adopté une syntaxe de chat à saveur Markdown pour le gras, l’italique, le barré, le code inline, les blocs de code et les blockquotes, ce que la plupart des non-développeurs de moins de 25 ans appellent maintenant « mettre des étoiles autour de quelque chose ». La compétence se cumule : un auteur qui apprend Markdown une fois peut écrire des billets de blog dans Jekyll/Hugo/Eleventy, de la documentation dans MkDocs/Docusaurus/Read the Docs, des présentations dans Marp et Reveal.js, des notes dans Obsidian/Bear/Logseq/Notion, du chat dans Slack et Discord, et de la documentation de code source dans à peu près tout projet open-source moderne.

CommonMark, corriger la sous-spécification

La description originale de la syntaxe de Gruber de 2004 était fameusement informelle, un document en prose avec des exemples, pas une grammaire. Elle laissait des dizaines de cas limites non spécifiés (« comment l’emphase interagit-elle avec les underscores au milieu d’un mot ? » ; « une liste à l’intérieur d’un blockquote ferme-t-elle le blockquote ? » ; « qu’est-ce qui compte comme liste serrée vs liste lâche ? »), et Gruber n’a jamais publié de parser de référence autre que son script Perl, dont le comportement était idiosyncratique de manières que d’autres implémenteurs ont dû soit copier soit outrepasser. Le résultat au début des années 2010 était que GitHub, Reddit, Stack Overflow, Pandoc et le parser C Discount rendaient tous la même source Markdown légèrement différemment, et la même entrée pouvait casser entre plateformes.

En 2012, le co-fondateur de Stack Overflow Jeff Atwood (à l’époque dirigeant Discourse) et l’auteur de Pandoc John MacFarlane ont commencé un effort pour écrire une vraie spécification testable. Ils ont été rejoints par David Greenspan (Meteor), Vicent Marti (GitHub), Neil Williams (Reddit) et Benjamin Dumke-von der Ehe (Stack Exchange). Le projet a été lancé publiquement en septembre 2014 sous le nom de « Standard Markdown » ; en quelques jours, Gruber a objecté au nom dans un e-mail privé, Atwood a écrit un post public expliquant le changement, et le projet a été renommé « CommonMark ». La première release numérotée est arrivée le 25 octobre 2014. La version actuellement publiée est CommonMark 0.31.2, sortie le 28 janvier 2024, une « 1.0 » était promise pour 2019 et n’est pas arrivée parce qu’un petit nombre de cas limites pathologiques (notamment autour du parsing d’emphase et de l’embedding HTML) n’ont pas produit de résolutions unanimes. En pratique, 0.31.2 est traitée comme stable pour la production. La spec CommonMark est inhabituelle en ce qu’elle est elle-même un document CommonMark, avec plus de 600 cas de test exécutables en ligne ; un parser revendique la conformité en passant ces tests.

GitHub Flavored Markdown, cinq extensions par-dessus

La spécification formelle GFM, publiée en 2017 et plus récemment versionnée comme 0.29-gfm le 6 avril 2019, définit cinq extensions par-dessus CommonMark : tables (blocs délimités par des barres verticales avec une ligne de délimiteur utilisant des tirets et : pour l’alignement par colonne) ; éléments de liste de tâches (entrées de liste qui commencent par [ ] pour non cochées ou [x] pour cochées, rendues comme cases à cocher HTML désactivées, GitHub permet en plus aux utilisateurs connectés de les basculer en cliquant, ce qui est une couche UX par-dessus la spec, pas partie de la spec elle-même) ; barré (envelopper du texte dans ~~ produit <del>: CommonMark lui-même ne spécifie pas cela) ; extension autolinks (les URL et adresses e-mail nues dans le texte courant sont auto-liées, là où CommonMark ne le fait que pour les autolinks à crochets explicites) ; et HTML brut interdit (une restriction de sécurité qui supprime <script>, <iframe>, <style>, <title>, <plaintext>, <textarea>, <xmp>, <noembed>, <noframes> et une poignée d’autres balises dangereuses). Une sixième fonctionnalité couramment attribuée à GFM mais qui mérite d’être traitée avec soin est celle des blocs de code à fence avec identifiants de langue: les blocs de code à fence font partie de CommonMark lui-même ; l’indication de langue après la fence d’ouverture est aussi CommonMark ; la coloration syntaxique que GitHub applique ensuite sur la base de cette indication est un comportement de rendu de GitHub, pas de la spec. Le moteur de rendu de GitHub exécute aussi un post-traitement supplémentaire, sanitization HTML via son gem maison html-pipeline, expansion de shortcodes emoji (:smile:), autolinking @user et #issue: dont aucun ne fait partie de GFM lui-même.

Les principaux parsers

marked.js a été créé par Christopher Jeffrey, avec le copyright original daté de 2011, et a été maintenu par l’organisation GitHub markedjs depuis 2018. C’est une conception lexer-puis-parser en une passe qui privilégie la vitesse brute ; les docs le positionnent explicitement comme un « low-level compiler for parsing markdown without caching or blocking ». C’est le parser que ce previewer utilise actuellement pour le rendu en direct. Marked est petit, rapide, extensible via des hooks de tokens, et l’un des projets markdown les plus étoilés sur GitHub (~36k étoiles).

markdown-it a été lancé en 2014 par Vitaly Puzrin et Alex Kocharin. Les deux avaient contribué auparavant presque tout le code à un parser appelé Remarkable ; quand des disputes de leadership ont bloqué les progrès, ils ont réorganisé la même paternité autour de markdown-it. Le projet annonce une conformité 100% CommonMark avec des bascules GFM optionnelles pour les tables et le barré, plus un écosystème de plugins agressif (markdown-it-footnote, markdown-it-emoji, markdown-it-attrs, markdown-it-anchor, markdown-it-task-lists et plusieurs centaines d’autres). C’est le parser utilisé par la preview Markdown intégrée de VS Code, l’UI web de GitLab, et une longue liste de générateurs de sites statiques dont Eleventy.

remark / unified.js n’est pas un parser unique mais un framework de transformation d’arbres. Le collectif unified, démarré vers 2014, définit une spec d’arbre syntaxique abstrait appelée mdast (Markdown Abstract Syntax Tree) ; remark parse Markdown en mdast, des plugins manipulent l’arbre, et remark-rehype convertit mdast en hast (l’AST HTML) pour émission. Le modèle est plus lent que marked mais vastement plus composable. Les utilisateurs notables incluent Prettier (qui formate Markdown avec remark), Gatsby, MDN, le pipeline de documentation de Node.js, et le linter de langage inclusif alex. Le collectif unified liste 312 projets et environ 6,3 milliards de téléchargements npm mensuels sur tous ses paquets.

MDX, d’abord committé fin 2017 par John Otander et d’autres connectés à la société d’outils design Compositor, a été annoncé publiquement à ZEIT Day 2018 et a livré 1.0 le 11 avril 2019. MDX combine le contenu Markdown avec des composants JSX, donc un auteur peut déposer un <Chart /> ou un <Tweet id="123" /> directement dans la prose. Il alimente les docs Next.js, Docusaurus et la plupart des sites de documentation basés sur React. MDX a son propre parser distinct de CommonMark ; v1 était basée sur remark, v2+ utilise une grammaire MDX dédiée pour gérer correctement les expressions JSX dans le contexte de paragraphe.

Pandoc, le convertisseur universel

Pandoc a été publié par John MacFarlane, alors professeur de philosophie à l’Université de Californie, Berkeley, le 10 août 2006. Il est écrit en Haskell, et sa conception se centre sur le parsing de l’un de quelque 30 formats d’entrée (Markdown, reStructuredText, HTML, LaTeX, DocBook, Textile, balisage MediaWiki et DokuWiki, Org-mode, Microsoft Word .docx, OpenDocument, EPUB, JATS XML, Jupyter .ipynb et autres) en un modèle de document abstrait partagé, puis le rendu de ce modèle dans environ 40 formats de sortie (HTML, PDF via LaTeX ou wkhtmltopdf, .docx, .odt, ePub2/3, formats de diapositives dont Beamer et reveal.js, et bien d’autres). Il est omniprésent dans l’édition académique et technique parce qu’il porte les citations à travers CSL JSON / BibTeX et les résout en références formatées pour n’importe quel des principaux styles de citation. Le dialecte Markdown que Pandoc parse par défaut (« Pandoc Markdown ») est lui-même un sur-ensemble CommonMark avec des extensions pour les notes de bas de page, listes de définitions, divs à fence, mathématiques ($...$ et $$...$$ à la LaTeX) et légendes de tables. Pandoc est sous licence GPL v2-or-later et est ce que la plupart des départements académiques utilisent pour compiler des manuscrits Markdown en documents Word prêts pour publication.

MultiMarkdown, Markdown Extra et SmartyPants

Deux dialectes d’extension antérieurs précèdent CommonMark et ont influencé à la fois GFM et Pandoc. MultiMarkdown a été créé par Fletcher T. Penney avec une release initiale en mai 2007 (les travaux du projet ont commencé en 2005-2006), motivé par l’écriture académique, Penney voulait un Markdown capable de produire un manuscrit publiable avec notes de bas de page, citations, mathématiques, listes de définitions et métadonnées de document à la YAML. MultiMarkdown a introduit ou popularisé les tables à barres verticales, les marqueurs de notes de bas de page [^id], la notation mathématique, les blocs de métadonnées de niveau document en haut des fichiers, et les légendes d’images et de tables. Markdown Extra a été créé par Michel Fortin (auteur de PHP Markdown) en 2005-2006 et a ajouté les tables à barres, les blocs de code à fence avec ~~~ (plus tard aussi ```), les notes de bas de page, listes de définitions, abréviations et la syntaxe d’attribut {#id .class} pour les titres. Sa contribution la plus distinctive a été l’assouplissement des règles Markdown-dans-HTML, l’attribut markdown="1" qui permet d’imbriquer du Markdown dans un bloc HTML. Plusieurs choix de conception CommonMark et GFM autour du code à fence et des tables remontent à Markdown Extra. Séparément, SmartyPants: le compagnon typographique de Gruber lui-même de 2002, effectue des substitutions typographiques : les guillemets ASCII droits deviennent des guillemets courbes, les doubles et triples tirets deviennent des tirets demi-cadratin et cadratin, trois points deviennent une vraie ellipse. Markdown gère la structure ; SmartyPants gère le polissage ; beaucoup de parsers regroupent un comportement à la SmartyPants comme étape de post-traitement (markdown-it-smartypants, remark-smartypants), et Pandoc l’a intégré derrière un drapeau --smart.

Pièges courants, dix choses qui mordent les nouveaux auteurs

Un previewer en direct rend la plupart des surprises de parsing évidentes immédiatement, mais comprendre pourquoi elles arrivent aide un auteur à obtenir la source correcte du premier coup.

1. Conversion de guillemets intelligents qui casse les exemples de code. Les filtres à la SmartyPants convertissent joyeusement les guillemets dans ce qui ressemble à de la prose (y compris, parfois, à l’intérieur de spans de code inline ou de valeurs d’attribut HTML) vous laissant avec un balisage cassé. La plupart des parsers modernes excluent les spans de code de la substitution typographique, mais les plateformes de blog avec des pipelines personnalisés souvent ne le font pas.
2. La détection de marqueurs de liste est sensible aux espaces. Mélanger -, * et + à l’intérieur de la même liste, indenter les paragraphes de continuation de liste de moins que ce que le marqueur exige, ou mettre une ligne vide entre les items de liste peut basculer une liste serrée en liste lâche (chaque item enveloppé dans des balises <p>), une différence invisible dans la source mais spectaculaire dans la sortie.
3. Excès de zèle d’autolink. L’autolinking à la GFM transforme toute URL nue en lien, ce qui est habituellement ce que vous voulez, mais cela peut aussi mutiler des URL à l’intérieur de ce qui aurait dû être un span de code, ou des URL contenant des parenthèses (les URL Wikipédia particulièrement). La règle pour « où finit cette URL ? » varie entre parsers.
4. Indications de langue de fence de code. Le texte après le triple backtick d’ouverture, ```js vs ```javascript vs ```ts vs ```typescript: est une indication, pas une spec. Différents coloriseurs syntaxiques reconnaissent différents alias ; Highlight.js, Prism, Shiki et le moteur de rendu de GitHub ont chacun leurs propres dictionnaires de langues.
5. Tables qui nécessitent de l’échappement. Les caractères barre verticale à l’intérieur des cellules de table doivent être échappés en \|, sinon ils sont lus comme séparateurs de colonnes. Attrape quiconque essaie de mettre un exemple de code d’une ligne à l’intérieur d’une cellule de table.
6. Sauts de ligne durs. À l’intérieur d’un paragraphe, un saut de ligne unique est traité comme espace et les lignes sont jointes ; il faut soit mettre deux espaces de fin à la fin de la ligne, soit utiliser un backslash, selon le parser. CommonMark autorise les deux. Certains parsers plus anciens exigent un <br> explicite.
7. Markdown et HTML mélangés. Markdown a été conçu pour passer du HTML arbitraire à travers, donc déposer un <div class="callout"> dans un fichier Markdown fonctionne. Mais dès que vous mettez de la syntaxe Markdown à l’intérieur d’un bloc HTML, les parsers divergent : CommonMark traite la plupart des blocs HTML comme opaques ; Markdown Extra a introduit markdown="1" pour activer le parsing imbriqué.
8. Entités HTML et échappements de caractères. Une esperluette & dans une URL n’a pas besoin d’échappement à l’intérieur d’un lien Markdown, mais la même & en dehors d’un lien sera passée à HTML et peut nécessiter d’être & pour la conformité stricte HTML5. La plupart des moteurs de rendu gèrent cela automatiquement ; certains pas.
9. IDs de titre. GitHub auto-génère des IDs de fragment d’URL à partir du texte de titre en utilisant une règle de slugify ; beaucoup de parsers font de même, mais les algorithmes de slugify diffèrent. Même titre, ancre différente entre plateformes, une cause perpétuelle de liens intra-document cassés quand le contenu se déplace entre systèmes.
10. Espaces de fin et paramètres d’éditeur. Les éditeurs qui retirent les espaces de fin à la sauvegarde supprimeront silencieusement la syntaxe de saut de ligne à deux espaces de fin de Markdown. Les éditeurs qui convertissent les tabulations en espaces (ou l’inverse) casseront les blocs de code qui dépendent de l’indentation.

Markdown et sécurité, XSS et sanitization

Markdown est dangereux d’une manière spécifique : tout parser grand public passe le HTML brut à travers sans modification. C’est par conception (c’est ce qui rend Markdown utile pour des callouts et embeds codés à la main) mais cela signifie aussi qu’un previewer Markdown qui injecte la sortie du parser directement dans le DOM est, par défaut, un vecteur XSS. Coller <img src=x onerror="alert(1)"> dans un éditeur Markdown et rendre la sortie sans sanitization exécutera l’alerte. Deux couches de défense sont standard. Premièrement, configuration au niveau du parser : marked.js, markdown-it et remark exposent tous des options pour désactiver le HTML brut ou l’échapper à la sortie (markdown-it a html: false par défaut ; remark/rehype a rehype-sanitize). GFM spécifie en plus l’extension « HTML brut interdit » qui supprime une liste codée en dur d’éléments dangereux. Deuxièmement et plus robuste, sanitization HTML après parsing : DOMPurify, écrit par la firme de sécurité berlinoise Cure53 à partir de février 2014, est le sanitizer JavaScript de facto. Il prend une chaîne HTML, la parse en DOM, parcourt l’arbre en n’autorisant qu’un sous-ensemble sûr et configurable d’éléments et d’attributs, et sérialise le résultat. DOMPurify supprime <script>, bloque les gestionnaires d’événements inline, retire les URL javascript:, et gère une centaine de bypass XSS subtils (abus de SVG <use>, polyglots d’attributs MathML) qu’un sanitizer regex naïf raterait. Le pipeline recommandé pour tout previewer basé navigateur qui accepte du HTML brut est : markdownString → parser → htmlString → DOMPurify.sanitize() → innerHTML. CommonMark exige aussi explicitement que les parsers refusent les URI javascript: dans les autolinks ; la plupart des parsers étendent ce refus à toutes les formes de liens.

Markdown vs reStructuredText vs AsciiDoc

Markdown est le langage de balisage léger dominant mais pas le seul. reStructuredText (reST) a été publié pour la première fois en juin 2001 par David Goodger dans le cadre du Python Doc-SIG, évoluant à partir d’un format Zope antérieur appelé StructuredText. Il est devenu le format de documentation officiel de Python en 2002 et est le langage d’entrée de Sphinx, le générateur de documentation derrière presque toutes les docs des projets Python (les docs officielles du langage Python, NumPy, SciPy, Django, Flask, scikit-learn, pandas, la documentation du noyau Linux depuis 2016, CMake, LLVM). La philosophie de conception de RST est essentiellement l’opposé de celle de Markdown : il accepte plus de bruit visuel dans la source en échange de plus de précision sémantique en sortie. RST a un mécanisme d’extension intégré via des « directives »(.. note::, .. code-block:: python) et des « rôles » (:func:, :ref:) qui permettent à un projet de définir un balisage spécifique au domaine sans quitter le format. AsciiDoc a été créé en 2002 par Stuart Rackham comme outil Python qui cible délibérément la sémantique DocBook XML (chaque document AsciiDoc se mappe proprement à DocBook) en faisant le balisage de choix pour les projets qui ont besoin de livres de qualité publication, spécifications techniques et manuels. AsciiDoc est ce dans quoi la documentation du projet Git est écrite, ce que O’Reilly Media utilise pour beaucoup de ses livres, ce que Red Hat et Mozilla utilisent pour plusieurs ensembles de documentation produit, et ce que GitHub et GitLab supportent nativement comme alternative à README.adoc. L’implémentation Python originale a été remplacée par Asciidoctor, une implémentation Ruby publiée en 2013. Conseil pratique : choisissez Markdown pour les billets de blog, READMEs, chat, notes et la plupart de la documentation ; reStructuredText pour la documentation Python traitée par Sphinx ; AsciiDoc pour les livres ou spécifications longues qui doivent rendre vers DocBook, PDF et EPUB simultanément avec une fidélité sémantique complète.

Questions fréquentes

Quelles fonctionnalités Markdown sont prises en charge ?

Ce prévisualiseur prend en charge les titres, le gras, l'italique, les liens, les images, les listes, les citations, les blocs de code, les tableaux, les filets horizontaux et le barré. Il couvre la spécification CommonMark ainsi que des extensions courantes.

Puis-je exporter le HTML rendu ?

Vous pouvez copier la sortie rendue depuis le volet d'aperçu. Pour obtenir le HTML brut, faites un clic droit sur l'aperçu et utilisez la fonction « Inspecter » ou « Afficher la source » de votre navigateur pour copier le balisage généré.

Mon texte est-il sauvegardé ?

Non. Tout s'exécute dans votre navigateur, rien n'est stocké ni envoyé à un serveur. Fermez l'onglet et votre texte disparaît. Pensez à copier votre Markdown avant de quitter la page si vous souhaitez le conserver.

Mon texte est-il sauvegardé ou envoyé quelque part ?

Non. Le parser Markdown s’exécute entièrement dans votre navigateur via JavaScript. Rien n’est téléversé, aucune API n’est appelée, aucun log n’est écrit. Fermez l’onglet et le texte disparaît. Si vous voulez garder ce que vous avez écrit, copiez-le avant de quitter la page. Vous pouvez aussi utiliser la page hors ligne une fois qu’elle a été chargée, la mise en cache par service-worker signifie que le parser reste disponible sans connexion internet.

Le previewer assainit-il le HTML brut ?

Le parser passe le HTML brut à travers, ce qui est le comportement CommonMark standard, utile pour intégrer un occasionnel <div> ou <details>. Comme l’entrée vient de votre propre session de navigateur et que la sortie n’est rendue que dans votre propre onglet, c’est sûr pour le cas d’usage de preview à une personne pour lequel il a été construit. Si vous publiez la sortie sur un système multi-utilisateurs (un CMS, un forum, un site de documentation qui accepte des soumissions d’utilisateurs), vous devriez toujours faire passer le HTML rendu par un sanitizer comme DOMPurify avant de l’injecter dans une page publique, Markdown plus HTML brut est un vecteur XSS dans tout système où l’auteur et le lecteur sont des personnes différentes.

Y a-t-il des limites de taille de fichier ?

Aucune limite dure. Le parser gère des dizaines de milliers de lignes de Markdown sans problème sur un laptop typique. Le re-rendu en direct s’exécute à chaque frappe, donc les très gros documents (un livre entier dans un seul fichier) commenceront à sembler lents sur les appareils plus lents. Diviser en chapitres, ou coller le contenu pour rendre une fois puis éditer hors ligne, est le contournement. La page ne gèlera pas votre navigateur, marked.js est l’un des parsers Markdown les plus rapides disponibles.

Outils connexes