Convertisseur HTML en Markdown

Qu'est-ce que la conversion HTML en Markdown ?

La conversion HTML en Markdown transforme le balisage HTML en Markdown, une syntaxe de formatage en texte brut légère créée par John Gruber en 2004. Markdown a été conçu pour être lisible sans rendu. Là où HTML nécessite des balises ouvrantes et fermantes comme <strong> et <a href="">, Markdown utilise des caractères abrégés : **gras**, [liens](url) et # titres. Convertir du HTML en Markdown produit des fichiers plus faciles à lire, modifier et versionner que le HTML brut.

Le processus de conversion mappe les éléments HTML à leurs équivalents Markdown. Un <h2> devient ##, un <ul><li> devient - élément, et une balise <a> devient [texte](url). Certains éléments HTML n'ont pas d'équivalent Markdown direct, comme <div>, <span> ou les attributs data personnalisés. Les convertisseurs suppriment généralement ces balises ou les transmettent telles quelles en HTML brut, selon la configuration.

Markdown est devenu le format d'écriture standard pour la documentation développeur (GitHub, GitLab, Bitbucket), les générateurs de sites statiques (Hugo, Jekyll, Astro), les applications de prise de notes (Obsidian, Notion) et les blogs techniques. Convertir du contenu HTML existant en Markdown est une étape courante lors de la migration de sites web, de l'importation de contenu CMS ou de l'archivage de pages web dans un format portable. Contrairement au HTML, les fichiers Markdown produisent des diffs propres dans le contrôle de version, ce qui rend pratique la revue de code des modifications de documentation.

Pourquoi utiliser un convertisseur HTML en Markdown ?

Réécrire manuellement du HTML en Markdown est lent et source d'erreurs, surtout pour des pages avec des listes imbriquées, des tableaux ou des dizaines de liens. Un convertisseur automatisé gère le mapping structurel instantanément et de façon cohérente.

Cas d'utilisation du convertisseur HTML en Markdown

Référence des éléments HTML en Markdown

Le tableau ci-dessous montre comment les éléments HTML courants se mappent à leurs équivalents Markdown. Ce mapping suit les conventions GitHub-Flavored Markdown (GFM), qui étendent la spécification CommonMark avec des tableaux, le barré et les listes de tâches. Les éléments non listés ici (comme <div>, <form> ou les web components personnalisés) n'ont pas d'équivalent Markdown et sont soit supprimés, soit transmis tels quels en HTML brut.

Variantes Markdown : GFM vs CommonMark vs Original

Tous les Markdown ne sont pas identiques. Le format de sortie importe car les différentes plateformes analysent Markdown différemment. Les trois variantes les plus courantes sont GitHub-Flavored Markdown (GFM), CommonMark et le Markdown original de Gruber.

Exemples de code

Exemples fonctionnels en JavaScript (Turndown), Python (markdownify et html2text), Go et Pandoc en ligne de commande.

import TurndownService from 'turndown'

const turndown = new TurndownService({ headingStyle: 'atx' })
const html = '<h1>Title</h1><p>A <strong>bold</strong> paragraph.</p>'
const md = turndown.turndown(html)
console.log(md)
// → "# Title\n\nA **bold** paragraph."

from markdownify import markdownify

html = '<h2>Section</h2><ul><li>First</li><li>Second</li></ul>'
md = markdownify(html, heading_style='ATX')
print(md)
# → "## Section\n\n- First\n- Second"

import html2text

converter = html2text.HTML2Text()
converter.body_width = 0  # disable line wrapping

html = '<p>Visit <a href="https://example.com">Example</a> for details.</p>'
md = converter.handle(html)
print(md)
# → "Visit [Example](https://example.com) for details."

package main

import (
	"fmt"
	md "github.com/JohannesKaufmann/html-to-markdown"
)

func main() {
	converter := md.NewConverter("", true, nil)
	html := `<h3>Go Example</h3><p>Code: <code>fmt.Println()</code></p>`
	markdown, _ := converter.ConvertString(html)
	fmt.Println(markdown)
	// → "### Go Example\n\nCode: `fmt.Println()`"
}

# Convert an HTML file to Markdown
pandoc input.html -f html -t markdown -o output.md

# Pipe HTML from stdin
echo '<p>Hello <em>world</em></p>' | pandoc -f html -t markdown
# → Hello *world*

# Use GitHub-Flavored Markdown output
pandoc input.html -f html -t gfm -o output.md

Questions fréquentes