Convertir du Markdown en HTML

Un fragment ou une page : lequel vous faut-il ?

Il existe deux résultats utiles, et ils ne sont pas interchangeables. Un fragment ne contient que le balisage converti — titres, paragraphes, listes, liens — sans enveloppe de document : c'est ce qu'il vous faut quand le résultat va dans un modèle, un champ de CMS ou une autre page. Une page complète ajoute le doctype, un en-tête, une déclaration de jeu de caractères et une feuille de style, pour s'ouvrir seule et avoir de l'allure. Coller une page complète dans un CMS donne un document dans un document ; ouvrir un fragment dans un navigateur donne du texte sans mise en forme.

La conversion couvre l'ensemble étendu de Markdown qui fait consensus : titres, emphase, listes, liens, images, citations, tableaux, blocs de code délimités avec coloration syntaxique, listes de tâches, texte barré et notes de bas de page. Les titres reçoivent des identifiants tirés de leur texte, ce qui permet d'y faire un lien direct — ces ancres qui rendent une longue documentation utilisable.

Le HTML brut présent dans le Markdown est transmis tel quel, ce qui fait partie de la spécification et mérite d'être pris au sérieux : un fichier Markdown d'origine douteuse peut contenir une balise script, et le convertir produit une page qui embarque ce script. N'affichez jamais le Markdown d'inconnus sans nettoyer le HTML ensuite — la conversion n'est pas une barrière de sécurité et n'a jamais été conçue comme telle.

Deux éléments sont volontairement restitués sous forme de blocs de code plutôt qu'affichés. Les formules mathématiques en notation LaTeX exigent une bibliothèque de composition, et les diagrammes Mermaid un moteur de rendu de diagrammes — chacun est une dépendance lourde, et une équation mal rendue est pire qu'une équation visible telle quelle. Une page complète utilise les polices système ordinaires au lieu d'en télécharger, elle fonctionne donc hors ligne et s'affiche légèrement différemment sous Windows, macOS et Linux.

Si vous cherchez autre chose

Pandoc gère ce qui est laissé de côté ici, et bien plus encore : pandoc in.md -o out.html --mathjax --standalone --toc affiche correctement les formules, génère une table des matières et accepte un modèle pour que le résultat corresponde à votre site. Il convertit aussi depuis et vers une quarantaine d'autres formats, ce qui justifie de l'installer une bonne fois pour toutes.

Pour un site web plutôt qu'un fichier, utilisez un générateur au lieu de convertir les pages une à une. Hugo, Eleventy, Jekyll et MkDocs transforment un dossier de Markdown en site avec navigation, recherche et mise en forme cohérente, et le reconstruisent à chaque modification de la source — ce qui est le vrai travail dès qu'il y a plus d'un document.