Je migre du contenu pour gagner ma vie, dans le sens où quiconque dirige un site WordPress depuis une décennie finit par le faire Quand j'ai déplacé un lot de vieux messages d'un constructeur de pages et dans un système docs basé sur Markdown, j'ai découvert ce que " ; HTML" propre ; signifie vraiment dans la nature : <p> tags avec styles en ligne, vide <span>s enveloppant des mots simples, <div>s trois niveaux profondément autour d'un paragraphe, et l'étiquette occasionnelle qui n'a tout simplement jamais été fermée Coller cela dans un champ Markdown m'a donné un mur de crochets d'angle littéraux Copier-coller le rendu le texte a perdu chaque lien, titre et liste Aucun des deux raccourcis n'a fonctionné, et j'ai fini par nettoyer les articles à la main pendant un après-midi avant de faire preuve de sens à ce sujet.
Devenir raisonnable signifiait traiter HTML-to-Markdown comme ce qu'il est : une transformation structurée avec un ensemble clair de règles, pas un copier-coller Un élément de titre devient un # ligne. Le gras devient **. Un lien devient [text](url). Une table devient une table de tuyaux Une fois que vous avez ces mappages et un analyseur assez tolérant pour survivre au balisage du monde réel, la conversion est ennuyeuse et fiable - ce qui est exactement ce que vous voulez Je construis [Toolz.dev] (/et mets un navigateur-based convertisseur HTML à Markdown là, cela applique ces règles, mais ce guide concerne les règles elles-mêmes afin que vous compreniez à quoi devrait ressembler le résultat et pourquoi.
tl;dr : Pour convertir HTML en Markdown, mappez les éléments de bloc à leurs équivalents Markdown (
<h2>→##,<ul><li>→-,<blockquote>→>,<pre><code>→ un bloc clôturé), éléments en ligne de la carte (<strong>→**,<em>→*,<a>→[text](href),<img>→), tourne<table>dans une table de canalisations GitHub Flavored Markdown, décodez les entités HTML en caractères réels et déposez-les<script>/<style>. Utilisez un analyseur tolérant les balises non fermées et faites-le dans le navigateur afin que votre contenu ne soit jamais téléchargé.
Pourquoi convertir HTML en Markdown ?
Markdown est le format portable du Web des développeurs modernes. Les fichiers README, les sites de documentation, les blogs statiques (contenu Hugo, Jekyll, Astro, Next.js), les applications de notes comme Obsidian et Bear, les problèmes GitHub et, de plus en plus, les invites et le contexte que nous alimentons aux modèles d'IA - tous parlent Markdown. It' ; est en texte brut, il se diffuse proprement dans Git et survit en étant déplacé d'un système à un autre sans entraîner une pile de balisage de présentation avec lui.
HTML, en revanche, est ce que vous finir avec chaque fois que le contenu passe par un navigateur ou un éditeur WYSIWYG. Copiez une section d'une page Web, exportez depuis un CMS, retirez le corps d'un article d'une API ou récupérez du texte formaté à partir d'un champ de texte enrichi, et vous obtenez HTML - généralement du HTML encombré, plein d'éléments d'emballage et de styles en ligne que vous ne souhaitez pas. ' ; la conversion est le pont de " ; contenu piégé dans le balisage et le devis de présentation ; à " ; contenu Je peux version, modifier et republier n'importe où." ;
Les scénarios reviennent constamment une fois que vous les remarquez Migration d'un blog hors WordPress ou Medium Sortir la documentation d'un système d'aide HTML hérité Tourner un article gratté dans une note de Markdown Convertir un bulletin d'information par courriel' ; s HTML en brouillon de Markdown Alimenter une page Web' ; s contenu en LLM comme contexte propre au lieu de HTML brut qui gaspille des jetons sur <div> soupe. Dans tous les cas, les alternatives manuelles - retaper ou coller du texte rendu et reconstruire le formatage à la main - sont lentes et avec perte. Un convertisseur basé sur des règles n’est ni l’un ni l’autre.
Comment le HTML est-il mappé au Markdown ?
Le mappage se divise naturellement en deux couches : la structure au niveau du bloc et le formatage en ligne.
Éléments de bloc définissez le squelette document' ;s, et chacun a une contrepartie directe Markdown :
<h1>–<h6>devenir#par######lignes de cap.<p>devient un paragraphe séparé par des lignes blanches.<ul>/<li>devenir-listes à puces ;<ol>/<li>devenir1.les listes numérotées et les listes imbriquées s'indentent par deux espaces.<blockquote>préfixe chaque ligne avec>.<hr>se transforme---.<pre><code>devient un bloc de code clôturé avec des backticks triples.<table>devient une table à tuyaux GitHub Flavored Markdown.
Éléments en ligne décorez le texte dans ces blocs :
<strong>et<b>devenir**bold**.<em>et<i>devenir*italic*.<code>se transforme`inline code`.<a href="...">se transforme[link text](href): garder letitleattribut lorsqu'il est présent.<img>se transforme.<del>et<s>devenir~~strikethrough~~(une extension GitHub Flavored Markdown).<br>devient une rupture de ligne dure - deux espaces arrière avant la nouvelle ligne.
Exécutez ces règles sur un bloc réel de HTML et la structure survit intacte Compte tenu de cette entrée :
<article>
<h1>Getting Started</h1>
<p>Convert <strong>HTML</strong> into clean <em>Markdown</em>.</p>
<ul>
<li>Paste from a CMS</li>
<li>Get portable output</li>
</ul>
<pre><code class="language-js">const md = convert(html)</code></pre>
</article>
vous obtenez:
# Getting Started
Convert **HTML** into clean *Markdown*.
- Paste from a CMS
- Get portable output
```js
const md = convert(html)
```
Deux détails dans cette sortie méritent d’être appelés. Premièrement, le <article> wrapper n'a rien apporté - des conteneurs structurels comme <article>, <section>, et <div> sont transparents ; le convertisseur y revient et rend leurs enfants sous forme de blocs. Deuxièmement, la clôture de code a été récupérée js comme langue. Que' ;s parce que le <code> élément porté class="language-js"[traduction], les surligneurs de syntaxe de convention utilisent, et un bon convertisseur lit cette classe pour étiqueter la clôture It' ; est une petite chose qui fait la différence entre un bloc de code qui met en évidence sur votre site docs et un autre qui fait ' ; t.
Qu'est-ce qui fait qu'un convertisseur survit au HTML réel ?
Les règles ci-dessus sont la partie facile La raison pour laquelle les convertisseurs regex roulés à la main échouent - et I' ; ont écrit et jeté quelques - est que le vrai HTML brise constamment les hypothèses Trois problèmes reviennent encore et encore.
Tags non fermés. Les navigateurs pardonnent : <p>one<p>two rend comme deux paragraphes parce que a <p> se ferme implicitement lorsqu'un autre élément de bloc s'ouvre, et <li>a<li>b est deux éléments de liste pour la même raison Un analyseur naïf qui ne ferme que les éléments sur un explicite </p> va imbriquer le deuxième paragraphe à l'intérieur du premier et tout mutiler en aval Un convertisseur robuste applique les mêmes règles implicites de fin de balise que la spécification HTML définit : l'ouverture d'un élément au niveau du bloc ferme un paragraphe ouvert ; l'ouverture d'un <li> ferme le précédent Mon convertisseur fait cela, c'est pourquoi coller une sortie CMS bâclée fonctionne généralement simplement.
<script> et <style> blocs. Ceux-ci contiennent du code et du CSS, et non du contenu, et leur contenu doit être pris textuellement (a < à l'intérieur de JavaScript n'est pas une balise) et puis complètement abandonné Oubliez de les cas spéciaux et vous obtenez la source JavaScript qui saigne dans votre Markdown.
Entités HTML. Le contenu Web est jonché de &, ©, —, et des références numériques comme ’. Dans Markdown - qui est un texte brut - vous voulez les caractères réels : &, ©, —(en), et une véritable apostrophe Le décodage des entités nommées et numériques n'est pas facultatif ; sautez-le et votre Markdown propre se lit comme view-source.
C'est pourquoi j'ai arrêté d'essayer de convertir HTML avec find-and-replace et j'ai construit un analyseur tolérant approprié à la place Il tokenise le HTML dans une arborescence - gérer les commentaires, annuler les éléments comme <br> et <img>(en), les noms de balises majuscules et les attributs non cités - puis parcourt cette arborescence en émettant Markdown. Notamment, il ne s'appuie pas sur le DOM du navigateur & #39 ; ce qui signifie que la même logique s'exécute également sur un serveur, mais le gain pratique pour vous est simple : il ne fait pas de & #39 ; ne pas jeter sur le balisage désordonné dont sont faits les vrais sites Web.
Comment utiliser le convertisseur ?
Sur Toolz.dev/tools/html-to-markdown« Coller votre HTML dans le volet de gauche et le Markdown apparaît à droite lorsque vous tapez - il n'y a pas de téléchargement et pas de bouton Convertir à rechercher. Chargez l'échantillon si vous souhaitez voir chaque construction prise en charge à la fois ».
Quelques options couvrent les préférences communes Choisissez votre caractère de puce (-, *, ou +) pour les listes non ordonnées correspondant à votre style project' ;s. Gardez GitHub Flavored Markdown allumé pour les tables et les strikethrough, ou éteint si votre cible accepte uniquement CommonMark. Basculer et devis ; gardez les liens" ; désactivé lorsque vous voulez la prose mais pas les URL - pratique pour transformer un article riche en liens en texte de lecture propre - et " ; gardez les images" ; désactivé pour supprimer entièrement les images. La ligne de statistiques affiche les mots, les titres, les liens, les images, les blocs de code et un temps de lecture estimé, ce qui est une vérification rapide de la raison que la structure est passée avant de coller le résultat quelque part
Comme pour tout ce qui se trouve sur le site, la conversion est 100 % côté client L'analyseur est JavaScript simple exécuté dans votre navigateur, donc les pages collées, la documentation interne et les brouillons non publiés ne sont jamais envoyés nulle part. That' ; est la bonne valeur par défaut pour le travail de contenu - vous devriez' ; vous n'avez pas à télécharger une ébauche sur un serveur stranger' ; juste pour le reformater - et cela signifie que l'outil continue de fonctionner hors ligne. Je vais plus loin sur les raisons pour lesquelles le traitement côté navigateur est important dans le Guide des outils de confidentialité des données.
HTML vs Markdown : quand utiliser lequel
Convertir entre eux est facile ; savoir ce que vous voulez est la vraie décision.
| Aspect | HTML | Marquage |
|---|---|---|
| But principal | Rendu dans un navigateur | Écriture et stockage de texte |
| Lisibilité comme source | Pauvre (tag-heavy) | Excellent (lire en texte brut) |
| Git diffs | Bruyant | Nettoyer |
| Portabilité entre les systèmes | Faible | Haut |
| Contrôle précis de la disposition | Plein | Limité par conception |
| Où il vit | Pages Web, sortie WYSIWYG | READMEs, docs, notes, sites statiques |
| Courbe d'apprentissage | Ramper | procès-verbal |
Markdown échange délibérément le contrôle de la mise en page pour plus de simplicité, c'est pourquoi il gagne pour le contenu que vous écrivez, versez et déplacez, et perd lorsque vous avez besoin d'une présentation au niveau des pixels Convertissez HTML en Markdown lorsque vous et le n°39 ; capturez ou migrez contentement; gardez HTML lorsque vous et le numéro 39 ; construisez un page. Et lorsque vous devez aller dans l'autre sens - Marquage en HTML pour un champ CMS ou un modèle de courrier électronique - le Convertisseur de Markdown en HTML est l'image miroir de cet outil et partage les mêmes conventions, donc les deux aller-retour proprement pour les structures communes.
Où cela s'intègre dans un flux de travail de contenu
La conversion de format est rarement l'ensemble du travail ; c'est un pas de & #39 ; Après avoir converti un article en Markdown I & #39 ; j'exécute généralement le texte via a compteur de mots pour vérifier la longueur par rapport à une cible, et si la source avait des entités HTML qui ont besoin d'être codées pour une autre destination, le Encodeur/décodeur d'entité HTML gère l'inverse. Lorsque I' ; m nettoie le HTML manuscrit avant la conversion, un Minificateur HTML supprime le bruit en premier. Ces petits outils s'enchaînent en un pipeline reproductible, qui est l'idée derrière la façon dont je pense à une boîte à outils basée sur un navigateur - j'ai exposé cette philosophie dans Guide d'outils pour les développeurs Web Et le plus large Guide des outils de codage.
Erreurs courantes convertissant HTML en Markdown
Copier-coller le texte rendu au lieu de convertir le HTML. Vous perdez des liens, des titres et des listes - toute la structure Convertissez le balisage réel.
Ignorer la classe de langage de code. Si vos blocs clôturés sortent sans langue et que don' ; t surlignage, le convertisseur a laissé tomber le class="language-x" indice. Un bon le lit.
En supposant que CommonMark et GFM soient identiques. Les tables et les strikethrough sont des extensions GitHub Flavored Markdown, pas le noyau CommonMark Si votre destination est stricte CommonMark, une table won' ; t render - convertir avec GFM off et gérer les tables d'une autre façon.
Faire confiance à un convertisseur qui télécharge votre contenu. Beaucoup de " ; free" ; convertisseurs en ligne PUBLIEZ votre HTML sur un serveur Pour tout ce qui est non publié ou interne, que' ; est une fuite Utilisez un outil côté client.
FAQ
Comment convertir HTML en Markdown ?
Collez votre HTML dans l'éditeur et le Markdown apparaît immédiatement - il n'y a pas de fichier à télécharger et pas de bouton de conversion sur lequel appuyer Ajustez le style de la puce ou la gestion des liens si vous le souhaitez, puis copiez le Markdown ou téléchargez-le sous forme de fichier.md.
Le convertisseur gère-t-il les tableaux ?
Oui. Avec GitHub Flavored Markdown activé, un HTML est transformé en une table de tuyaux Markdown : la première ligne devient l'en-tête, une ligne de séparation est insérée et les lignes restantes deviennent le corps. Les caractères de tuyau à l'intérieur des cellules sont échappés afin qu'ils ne brisent pas la table.
Qu'arrive-t-il aux liens et images ?
Ancres deviennent [lien texte](href) et les images deviennent [TRADUCTION], préservation de l'attribut title lorsqu'il est présent Si vous désactivez " ; conservez liens" ; le texte d'ancrage est conservé mais l'URL est supprimée, et désactivez " ; conservez images" ; supprime entièrement les images - utiles lorsque vous ne voulez que la prose.
Les blocs de code et le code en ligne sont-ils conservés ?
Oui. A block becomes a fenced code block, and if the code element carries a class like "language-js" that language is added to the fence. Inline spans are wrapped in backticks, and the code text itself is never escaped or reformatted, so snippets stay exactly as written.
Will it work on messy HTML copied from a website?
That is what it is built for. The parser is tolerant of unclosed tags, uppercase element names, unquoted attributes and stray comments, and it strips