Markdown vs HTML: quando scegliere l'uno o l'altro

TL;DR. Markdown è un formato sorgente adatto alla scrittura che compila in HTML. HTML è il bersaglio di rendering che ogni browser, client di posta elettronica e CMS consuma alla fine. Scrivi in Markdown per la prosa; passa a HTML inline per layout complessi, form ed elementi interattivi.

Markdown e HTML vengono spesso discussi come alternative. Non lo sono. Markdown è un formato sorgente adatto alla scrittura che compila in HTML. HTML è il formato universale di rendering dei documenti che browser, client di posta e la maggior parte dei generatori di siti statici consumano alla fine. La domanda non è quale scegliere — ma in quale dovresti scrivere.

Le differenze principali

Quando vince Markdown

• File README, documentazione, post del blog. È il suo scopo principale. Si legge mentre si scrive, nessun rumore di tag, i diff nel controllo di versione sono puliti.
• Commenti, issue, messaggi di chat. GitHub, Discord, Slack, ogni moderno strumento di collaborazione accetta Markdown. Grassetto, link, blocchi di codice, elenchi — universali.
• Generatori di siti statici. Hugo, Jekyll, Next.js MDX, ogni moderno motore di blog accetta input in Markdown.
• Ovunque la prosa domina. Markdown è ottimizzato per “testo con formattazione occasionale” — esattamente il rapporto di cui gli scrittori hanno bisogno.

Quando vince HTML

• Qualsiasi cosa con layout complesso. Multi-colonna, tabelle con stile a livello di cella, posizionamento personalizzato. Markdown non può esprimere ciò che CSS richiede.
• Pagine web in produzione. Il browser esegue solo il rendering di HTML. Anche quando il tuo sorgente è Markdown, la pagina distribuita è HTML.
• Email. La maggior parte dei client di posta renderizza HTML; pochissimi renderizzano Markdown direttamente. Le email di marketing usano HTML + stili inline perché i client di posta rovinano qualsiasi cosa più sofisticata.
• Elementi interattivi. Form, script, iframe, attributi di accessibilità (aria-*, role) — territorio esclusivo di HTML.

Il problema delle varianti

“Markdown” non è una specifica unica. Esistono diverse varianti incompatibili:

• CommonMark (2014, in corso) — lo sforzo di standardizzazione. Rigoroso e prevedibile. La base a cui si conformano la maggior parte dei parser moderni.
• GitHub Flavored Markdown (GFM) — CommonMark più tabelle, testo barrato, elenchi di attività, autolink. Lo standard de facto per la documentazione degli sviluppatori.
• Pandoc Markdown — esteso per uso accademico e libri: note a piè di pagina, citazioni, elenchi di definizioni, matematica tramite LaTeX.
• Markdown originale di John Gruber (2004) — sottodefinito in alcuni punti. Parser diversi gestiscono i casi limite in modo diverso.

Se la portabilità è importante, scrivi in CommonMark ed evita le estensioni specifiche della variante.

HTML all’interno di Markdown

La maggior parte dei parser Markdown consente di inserire HTML grezzo inline quando Markdown non è sufficientemente espressivo. Questa è la valvola di sfogo pragmatica — mantieni il 95% del tuo documento in Markdown, passa a HTML per la tabella che necessita di colspan nelle celle, l’iframe che incorpora un video, il form.

Alcuni parser (quello di StackOverflow, ad esempio) eliminano la maggior parte dell’HTML per motivi di sicurezza. Controlla il contesto di rendering prima di fare affidamento su questo.

La regola pragmatica

• Scrittura: Markdown. Inizia sempre con Markdown.
• Lettura: HTML. Il browser/email renderizza l’output HTML del tuo Markdown.
• Casi limite: passa a HTML inline quando necessario.
• Email marketing, layout complessi, web in produzione: HTML direttamente.

Dati numerici

• Lunghezza della specifica Markdown: CommonMark 0.31 è ~70 pagine stampate; il WHATWG HTML Living Standard è >1.400 pagine.
• Rapporto di tasti: per un articolo tipico di 500 parole con 6 link e 3 intestazioni, il sorgente Markdown è ~620 caratteri rispetto a ~1.050 per HTML equivalente — circa 40% di tasti in meno.
• Velocità di parsing: markdown-it analizza ~150 MB/s di CommonMark su un laptop del 2024; i parser HTML moderni (lxml, html5ever) raggiungono 200-400 MB/s. Entrambi sono abbastanza veloci da non essere mai il collo di bottiglia.
• Supporto tabelle GFM: GitHub Flavored Markdown limita le tabelle a 64 colonne; la specifica CommonMark non ha affatto una sintassi nativa per le tabelle.
• Segnale di adozione: ~99% dei README su GitHub sono in Markdown (GitHub riporta un conteggio superiore a 280 milioni di file).

Matrice decisionale affiancata

Dove si nascondono le insidie

Tre modalità di errore ricorrono nei team che adottano Markdown per le pipeline di documentazione:

• Paragrafi a ritorno a capo forzato vs morbido. CommonMark tratta un singolo a capo all’interno di un paragrafo come uno spazio; GFM segue la stessa regola ma alcuni parser legacy (RedCarpet più vecchi, Pandoc vintage) lo trattano come un <br>letterale. La soluzione: non spezzare mai forzatamente all’interno di un paragrafo a meno che tu non intenda un a capo riga.
• Riscrittura delle virgolette tipografiche.Pandoc, Hugo e alcuni plugin Jekyll riscrivono silenziosamente le virgolette dritte in virgolette tipografiche curve — ottimo per la prosa, catastrofico all’interno di un campione di codice non recintato. Usa sempre blocchi di codice recintati (tripli backtick) per qualsiasi cosa contenga virgolette.
• Indentazione degli elenchi.CommonMark richiede che gli elementi degli elenchi annidati siano indentati di 2 o 4 spazi (corrispondendo all’offset del marcatore dell’elemento dell’elenco padre). I tab vengono renderizzati diversamente tra parser; non mischiare mai tab e spazi all’interno dello stesso elenco.

Fonti

• CommonMark Specification 0.31.2 — spec.commonmark.org (grammatica canonica di Markdown).
• WHATWG HTML Living Standard — html.spec.whatwg.org (riferimento HTML autorevole).
• GitHub Flavored Markdown Spec — github.github.com/gfm (superset CommonMark usato da GitHub).