Markdown vs HTML : quand choisir l'un ou l'autre

En bref.Markdown est un format source convivial pour l’auteur qui se compile en HTML. HTML est la cible de rendu que tout navigateur, client de messagerie et CMS consomme en fin de compte. Rédigez en Markdown pour la prose ; basculez en HTML en ligne pour les mises en page complexes, les formulaires et les éléments interactifs.

Markdown et HTML sont souvent présentés comme des alternatives. Ils ne le sont pas. Markdown est un format source convivial qui se compile en HTML. HTML est le format universel de rendu de documents que les navigateurs, les clients de messagerie et la plupart des générateurs de sites statiques consomment en fin de compte. La question n’est pas de choisir l’un ou l’autre — c’est de savoir dans lequel vous devriez écrire.

Les différences essentielles

Quand Markdown l’emporte

• Fichiers README, documentation, articles de blog. Tout l’intérêt. Lisible en cours d’écriture, sans bruit de balises, diffs propres en contrôle de version.
• Commentaires, tickets, messages de chat. GitHub, Discord, Slack et tout outil de collaboration moderne acceptent Markdown. Gras, liens, blocs de code, listes — universel.
• Générateurs de sites statiques. Hugo, Jekyll, Next.js MDX — tout moteur de blog moderne prend Markdown en entrée.
• Partout où la prose domine. Markdown est optimisé pour le texte avec une mise en forme occasionnelle — exactement le ratio dont les auteurs ont besoin.

Quand HTML l’emporte

• Tout ce qui implique une mise en page complexe. Multi-colonnes, tableaux avec styles au niveau des cellules, positionnement personnalisé. Markdown ne peut pas exprimer ce que CSS attend.
• Pages web en production. Le navigateur ne rend que du HTML. Même quand votre source est en Markdown, la page déployée est en HTML.
• E-mail. La plupart des clients de messagerie rendent le HTML ; très peu rendent directement le Markdown. Les e-mails marketing utilisent HTML + styles en ligne car les clients de messagerie massacrent tout ce qui est plus sophistiqué.
• Éléments interactifs. Formulaires, scripts, iframes, attributs d’accessibilité (aria-*, role) — territoire exclusif d’HTML.

Le problème des dialectes

“Markdown” n’est pas une seule spécification. Plusieurs dialectes incompatibles existent :

• CommonMark(2014, en cours) — l’effort de standardisation. Strict et prévisible. La base à laquelle la plupart des analyseurs modernes se conforment.
• GitHub Flavored Markdown (GFM) — CommonMark plus tableaux, barré, listes de tâches, liens automatiques. La norme de facto pour la documentation développeur.
• Pandoc Markdown — étendu pour un usage académique et les ouvrages longs : notes de bas de page, citations, listes de définitions, maths via LaTeX.
• Markdown original de John Gruber (2004) — sous-spécifié par endroits. Différents analyseurs gèrent les cas limites différemment.

Si la portabilité est importante, rédigez en CommonMark et évitez les extensions spécifiques à un dialecte.

HTML dans Markdown

La plupart des analyseurs Markdown vous permettent d’insérer du HTML brut en ligne quand Markdown n’est pas assez expressif. C’est la soupape pragmatique — gardez 95 % de votre document en Markdown, basculez en HTML pour le tableau qui nécessite des colspan, l’iframe intégrant une vidéo, le formulaire.

Certains analyseurs (celui de StackOverflow, par exemple) suppriment la majeure partie du HTML pour des raisons de sécurité. Vérifiez le contexte de rendu avant d’en dépendre.

La règle pragmatique

• Écriture : Markdown. Commencez toujours en Markdown.
• Lecture : HTML. Le navigateur/messagerie rend la sortie HTML de votre Markdown.
• Cas limites : basculez en HTML en ligne si nécessaire.
• E-mail marketing, mises en page complexes, web en production : HTML directement.

Chiffres clés

• Longueur de la spécification Markdown : CommonMark 0.31 représente ~70 pages imprimées ; le WHATWG HTML Living Standard en compte plus de 1 400.
• Ratio de frappes : pour un article type de 500 mots avec 6 liens et 3 titres, la source Markdown représente ~620 caractères contre ~1 050 pour l’HTML équivalent — soit environ 40 % de frappes en moins.
• Vitesse d’analyse : markdown-it analyse ~150 Mo/s de CommonMark sur un ordinateur portable 2024 ; les analyseurs HTML modernes (lxml, html5ever) atteignent 200 à 400 Mo/s. Les deux sont suffisamment rapides pour que l’analyse ne soit jamais le goulot d’étranglement.
• Support des tableaux GFM : GitHub Flavored Markdown limite les tableaux à 64 colonnes ; la spécification CommonMark n’a pas du tout de syntaxe native pour les tableaux.
• Signal d’adoption : ~99 % des fichiers README sur GitHub sont en Markdown (GitHub indique que le nombre dépasse 280 millions de fichiers).

Matrice de décision côte à côte

Où se cachent les pièges

Trois modes d’échec reviennent fréquemment dans les équipes adoptant Markdown pour leurs pipelines de documentation :

• Paragraphes avec retour à la ligne forcé vs souple. CommonMark traite un seul saut de ligne dans un paragraphe comme un espace ; GFM suit la même règle, mais certains anciens analyseurs (vieux RedCarpet, Pandoc vintage) le traitent comme un <br> littéral. La solution : ne jamais forcer un retour à la ligne dans un paragraphe sauf si vous voulez un saut de ligne.
• Réécriture des guillemets typographiques. Pandoc, Hugo et certains plugins Jekyll réécrivent silencieusement les guillemets droits en guillemets typographiques courbes — parfait pour la prose, catastrophique dans un exemple de code non clôturé. Utilisez toujours des blocs de code clôturés (triple backtick) pour tout ce qui contient des guillemets.
• Indentation des listes.CommonMark exige que les éléments de liste imbriqués soient indentés de 2 ou 4 espaces (correspondant au décalage du marqueur de l’élément parent). Les tabulations sont rendues différemment selon les analyseurs ; ne mélangez jamais tabulations et espaces dans la même liste.

Sources

• CommonMark Specification 0.31.2 — spec.commonmark.org (grammaire Markdown de référence).
• WHATWG HTML Living Standard — html.spec.whatwg.org (référence HTML faisant autorité).
• GitHub Flavored Markdown Spec — github.github.com/gfm (sur-ensemble CommonMark utilisé par GitHub).