Convertitore da HTML a Markdown

Cosa fa effettivamente la conversione HTML-a-Markdown

Un convertitore HTML-a-Markdown analizza un frammento HTML, percorre l'albero DOM risultante ed emette sintassi Markdown per ogni elemento che riconosce. <h1> diventa #; <strong> diventa **grassetto**; <a href="..."> diventa [testo](url); <ul><li> diventa una lista puntata. Lo strumento gira interamente nel tuo browser tramite JavaScript: incolla l'HTML a sinistra, clicca Converti in Markdown, e l'output formattato appare a destra. Niente upload, niente round-trip al server, niente telemetria: verifica nel pannello Network di DevTools mentre clicchi Converti, oppure metti la pagina offline (modalità aereo) dopo che si è caricata e il convertitore continua a funzionare. Questa implementazione usa il DOMParser integrato del browser per leggere l'HTML, poi un piccolo walker ricorsivo emette il Markdown per ogni nodo. È un convertitore scritto a mano di circa 150 righe piuttosto che un wrapper attorno a Turndown, il che significa che copre il caso comune in modo pulito ma non corrisponde alla configurabilità completa di Turndown.

Quando hai effettivamente bisogno di questa conversione

La direzione inversa (Markdown a HTML) è quella famosa: ogni generatore di siti statici e strumento di scrittura lo fa. La direzione in avanti (HTML a Markdown) è meno ovvia ma sempre più comune perché l'ecosistema degli strumenti di scrittura si è polarizzato: l'HTML è il formato ambientale del web (ogni CMS, piattaforma di newsletter, template CRM, vecchio sito statico emette o memorizza HTML); Markdown è il formato nativo di ogni workflow moderno di documentazione, presa di appunti e contenuto sotto controllo di versione apparso dal 2014 in poi circa. Quattro workflow del mondo reale generano questa esigenza di conversione.

• Scraping di articoli per app di presa di appunti. Salvare un articolo web in Obsidian, Notion, Logseq o Roam, tutti i quali memorizzano gli appunti come file Markdown. Il Web Clipper ufficiale di Obsidian (rilasciato nel 2024) e la popolare estensione browser MarkDownload seguono questo pattern: estrarre il DOM dell'articolo con la libreria Readability di Mozilla, convertire in Markdown, salvare su disco. Quando non puoi raggiungere l'HTML sottostante attraverso un'estensione (contenuto a pagamento, lettori incorporati, contenuto in arrivo via email), copia il testo renderizzato, incolla l'HTML risultante in un convertitore, salva il Markdown.
• Migrazione CMS a un SSG Markdown-first. Spostare la documentazione da WordPress, Confluence, Drupal, Mediawiki o Movable Type a MkDocs (Tom Christie, Python), Docusaurus (Meta, React), Hugo (Steve Francia, Go), Jekyll (Tom Preston-Werner, Ruby: ancora il motore dietro a GitHub Pages), Eleventy (Zach Leatherman, Node), VitePress (Evan You, Vue) o Sphinx-with-MyST. Tutti questi sono Markdown-nativi; il contenuto CMS esistente deve essere esportato come HTML e convertito in massa.
• Output di editor WYSIWYG a Markdown portabile. Uno scrittore usa Google Docs, Word, Apple Notes, Evernote o un editor rich-text di un CMS e il payload della clipboard è HTML. Vuole un Markdown pulito da committare in Git, incollare in un editor Markdown, mandare a uno sviluppatore o includere in un sito di docs. Il "Save as Web Page" di Microsoft Word produce HTML notoriamente denso, pieno di namespace XML, CSS con prefisso mso-, tag specifici di Office, e un convertitore che ignora tutto ciò che non capisce ed emette Markdown pulito è esattamente lo strumento di pulizia giusto.
• Contenuto email per archivio. Le piattaforme di newsletter (Substack, Kit/ConvertKit, Beehiiv, Mailchimp) inviano tutte HTML formattato. Un lettore che memorizza materiale di riferimento in Markdown può fare view-source sul corpo dell'email, incollare l'HTML in un convertitore e archiviare il risultato nei suoi appunti.

L'implementazione di riferimento: Turndown e la sua famiglia

