Convertitore da Markdown a HTML

Come funziona

1. Incolla Markdown: inserisci qualsiasi testo Markdown, titoli, paragrafi, liste, blocchi di codice, tabelle, citazioni e link.
2. Converti: lo strumento analizza il Markdown e produce HTML pulito e semantico con una corretta annidatura degli elementi.
3. Visualizza l'anteprima o copia: visualizza l'anteprima del rendering o copia l'HTML grezzo da incollare nel tuo CMS, sito web o template e-mail.

Una breve storia di Markdown

Markdown è stato creato da John Gruber, lo scrittore dietro il weblog Daring Fireball, con sostanziale feedback di design da parte di Aaron Swartz. Il primo rilascio pubblico, versione 1.0, è stato annunciato sul sito di Gruber il 9 marzo 2004; la versione 1.0.1, il rilascio di riferimento canonico, è seguita il 17 dicembre 2004 ed è ancora la versione linkata da daringfireball.net/projects/markdown. Markdown era due cose contemporaneamente fin dall'inizio: una sintassi di formattazione in testo semplice e lo script Perl originale che la convertiva in HTML. L'obiettivo dichiarato di Gruber era che il testo sorgente fosse leggibile così com'è, un documento Markdown aperto in un editor di testo semplice dovrebbe sembrare un'email formattata con cura, non una zuppa di tag. Quel vincolo di leggibilità è la linea filosofica che separa Markdown dai formati basati su XML e dal markup più pesante come LaTeX, ed è la ragione per cui ogni estensione successiva ha dovuto argomentare per se stessa in termini di quanto disturba il sorgente. Aaron Swartz aveva precedentemente scritto un markup leggero correlato chiamato atx (2002), che ha contribuito allo stile di intestazione ora familiare # e ##, ancora a volte chiamato "intestazioni stile atx" all'interno delle spec dei parser.

CommonMark, risolvere la sottospecificazione

La descrizione della sintassi originale di Gruber del 2004 era notoriamente informale, un documento di prosa con esempi, non una grammatica. Lasciava dozzine di casi limite non specificati, e Gruber non ha mai rilasciato un parser di riferimento diverso dal suo script Perl, il cui comportamento era idiosincratico in modi che altri implementatori dovevano copiare o sovrascrivere. Il risultato all'inizio degli anni 2010 era che GitHub, Reddit, Stack Overflow, Pandoc e il parser Discount C renderizzavano tutti la stessa sorgente Markdown in modo leggermente diverso. Nel 2012, il cofondatore di Stack Overflow Jeff Atwood e l'autore di Pandoc John MacFarlane hanno iniziato uno sforzo per scrivere una specifica reale e testabile. Il progetto è stato lanciato pubblicamente nel settembre 2014 come "Standard Markdown"; entro pochi giorni Gruber ha obiettato al nome in email privata, Atwood ha scritto un post pubblico spiegando il cambiamento, e il progetto è stato rinominato "CommonMark". Il primo rilascio numerato è arrivato il 25 ottobre 2014. La versione attuale pubblicata è CommonMark 0.31.2, rilasciata il 28 gennaio 2024. La specifica CommonMark è insolita in quanto è essa stessa un documento CommonMark, con oltre 600 test case eseguibili inline; un parser rivendica la conformità superando quei test. GitHub Flavored Markdown (GFM), la specifica formale alla versione 0.29-gfm datata 6 aprile 2019, definisce cinque estensioni su CommonMark: tabelle, voci di lista task, strikethrough, autolink per URL nudi, e HTML grezzo non consentito (una restrizione di sicurezza che rimuove tag pericolosi dall'HTML fornito dall'autore).

I parser principali

