HTML to markdown converter : comprendre la conversion entre langages de balisage
HTML et Markdown : deux approches du formatage de texte
Le HTML (HyperText Markup Language) et le Markdown sont deux langages de balisage qui servent des objectifs complémentaires. Le HTML, standardisé par le W3C et le WHATWG, est le langage natif du web : il permet de structurer et présenter du contenu dans un navigateur avec un contrôle total sur la mise en page, les styles et l'interactivité. Le Markdown, créé par John Gruber en 2004, est un langage léger conçu pour être lisible tel quel, sans outil de rendu.
La conversion de HTML vers Markdown est utile dans de nombreux contextes : migration de contenu d'un CMS WordPress vers un CMS headless (Contentful, Strapi, Sanity), création de README GitHub à partir de pages web, simplification de code HTML copié depuis un éditeur WYSIWYG, ou archivage de contenu dans un format portable et lisible.
HTML
<strong>
Balisage verbeux, contrôle total
Markdown
**texte**
Syntaxe concise, lisible en brut
Correspondance des éléments HTML et Markdown
La majorité des éléments HTML courants ont un équivalent direct en Markdown. Cependant, le Markdown est volontairement limité : il ne couvre que les éléments de structuration de texte les plus communs.
Couverture de conversion HTML vers Markdown
Éléments supportés par le standard CommonMark
CommonMark vs GitHub Flavored Markdown (GFM)
Le CommonMark est la spécification formelle du Markdown standard, publiée pour résoudre les ambiguïtés de la spécification originale de Gruber. GitHub Flavored Markdown (GFM) étend CommonMark avec des fonctionnalités supplémentaires : tableaux, cases à cocher (task lists), blocs de code avec coloration syntaxique, barré (strikethrough) et autolinks. Notre convertisseur produit du Markdown compatible CommonMark, qui fonctionne dans les deux contextes.
<table>, la conversion nécessite GFM ou un post-traitement manuel. Les styles CSS inline et les classes sont toujours ignorés lors de la conversion.Exemple illustré : migrer du contenu WordPress
Prenons le cas d'une migration de blog WordPress vers un CMS headless utilisant le Markdown.
Copier le contenu HTML de l'éditeur WordPress
<h2>Mon article</h2><p>Texte avec <strong>gras</strong>...</p> Notre outil transforme les balises en syntaxe Markdown
## Mon article\nTexte avec **gras**... Coller le Markdown dans le nouvel éditeur
Contentful / Strapi / Sanity 2004
Année de création du Markdown par John Gruber, devenu le standard de facto pour la documentation technique
Cas d'usage courants
La conversion HTML vers Markdown est particulièrement utile pour les README GitHub (transformer une page de documentation web en fichier .md), la documentation technique (Docusaurus, VitePress, MkDocs utilisent tous le Markdown), l'archivage de contenu (le Markdown est pérenne, portable et lisible sans logiciel spécifique), et les éditeurs de notes comme Obsidian et Notion. Pour vérifier l'intégrité de vos fichiers Markdown exportés, utilisez notre générateur de hash SHA.
Bonne pratique
Limitations de la conversion
Certains éléments HTML ne peuvent pas être fidèlement convertis en Markdown. Les tableaux complexes (cellules fusionnées, thead/tbody) nécessitent GFM ou du HTML inline dans le Markdown. Les styles CSS (couleurs, tailles, marges) sont perdus car le Markdown sépare strictement le contenu de la présentation. Les formulaires, scripts et éléments interactifs n'ont aucun équivalent. Les attributs HTML (id, class, data-*) sont supprimés.
HTML dans le Markdown
Erreurs fréquentes à éviter
- Convertir sans vérifier le résultat. La conversion automatique est une base, pas un produit fini. Les tableaux, styles et éléments complexes nécessitent toujours une relecture manuelle.
- Perdre les images lors de la migration. La conversion transforme les balises
<img>en syntaxe Markdown, mais les URLs des images doivent rester accessibles. Vérifiez que les liens pointent vers des URLs absolues. - Confondre CommonMark et les extensions. Si vous utilisez des fonctionnalités GFM (tableaux, cases à cocher), assurez-vous que votre renderer les supporte. Un renderer CommonMark strict affichera les tableaux en texte brut.
- Ignorer l'encodage des caractères spéciaux. Les entités HTML (&, <, >) doivent être décodées en caractères normaux dans le Markdown. Notre convertisseur gère les entités courantes automatiquement.
- Copier du HTML depuis un éditeur WYSIWYG sans nettoyer. Les éditeurs comme Word ou Google Docs génèrent un HTML bourré de styles inline et de balises superflues. Nettoyez d'abord avec un outil de strip HTML avant de convertir.
Sources et références
- CommonMark Spec : spécification formelle du Markdown standard.
- GitHub Flavored Markdown Spec : extensions GFM.
- MDN Web Docs, HTML : référence HTML complète.
- Markdown: Syntax (Gruber, 2004) : spécification originale.