Markdown vs HTML Quand utiliser chacun pour les documents, les README et les API

Qu'est-ce que le Markdown en réalité

Markdown est un langage de mise en forme léger — vous écrivez du texte simple en utilisant des conventions simples (astérisques pour le gras, hashtags pour les titres, backticks pour le code), puis un parser le convertit en HTML. Il n'existe pas de standard officiel unique de Markdown ; ce que vous obtenez dépend du parser que vous utilisez.

Les variantes les plus courantes :

• CommonMark — un standard strict et bien spécifié. La version la plus proche de « Markdown pur ».
• GitHub Flavored Markdown (GFM) — CommonMark augmenté de tables, de listes de tâches, de soulignement, et de liens automatiques. Ce que GitHub et GitLab affichent.
• kramdown, Pandoc, MultiMarkdown — des variantes étendues avec des notes, des listes de définitions et des attributs personnalisés non présents dans CommonMark.

Si vous écrivez un README et que vous attendez que GitHub l'affiche, GFM est votre spécification. Si vous utilisez un générateur de site statique, vérifiez quel parser il utilise — ils divergent sur des cas limites comme les listes imbriquées ou le traitement du HTML brut.

Quand Markdown l'emporte

Les README et les documents de développement. Markdown est le format par défaut pour les documents de développement. GitHub, GitLab, Bitbucket, npm, PyPI — tous les affichent nativement. Écrire un README en HTML serait techniquement valide, mais pratiquement hostile aux contributeurs qui doivent l'écrire.

Les wikis et les journaux de changements. Des fichiers de texte simples, contrôlés par la version, que les humains éditent et où les différences doivent être lisibles. L'HTML est verbeux et crée des différences sans sens. Le Markdown reste propre.

Les sites de documentation. Des outils comme MkDocs, Docusaurus, Hugo et Jekyll prennent des fichiers Markdown et génèrent de l'HTML au moment de la construction. L'auteur écrit en Markdown ; le site gère la présentation.

Quand le contenu est écrit par des non-développeurs. Markdown est bien plus facile à apprendre et à écrire que l'HTML. Si votre pipeline de contenu inclut des auteurs qui ne sont pas des ingénieurs frontend, Markdown réduit considérablement les friction.

Quand l'HTML l'emporte

Les emails. Les clients d'email — en particulier Outlook — ont une prise en charge incohérente du CSS. L'HTML vous donne un contrôle explicite sur l'arrangement, les tailles de police, les espaces et les styles inline. Les emails générés à partir de Markdown peuvent se dégrader dans des clients qui suppriment certains tags ou qui ne supportent pas la sortie du parser.

Un contrôle précis de l'arrangement et du style. Quand vous avez besoin de largeurs de colonnes précises, d'arrangements flottants ou de classes CSS personnalisées, Markdown vous empêche de faire ce travail. Vous devez soit mélanger du HTML brut, soit lutter contre le résultat du parser.

Des tables complexes. Les tables GFM fonctionnent pour des grilles simples. Dès que vous avez besoin de cellules fusionnées, de contenu multi-lignes dans une cellule ou de colonnes qui s'étendent, la syntaxe Markdown échoue. HTML <table> est l'outil idéal.

Le contenu géré par un CMS. La plupart des plateformes de gestion de contenu stockent le contenu des articles en HTML ou utilisent un éditeur à blocs qui produit un HTML structuré. Forcer le Markdown dans ce pipeline ajoute une couche de conversion sans bénéfice clair, sauf si le CMS a été spécifiquement conçu pour cela.

Comparaison rapide

Cas d'utilisation	Réduction	HTML	Gagnant
README de GitHub	Support natif	Verbeux, peu convivial	Réduction
Modèle d'email	Incohérent	Contrôle complet	HTML
Site de documentation	Support natif avec des SSG	Requiert une étape de build	Réduction
Tables complexes	Limité	Contrôle complet	HTML
Corps de réponse d'API	Modèle courant	Fonctionne mais verbeux	Réduction
Contenu du CMS	Conversion nécessaire	Natif	HTML
Journaux de changements	Différences claires	Trop compliqué	Réduction