marked.js è stato creato da Christopher Jeffrey nel 2011 ed è stato mantenuto dall'organizzazione GitHub markedjs dal 2018, un design a singolo passaggio, lexer-poi-parser che dà priorità alla velocità grezza; ~36k stelle e il progetto Markdown più stellato su GitHub. È il parser che questo strumento usa per la conversione. markdown-it è stato lanciato nel 2014 da Vitaly Puzrin e Alex Kocharin, pubblicizzando il 100% di conformità a CommonMark con toggle opzionali GFM più un aggressivo ecosistema di plugin (markdown-it-footnote, markdown-it-emoji, markdown-it-attrs, markdown-it-anchor e diverse centinaia di altri). È il parser usato dall'anteprima Markdown integrata di VS Code, dalla UI web di GitLab e da Eleventy. remark / unified.js non è un singolo parser ma un framework di trasformazione dell'albero, il collettivo unified definisce una specifica di albero di sintassi astratta chiamata mdast (Markdown AST); remark parsa Markdown in mdast, i plugin manipolano l'albero, e remark-rehype converte mdast in hast (HTML AST) per l'emissione. Più lento di marked ma vastamente più componibile; utenti notevoli includono Prettier, Gatsby, MDN e il linter di linguaggio inclusivo alex. Pandoc, rilasciato da John MacFarlane il 10 agosto 2006, è il convertitore di documenti universale, scritto in Haskell, parsa circa 30 formati di input, renderizza in circa 40 formati di output; onnipresente nella pubblicazione accademica e tecnica.

La pipeline MD-a-HTML, meccanicamente

Un parser Markdown tipicamente lavora in due passaggi. Il parsing a livello block divide l'input in strutture block, paragrafi, intestazioni, liste, fence di codice, blockquote, regole orizzontali, tabelle. I confini dei block sono determinati da righe vuote e indentazione; farli bene è la maggior parte di ciò che rende corretto un parser CommonMark. Il parsing inline poi cammina attraverso il contenuto di ciascun block e abbina la sintassi inline: enfasi (*italic*, **bold**), link ([text](url)), span di codice inline (`code`), immagini (![alt](url)), strikethrough (~~text~~ in GFM), e autolink espliciti (<https://example.com>). Il parsing dell'enfasi inline è la parte più rognosa di qualsiasi specifica Markdown, CommonMark dedica diverse pagine della specifica e dozzine di test case alla specifica di quando *foo*bar* dovrebbe produrre <em>foo</em>bar* contro *foo<em>bar</em>. Il parser poi renderizza ogni token come il corrispondente elemento HTML e concatena i risultati. Pretty printing, indentazione e syntax highlighting dei blocchi di codice sono stratificati in cima dalle opzioni di rendering.

Perché convertire MD in HTML in primo luogo?

• Importazioni CMS. Molti CMS headless (Contentful, Sanity, Wagtail, Ghost) accettano HTML ma non Markdown. Bozze in Markdown e convertire una volta al momento della pubblicazione mantiene piacevole l'esperienza di editing.
• Composizione email. I client email renderizzano HTML; la maggior parte non renderizza Markdown. Le piattaforme di newsletter (Mailchimp, ConvertKit, Substack) tipicamente accettano HTML incollato nel loro editor. Converti la tua bozza, incolla, invia.
• Bozze di post di blog. Alcune vecchie installazioni di WordPress senza il plugin Markdown richiedono HTML nel body del post; alcune pagine shop di Shopify e Webflow accettano HTML nei loro campi di rich-text.
• Snippet per generatori di siti statici. Quando hai bisogno di un blocco HTML inline per uno shortcode Hugo, un template Eleventy o un file MDX Next.js, convertire Markdown in un singolo frammento HTML è più veloce che combattere la pipeline di conversione del proprio SSG.
• Condivisione di note renderizzate. Incollare Markdown "renderizzato" in Slack, Notion, Linear, ClickUp o altre destinazioni rich-text a volte vuole HTML nella clipboard piuttosto che Markdown grezzo.
• Archiviazione di documentazione. Memorizzare l'HTML renderizzato accanto al sorgente Markdown significa che il tuo archivio è leggibile dall'uomo in un browser senza un parser, utile per la conservazione a lungo termine.

Opzioni di output che vale la pena conoscere

