HTML vers Markdown (et retour) : le guide pratique pour développeurs et rédacteurs

1. Markdown vs HTML : deux philosophies, deux cas d'usage

Markdown et HTML ne sont pas en compétition : ils répondent à des besoins différents. Comprendre leurs forces et limites permet de choisir le bon format selon le contexte.

Quand utiliser Markdown :

• Documentation technique (README, wikis, API docs).
• Blogs et CMS headless (Jekyll, Hugo, Next.js, Gatsby).
• Prise de notes et PKM (Obsidian, Notion, Bear, Roam Research).
• Fichiers versionnés Git (historique lisible des diffs).

Quand rester en HTML :

• Interfaces utilisateur complexes (dashboards, SaaS).
• Emails HTML (templates marketing, newsletters).
• Layouts custom avec CSS/JS (landing pages, composants React).
• Tableaux avancés avec fusion de cellules (colspan, rowspan).

2. Les 10 syntaxes Markdown essentielles (et leurs équivalents HTML)

Markdown couvre 90% des besoins de formatage avec seulement 10 syntaxes de base. Voici la correspondance exacte avec HTML.

Élément	Markdown	HTML équivalent
Titre 1	# Titre	<h1>Titre</h1>
Titre 2	## Titre	<h2>Titre</h2>
Gras	texte	<strong>texte</strong>
Italique	texte	<em>texte</em>
Lien	texte	<a href="url">texte</a>
Image		<img src="url" alt="alt">
Liste à puces	- item	<ul><li>item</li></ul>
Liste numérotée	1. item	<ol><li>item</li></ol>
Citation	> texte	<blockquote>texte</blockquote>
Code inline	code	<code>code</code>
Bloc de code	code	<pre><code>code</code></pre>

3. Les 4 balises HTML sans équivalent Markdown natif

Markdown couvre les besoins de base, mais 4 types de contenu nécessitent du HTML brut ou des extensions (comme GitHub Flavored Markdown). Connaître ces limites évite les mauvaises surprises lors de migrations.

1. Tableaux complexes (<table> avec colspan/rowspan)

Markdown supporte des tableaux simples (lignes + colonnes), mais pas les fusions de cellules :

| Colonne 1 | Colonne 2 |
|-----------|-----------|
| Valeur A  | Valeur B  |

Pour un tableau avec colspan (fusion horizontale) ou rowspan (fusion verticale), vous devez utiliser HTML brut :

<table>
  <tr>
    <td colspan="2">Cellule fusionnée</td>
  </tr>
</table>

2. Éléments interactifs (<details>, <summary>)

Les accordéons HTML (<details>) ne sont pas supportés en Markdown pur. GitHub Flavored Markdown (GFM) les autorise :

<details>
  <summary>Cliquez pour déplier</summary>
  Contenu masqué par défaut.
</details>

3. Iframes et embeds (<iframe>, <video>)

Les embeds YouTube, Vimeo, tweets, ou vidéos nécessitent HTML :

<iframe src="https://www.youtube.com/embed/VIDEO_ID"></iframe>

4. Formulaires (<form>, <input>, <button>)

Markdown est orienté contenu statique. Tout formulaire interactif requiert HTML + JavaScript.

| Fonctionnalité | Markdown pur | GitHub Flavored Markdown (GFM) | HTML requis | |----------------|--------------|-------------------------------|-------------| | Tableaux simples | ✅ Supporté | ✅ Supporté | ❌ | | Tableaux avec colspan | ❌ Non supporté | ❌ Non supporté | ✅ Obligatoire | | Task lists (- [ ]) | ❌ Non supporté | ✅ Supporté | ❌ | | Strikethrough (~~texte~~) | ❌ Non supporté | ✅ Supporté | ❌ | | Accordéons <details> | ❌ Non supporté | ✅ Supporté | ✅ Recommandé | | Iframes/Embeds | ❌ Non supporté | ❌ Non supporté | ✅ Obligatoire |

4. Les 3 cas d'usage principaux de la conversion HTML → Markdown

La conversion HTML vers Markdown est cruciale dans 3 scénarios de migration technique. Comprendre ces use cases permet de choisir les bons outils et d'anticiper les pièges.

Use Case 1 : Migration WordPress → Jamstack (Jekyll, Hugo, Next.js)