Turndown (Dom Christie) è la libreria HTML-a-Markdown JavaScript dominante: è iniziata come to-markdown nel 2012, è stata rinominata Turndown nel 2017 per disambiguarla dai fork ed è pubblicata come turndown su npm sotto licenza MIT. Il suo design è basato su regole: ogni regola ha un filter (su quali nodi DOM la regola scatta) e una replacement (una funzione che produce il Markdown). Il costruttore accetta opzioni per lo stile di intestazione (atx # contro setext ===), il marker di lista (-, + o *), lo stile dei code block (indentato contro fenced), il delimitatore di enfasi (* contro _), il delimitatore di grassetto (** contro __), lo stile dei link (inline contro referenced) e così via. Tabelle, strikethrough, voci di lista task e autolink vivono nel pacchetto separato turndown-plugin-gfm. markdownify (Matthew Tretter) è l'equivalente in Python: ampiamente usato nelle pipeline di scraping, nella conversione di notebook Jupyter, nei document loader di LangChain e nella preparazione di dataset LLM. html2text (originariamente di Aaron Swartz, che collaborò anche con John Gruber al design Markdown originale nel 2004) è l'opzione Python più vecchia, ancora in uso nelle pipeline di posta legacy ma in gran parte superata. html-to-markdown (Johannes Kaufmann) è un port Go di Turndown popolare per binari di scraping autonomi. Pandoc (John MacFarlane, che presiede il progetto CommonMark) è il convertitore di documenti universale: gestisce tabelle con celle unite tramite grid table, matematica, citazioni, note a piè di pagina, definition list, e converte tra decine di formati. Pandoc è lo strumento HTML-a-Markdown più ricco di funzionalità disponibile, ma è un binario Haskell di oltre 60 MB che deve essere installato; non gira in un browser.

Il compromesso fondamentale: l'HTML è più ricco del Markdown

Ogni conversione HTML-a-Markdown è necessariamente lossy perché il formato sorgente esprime cose che il destinazione non può. Gli stili inline (<span style="color:red">) non hanno grammatica Markdown: il vocabolario di enfasi del Markdown è strettamente grassetto/corsivo/strikethrough/code, senza sintassi per colore, font o dimensione arbitrari. Le classi CSS (<div class="alert">) portano significato a un foglio di stile ma nessuno al Markdown. Gli attributi data custom (data-track-event="...") fanno parte del contratto JavaScript della pagina, non del documento. Le tabelle con celle unite (colspan, rowspan) non possono essere espresse nelle pipe table GFM. I media incorporati (<video>, <audio>, <iframe>) e i controlli di form non hanno equivalente Markdown. Le collassabili <details><summary>, <figure><figcaption>, le annotazioni <ruby> per la pronuncia CJK, microdata e microformat: nessuno sopravvive alla conversione. Per ogni costrutto non supportato, l'autore del convertitore sceglie una di tre strategie: tradurre in un'approssimazione Markdown che perde alcune informazioni, far passare come HTML grezzo incorporato dentro il Markdown (Markdown lo permette per specifica; CommonMark sezioni 4.6 e 6.6 lo coprono) o scartare del tutto. Questa implementazione sceglie "tradurre dove c'è un mapping chiaro, altrimenti transparent-wrap (renderizzare i figli, scartare il tag)": un default prevedibile e facile da ragionare che gestisce il caso comune al costo della configurabilità avanzata.

I mapping canonici

• Intestazioni: <h1>-<h6> mappano a # attraverso ###### (stile atx). La forma setext più vecchia (sottolineature === e ---) è anche valida per h1 e h2 ma raramente usata nel 2026.
• Paragrafi: <p> diventa testo semplice con righe vuote circostanti. Un'interruzione di paragrafo in Markdown è una o più righe vuote.
• Enfasi: <strong> e <b> diventano **grassetto**. <em> e <i> diventano *corsivo*. <del> e <s> diventano ~~strikethrough~~ (un'estensione GFM; non in CommonMark proper).
• Link: <a href="url">testo</a> diventa [testo](url). La forma reference-link ([testo][1] con [1]: url in fondo) è anche Markdown valido.
• Immagini: <img src="url" alt="testo"> diventa ![testo](url). Il punto esclamativo distingue le immagini dai link.
• Codice: <code> diventa span backtick inline. <pre><code> diventa un blocco fenced a tre backtick. Questa implementazione gestisce correttamente il requisito CommonMark che gli span di codice inline usino una fence più lunga quando il contenuto contiene backtick (corrispondendo alla regola di specifica da CommonMark §6.1).
• Liste: <ul> diventa righe puntate -; <ol> diventa righe numerate 1., 2., ... CommonMark accetta qualsiasi numero iniziale; i renderer normalizzano.
• Blockquote: <blockquote> antepone > a ogni riga dei figli.
• Linee orizzontali: <hr> diventa --- sulla propria riga. *** e ___ sono anche validi.
• Interruzioni di riga: <br> diventa una nuova riga. CommonMark accetta anche due spazi finali o un backslash a fine riga.
• Tabelle: <table> diventa una pipe table GFM: riga di intestazione, riga delimitatrice di ---, righe del corpo. Estensione GFM; non nel core CommonMark.

Ambito onesto: cosa fa e non fa questo strumento

Tre limitazioni oneste da conoscere. (1) Stili inline e classi CSS sono scartati. Un <span style="color:red"> diventa testo non stilizzato; un <p class="lede"> perde la sua classe. Non c'è grammatica Markdown per stilizzazione inline arbitraria. (2) Le tabelle con celle unite si appiattiscono. Le pipe table GFM non hanno sintassi per colspan o rowspan; le informazioni di celle unite vengono scartate silenziosamente. Per tabelle complesse, mantieni la sorgente come HTML dentro il Markdown (CommonMark permette HTML incorporato) o usa Pandoc per output con grid table. (3) I code block escono senza suggerimenti di linguaggio. Se il tuo HTML contiene <pre><code class="language-js">, l'attributo language viene attualmente scartato: l'output è un blocco fenced senza linguaggio. Puoi aggiungere manualmente l'identificatore di linguaggio dopo i backtick di apertura se il tuo renderer di destinazione supporta l'evidenziazione della sintassi. L'avvertenza più grande: se incolli l'HTML completo di una pagina web (da "Visualizza sorgente pagina"), i contenuti di <script> e <style> saranno emessi come testo semplice: quasi certamente non ciò che vuoi. La correzione è incollare solo il contenuto dell'articolo, o copiare dalla vista renderizzata (che elimina automaticamente script e stili), o sanificare l'HTML attraverso DOMPurify o simile prima della conversione.

La forma del Markdown nel 2026

Markdown ha compiuto ventidue anni nel 2026. John Gruber pubblicò lo script Perl originale nel 2004 con Aaron Swartz come collaboratore al design. Le tabelle furono deliberatamente omesse dall'originale di Gruber; la sintassi delle pipe table familiare alla maggior parte dei lettori oggi viene da dialetti successivi, soprattutto da GitHub Flavored Markdown. CommonMark, lo sforzo di specifica rigorosa organizzato da Jeff Atwood e John MacFarlane nel 2014, è ora alla versione 0.31.2 (28 gennaio 2024) ed è il dialetto a cui mira la maggior parte dei parser moderni. GitHub Flavored Markdown (GFM, formalizzato nella versione 0.29-gfm il 6 aprile 2019) è il superset GFM che aggiunge tabelle, task list, strikethrough, autolink e regole di disallowed-raw-HTML. GFM è il dialetto che la maggior parte degli utenti vede effettivamente sul web a causa della scala di GitHub. Markdown è ora il formato nativo di essenzialmente ogni ecosistema di documentazione per sviluppatori; HTML resta il formato di output universale del web; la conversione tra loro è esattamente comune quanto l'inversa, ed esiste per il momento in cui ne hai bisogno in fretta, in un browser, senza installazione e senza dati che lasciano il tuo dispositivo.

Privacy: perché solo browser conta qui

L'HTML incollato in un convertitore spesso contiene tracce della sorgente originale: markup CMS interno, contenuto bozza non ancora pubblicato, dati clienti dentro template email, URL di link che rivelano la struttura interna del sito, riferimenti di immagini che puntano a server di asset privati. I convertitori lato server caricano tutto questo a un servizio di terzi. Questo strumento gira interamente nel tuo browser tramite JavaScript: l'HTML che incolli non attraversa mai la rete: verifica nel pannello Network di DevTools mentre clicchi Converti, oppure metti la pagina offline (modalità aereo) dopo che si è caricata e il convertitore continua a funzionare. Sicuro per bozze non pubblicate, template email per clienti, estratti di documentazione interna o qualsiasi HTML che non vorresti vedere copiato sul disco di uno sconosciuto.

Domande frequenti

Funziona con file grandi?

Sì: poiché la conversione gira nel tuo browser, il tetto pratico è la memoria disponibile del tuo dispositivo. Decine di migliaia di righe convertono in ben meno di un secondo su un laptop moderno. Input molto grandi (milioni di nodi) possono brevemente bloccare la tab mentre il walker DOM ricorre. Per la conversione batch di un export CMS intero, uno script che usa Turndown in Node o markdownify in Python è lo strumento migliore.

Cosa succede agli stili inline e alle classi CSS?

Scartati del tutto. La grammatica di enfasi del Markdown copre grassetto, corsivo, strikethrough e codice; non c'è sintassi per colore, font, dimensione o stilizzazione guidata da classi arbitraria. Se la stilizzazione visiva conta nel tuo output, mantieni l'originale come HTML o usa un formato di destinazione più ricco come AsciiDoc, reStructuredText o MDX (Markdown più componenti JSX, usato da Docusaurus). Per i casi d'uso di archiviazione di articoli e migrazione CMS per cui questo strumento è costruito, scartare gli stili è il comportamento corretto: l'intero punto del Markdown è eliminare il rumore visivo e mantenere solo la struttura.

Questo strumento funziona offline?

Sì: una volta caricata la pagina, la conversione gira interamente in JavaScript dentro il tuo browser. Nessuna chiamata di rete durante la conversione. Verifica nel pannello Network di DevTools mentre clicchi Converti, oppure metti il dispositivo offline (modalità aereo) dopo il caricamento della pagina e lo strumento continua a funzionare.

Questo è Turndown?

No. Turndown (la libreria di Dom Christie) è l'implementazione di riferimento in JavaScript e lo strumento ovvio a cui ricorrere in un progetto Node, ma è una dipendenza sostanziale con piena configurabilità per stile di intestazione, marker di liste, stile di link, stile di code block e così via. Questo strumento in-browser è un walker DOM scritto a mano più piccolo, circa 150 righe, che mira al caso comune (intestazioni, paragrafi, enfasi, link, immagini, liste, blockquote, code fenced, tabelle base) senza la superficie di configurazione. Per i workflow per cui questo sito è costruito (conversioni una tantum in un browser, niente installazione), l'implementazione più piccola è la forma giusta; per pipeline di scraping di produzione che hanno bisogno di regole configurabili, Turndown resta la scelta giusta.

Come sono gestite le tabelle?

Come pipe table GFM: una riga di intestazione, una riga delimitatrice di trattini e una riga del corpo per ogni <tr>. Le pipe table sono piatte: non possono rappresentare colspan, rowspan, contenuto di cella multiriga, liste dentro le celle o allineamento per cella. Se la tua tabella HTML usa una di queste funzionalità, questo convertitore emette una pipe table degradata che perde la struttura extra. Per tabelle complesse, due opzioni pratiche: (a) mantieni la tabella come HTML grezzo dentro il Markdown (CommonMark permette HTML incorporato) e fidati che il tuo renderer di destinazione lo passi attraverso; (b) usa Pandoc con output a grid table, che può esprimere celle unite.

Posso incollare l'HTML completo di una pagina web?

Puoi, ma probabilmente non dovresti. La sorgente completa di una pagina web moderna contiene tag <script> con codice JavaScript, blocchi <style> con CSS, tracking pixel, markup pubblicitario e commenti template CMS. Questo convertitore non elimina esplicitamente il contenuto di script e style, quindi tutto ciò finisce come testo semplice nel tuo output Markdown. L'approccio pulito: seleziona solo l'elemento articolo in DevTools (clic destro sull'articolo, "Ispeziona", poi clic destro sul nodo corrispondente nel pannello Elements e "Copy outerHTML"), oppure usa un passaggio di estrazione del contenuto (la libreria Readability di Mozilla o la sua forma confezionata in Firefox Reader View) prima di incollare. Per workflow di estensioni browser che gestiscono il passaggio di estrazione automaticamente, vedi Obsidian Web Clipper o MarkDownload.

Strumenti correlati