Diversi usi a valle vogliono cose diverse dall'HTML convertito. Documento completo vs frammento. Un documento HTML completo include <!DOCTYPE html>, <html>, <head> con metadati e un wrapper <body>, appropriato quando salverai il file come .html e lo aprirai in un browser. Un frammento è solo il contenuto del body, nessun wrapper, appropriato quando incollerai in un campo CMS che fornisce già la struttura del documento. Questo strumento emette frammenti di default; avvolgi con il tuo boilerplate se hai bisogno di un documento completo. Sanitizzazione. Di default i parser Markdown passano l'HTML grezzo attraverso invariato, quindi se la tua sorgente contiene <script>alert(1)</script>, quel tag script apparirà nell'output. Per documenti che vanno in un sistema multi-utente, esegui l'output attraverso DOMPurify (Cure53, iniziato febbraio 2014) prima di iniettare nel DOM. Per uso personale una tantum, l'output grezzo va bene. ID header. Generare attributi id sulle intestazioni (slugificati dal testo dell'intestazione) ti permette di costruire un sommario con link ancora. L'algoritmo di slug esatto differisce tra le piattaforme, GitHub usa una regola, MkDocs un'altra, marked.js una terza, quindi i link ancora possono rompersi quando il contenuto si muove tra sistemi. Hard line break. CommonMark richiede o due spazi finali alla fine di una riga o un backslash per forzare un <br>; alcune piattaforme (Discord, GitHub issues) trattano i newline singoli come break. La scelta dipende dallo stile atteso della tua sorgente.

Insidie comuni

• Conversione delle virgolette intelligenti. Alcuni parser (o layer di post-processing come SmartyPants dello stesso Gruber) sostituiscono le virgolette dritte con virgolette tipografiche ricciolute di default. Se hai bisogno di virgolette dritte preservate (perché il tuo output viene parsato come codice), verifica che questa trasformazione sia disattivata.
• Sensibilità agli spazi bianchi dei marcatori di lista. Mischiare - e * e + nella stessa lista, indentare i paragrafi di continuazione della lista meno di quanto richiede il marcatore, o mettere una riga vuota tra le voci di lista può capovolgere una lista stretta in una lista lasca (ogni voce avvolta in tag <p>). La differenza visiva nell'output è drammatica.
• Eccesso di zelo dell'autolink. L'autolinking in stile GFM trasforma qualsiasi URL nudo in un link, che è solitamente quello che vuoi, ma può mutilare URL contenenti parentesi (URL di Wikipedia specialmente) o punteggiatura finale.
• Tabelle che necessitano escape. I caratteri pipe dentro le celle delle tabelle devono essere escapati come \|, altrimenti vengono letti come separatori di colonna. Cattura chiunque tenti di mettere un esempio di codice in una riga dentro una cella.
• Markdown e HTML mescolati. Markdown è stato progettato per passare HTML arbitrario, quindi inserire un <div class="callout"> in un file Markdown funziona. Ma nel momento in cui metti sintassi Markdown dentro un block HTML, i parser divergono: CommonMark tratta la maggior parte dei block HTML come opachi; Markdown Extra ha introdotto markdown="1" per optare per il parsing annidato.
• ID intestazione attraverso le piattaforme. Diversi algoritmi di slugify producono diversi frammenti ancora per la stessa intestazione; i link intra-documento possono rompersi quando il contenuto si muove tra sistemi.

Questo strumento vs il Markdown Previewer

Absolutool spedisce due strumenti correlati che si sovrappongono sullo stesso parser. Il Markdown Previewer è per l'editing dal vivo, scrivi Markdown a sinistra, vedi l'output visivo renderizzato a destra, nessun concetto di "l'output HTML". Questo convertitore Markdown-a-HTML è per la conversione una tantum, incolla Markdown, copia HTML grezzo, incolla nel tuo CMS o client email. Usa il previewer quando stai facendo bozze e hai bisogno di feedback visivo; usa questo convertitore quando hai Markdown finito e hai bisogno di HTML che puoi trasportare altrove. Entrambi gli strumenti usano marked.js sotto il cofano e accettano lo stesso dialetto CommonMark + GFM, quindi il comportamento di conversione è identico tra di loro.

Privacy: perché il solo-browser conta qui