GFM : Ce qu'il ajoute par rapport à CommonMark

GitHub Flavored Markdown ajoute à CommonMark des fonctionnalités que les développeurs utilisent fréquemment. Voici un exemple rapide d'une table GFM et d'une liste de tâches — deux fonctionnalités absentes de CommonMark :

## GFM Table
| Name     | Role     | Status  |
|----------|----------|---------|
| Alice    | Author   | Active  |
| Bob      | Reviewer | Pending |

## GFM Task List
- [x] Write draft
- [x] Add code examples
- [ ] CMO review
- [ ] Schedule publish

Aucune de ces fonctionnalités n'est rendue par un parser pur CommonMark. Si votre outil de documentation utilise CommonMark sans extensions, ces blocs apparaîtront comme du texte brut. Vérifiez toujours que votre syntaxe correspond à votre parser.

Mélanger Markdown et HTML

La plupart des parsers de Markdown permettent l'insertion de HTML brut. CommonMark l'autorise par défaut, GFM l'autorise aussi, avec une certaine sécurisation. Cela signifie que vous pouvez insérer <div> ou <table> dans un fichier Markdown quand vous avez besoin d'exprimer quelque chose que la syntaxe ne peut pas faire.

Ce qui se casse généralement : l'insertion de Markdown dans des blocs HTML. Si vous ouvrez un <div> et que vous écrivez du Markdown à l'intérieur, la plupart des parsers ne traiteront pas le Markdown — ils le considéreront comme du HTML brut. Si vous avez besoin de contenu Markdown à l'intérieur d'un bloc HTML, vous devez que le parser le supporte explicitement (kramdown dispose d'un attribut markdown="1" pour cela ; la plupart des autres ne le font pas).

Règle de base : utilisez les blocs HTML avec parcimonie pour des overrides structurels. N'essayez pas d'écrire des sections entières en HTML dans un fichier Markdown — à ce moment-là, écrivez simplement en HTML.

Markdown dans les corps de réponse d'API

Un modèle courant et pratique : les API retournent des chaînes de Markdown dans des champs de réponse. L'API de rich text de Notion, le block kit de Slack, ainsi que diverses API de services d'aide et de CMS envoient du contenu Markdown que le client doit afficher.

Pourquoi ? Le Markdown est compact, lisible par l'humain et convivial dans les éditeurs. Stocker **bold text** est plus économique et plus clair que de stocker <strong>bold text</strong>, et il maintient la forme du données indépendante de toute structure HTML particulière. Si vous concevez une API qui retourne du contenu lisible par l'humain, un Markdown dans des champs de chaîne est une option raisonnable par défaut — tout simplement, documentez le variant que vous utilisez.

Affichage sécurisé du Markdown

Afficher du Markdown fourni par l'utilisateur directement sur le frontend sans le nettoyer est un vecteur d'XSS. Un parser de Markdown qui prend en charge le HTML brut transmettra librement <script>alert('xss')</script> intégré dans le contenu utilisateur.

La solution : nettoyer l'HTML de sortie, pas l'entrée Markdown. Des bibliothèques comme DOMPurify (navigateur), sanitize-html (Node.js) ou Bleach (Python) suppriment les balises et attributs dangereux du HTML rendu tout en conservant le format sécurisé. N'affichez jamais du Markdown non fiable directement dans le DOM sans passer par un nettoyage. Le parser n'est pas votre couche de sécurité.

Testez-le dans le navigateur

Si vous souhaitez expérimenter l'affichage du Markdown — tester la syntaxe GFM, prévisualiser comment les tables et les listes de tâches apparaissent, ou vérifier le comportement du HTML brut dans le Markdown — l'éditeur Markdown IO Tools fonctionne dans le navigateur sans installation. C'est un éditeur rapide de Markdown en ligne, idéal pour rédiger des documents, prévisualiser des fichiers README ou tester le comportement du parser avant de choisir un format.

Vous aimerez peut-être aussi