Contexte : Vous migrez un blog WordPress (HTML/PHP/MySQL) vers un Static Site Generator (SSG) qui utilise Markdown.

Workflow :

1. Exporter les posts WordPress en HTML (via plugin ou API).
2. Convertir HTML → Markdown (automatisé avec pandoc ou script custom).
3. Nettoyer le Markdown (supprimer les shortcodes WordPress, classes CSS inline).
4. Importer les fichiers .md dans votre SSG (dossier content/).

Pièges courants :

• Les shortcodes WordPress ([gallery], [contact-form]) ne sont pas convertis automatiquement.
• Les images hébergées sur WordPress doivent être migrées (chemins relatifs à corriger).
• Les Custom Post Types nécessitent un mapping manuel vers la structure Markdown.

Use Case 2 : Export de documentation Notion/Confluence → GitHub/GitLab

Contexte : Votre équipe rédige la documentation dans Notion/Confluence (interface WYSIWYG), mais vous voulez la versionner dans Git (format Markdown).

Workflow :

1. Exporter la page Notion en HTML (option native).
2. Convertir HTML → Markdown avec un outil (Pandoc, Turndown.js).
3. Commit dans le repo Git (docs/ ou wiki GitHub).
4. Automatiser avec un workflow CI/CD (sync périodique Notion → Git).

Avantages :

• Historique versionné des modifications (Git blame, diffs lisibles).
• Code review de la documentation (Pull Requests).
• Intégration avec CI/CD (déploiement auto vers site statique).

Use Case 3 : Nettoyage de contenu copié depuis Word/Google Docs

Contexte : Vous copiez-collez du contenu depuis Word ou Google Docs dans un CMS headless (Strapi, Contentful) qui accepte du Markdown.

Problème : Le copier-coller injecte du HTML pollué (classes inline, styles <span>, espaces insécables, balises vides).

Solution :

1. Coller le contenu dans un éditeur HTML.
2. Convertir HTML → Markdown (le convertisseur nettoie automatiquement les balises parasites).
3. Obtenir un Markdown propre sans pollution visuelle.

5. Checklist de conversion : valider la qualité HTML → Markdown

Après une conversion automatique HTML → Markdown, validez ces 8 points critiques pour garantir un résultat propre et exploitable.

1. Titres (H1-H6) :

• ✅ Les niveaux de titre sont respectés (#, ##, ###) ?
• ✅ Pas de sauts de niveau (H1 → H3 sans H2) ?

2. Liens et images :

• ✅ Les URLs sont correctes (pas de chemins absolus cassés) ?
• ✅ Les attributs alt des images sont préservés ?

3. Listes :

• ✅ Les listes imbriquées sont correctement indentées (2 ou 4 espaces) ?
• ✅ Pas de mélange puces (-) et numéros (1.) dans la même liste ?

4. Code :

• ✅ Les blocs de code ont le bon langage ( ```js, ```python) ?
• ✅ Les caractères spéciaux dans le code sont échappés si nécessaire ?

5. Tableaux :

• ✅ Les tableaux simples sont convertis en syntaxe Markdown ?
• ✅ Les tableaux complexes (colspan) sont laissés en HTML brut ?

6. Formatage inline :

• ✅ Pas de <span> ou <div> vides résiduels ?
• ✅ Le gras (**) et l'italique (*) sont bien convertis ?

7. Caractères spéciaux :

• ✅ Les entités HTML ( , <, >) sont décodées ou échappées ?
• ✅ Pas de caractères invisibles (U+200B, U+00A0) ?

8. Lisibilité brute :

• ✅ Le fichier Markdown est lisible sans rendu (test : ouvrir dans VSCode) ?
• ✅ Les lignes ne dépassent pas 120 caractères (recommandé pour Git diffs) ?

En 2026, la conversion HTML ↔ Markdown n'est plus un luxe mais une compétence technique de base pour tout développeur ou rédacteur travaillant dans l'écosystème moderne (Jamstack, Git-based CMS, documentation-as-code). Maîtriser les limites de Markdown (tableaux complexes, iframes, formulaires) et savoir quand basculer en HTML brut est la clé pour maintenir des contenus propres, versionnés et maintenables sur le long terme.