Bozze di scritti non pubblicati, post di blog in corso, documentazione interna, deliverable cliente sotto NDA, capitoli di manoscritti, articoli accademici, sono esattamente il tipo di testo che non vuoi caricare a un servizio di terze parti. I convertitori Markdown lato server richiedono di inviare l'intero documento a un endpoint remoto, il che significa che rimane nei log del server, possibilmente in una cache CDN, possibilmente in una pipeline di analisi, possibilmente in un backup. Per testo pubblicato la questione è discutibile. Per il lavoro di bozza, l'architettura conta. Questo strumento esegue l'intera pipeline nel tuo browser tramite JavaScript e marked.js. Il Markdown non attraversa mai la rete, verifica nel tab Network di DevTools mentre digiti, o porta la pagina offline (modalità aereo) dopo che si carica e conferma che il convertitore funzioni ancora. Sicuro per bozze confidenziali, deliverable cliente, capitoli di manoscritto sotto NDA, memo interni o qualsiasi altra cosa che non vorresti copiata sull'hard drive di uno sconosciuto.

Domande frequenti

Quale dialetto Markdown supporta questo convertitore?

CommonMark con le estensioni GFM più comuni abilitate, tabelle (pipe-delimitate con allineamento : opzionale), blocchi di codice fenced con suggerimenti di linguaggio, strikethrough tramite ~~text~~, autolink per URL nudi, e voci di lista task tramite [ ] e [x]. Intestazioni, grassetto, corsivo, link, immagini, liste, blockquote, regole orizzontali e codice inline funzionano tutti come ti aspetteresti su GitHub. Il renderer è marked.js, lo stesso parser che usa il Markdown Previewer.

Supporta GitHub Flavored Markdown (GFM)?

Sì, tabelle con pipe, blocchi di codice fenced con suggerimenti di linguaggio, liste task, autolink e strikethrough funzionano tutti. Se un'estensione GFM non sta renderizzando, ricontrolla che l'input segua le regole di sintassi CommonMark/GFM: righe vuote attorno agli elementi block, conteggi di backtick corrispondenti sui blocchi di codice fenced, esattamente due spazi finali (o un backslash) per hard line break. La causa più comune di "GFM non funziona" è un editor che rimuove gli spazi bianchi finali al salvataggio, che uccide la sintassi hard-break.

L'output sembrerà uguale su GitHub?

L'HTML strutturale, paragrafi, liste, tabelle, intestazioni, corrisponderà per qualsiasi input che è CommonMark + GFM valido. Due layer differiranno. GitHub applica il proprio tema CSS e syntax-highlighting, quindi colori, font e spaziatura sembreranno diversi. GitHub stratifica anche post-processing sopra la specifica, shortcode emoji (:smile:), menzioni @user, auto-linking #issue, percorsi di immagine relativi al repository, che nessun convertitore spec-compliant riproduce. L'HTML che questo strumento emette è strutturalmente portabile; l'aspetto visivo dipende dal CSS nella destinazione.

Dovrei sanitizzare l'output prima di pubblicare?

Se la sorgente potrebbe includere contenuto fornito dall'utente, sì. I parser Markdown passano l'HTML grezzo attraverso invariato, quindi una sorgente che contiene <img src=x onerror="alert(1)"> produrrà quel tag nell'output. Per sistemi multi-utente, esegui l'output attraverso DOMPurify (Cure53, febbraio 2014, il sanitizer JavaScript de facto) prima di iniettare nel DOM. Per uso personale una tantum dove la sorgente è la tua scrittura, questo non è un problema, il peggio che puoi fare alla tua pagina è incollare il tuo HTML.

Posso ottenere un documento HTML completo con head e body?

Attualmente questo strumento emette solo il frammento del body, il Markdown convertito avvolto in tag HTML semantici ma non in un documento completo <html>/<head>/<body>. Per salvare come file .html standalone, avvolgi l'output tu stesso: <!DOCTYPE html><html><head><meta charset="utf-8"><title>...</title></head><body>[fragment]</body></html>. O usa Pandoc con il flag --standalone per un output completamente standalone con CSS guidato da template.

Il mio Markdown viene inviato da qualche parte?

No. La conversione gira interamente nel tuo browser tramite marked.js. Il Markdown che incolli non attraversa mai la rete, verifica nel tab Network di DevTools mentre digiti, o porta la pagina offline (modalità aereo) dopo che si carica e conferma che il convertitore funzioni ancora. Sicuro per bozze confidenziali, deliverable cliente sotto NDA, capitoli di manoscritto o qualsiasi testo che non vorresti copiato sull'hard drive di uno sconosciuto.

Strumenti correlati