01: Markdown e i suoi dialetti
Indice · successivo → 02 - Blocchi - paragrafi, liste, codice
1.1 Da dove viene
Markdown 1.0.1, John Gruber, 17 dicembre 2004. Da allora, nessuna versione successiva. Non è stato “congelato” con un annuncio: semplicemente non è mai più uscito niente.
L’obiettivo dichiarato era che il testo sorgente fosse leggibile così com’è, senza rendering. Non era un formato di pubblicazione: era un modo per scrivere email e post in testo semplice ottenendo HTML decente.
Il problema: la specifica originale era prosa in inglese più uno script Perl
(Markdown.pl). Dove la prosa taceva, l’implementazione decideva. E la prosa taceva
spesso. Risultato: ogni implementazione ha fatto scelte diverse, e lo stesso file ha
prodotto HTML diverso in posti diversi.
1.2 CommonMark: la specifica
CommonMark 0.31.2, 28 gennaio 2024: ed è ancora l’ultima ad agosto 2026. È una specifica vera: definisce l’algoritmo di parsing e include oltre 650 esempi eseguibili che fungono da test suite.
Domanda ovvia: perché dopo dodici anni è ancora 0.x? La risposta dei manutentori (John MacFarlane, 2019) è che “1.0 implica stabilità, e non ci siamo ancora”. Esiste una issue aperta dal 2025 che propone di chiamarla 1.0, ancora senza esito.
In pratica lo 0.x qui non significa instabile: CommonMark è il motore (o la base) di GitHub, GitLab, Reddit, Discourse, Stack Overflow, Swift, Qt.
Da ricordare
Quando qualcuno ti dice “ma questo è Markdown standard”, la domanda giusta è: standard secondo chi? CommonMark è la risposta più vicina a “standard” che esista.
1.3 GitHub Flavored Markdown
GFM 0.29-gfm, 6 aprile 2019. Anche questa ferma da anni, e, dettaglio che conta, basata su CommonMark 0.29, non sulla 0.31.2 attuale.
GFM si autodefinisce “a strict superset of CommonMark” e aggiunge cinque estensioni: tabelle, task list, strikethrough, autolink “nudi”, filtro sull’HTML pericoloso.
Ma c’è una seconda riga, nella spec stessa, che spiega quasi tutta la confusione del
mondo: “GitHub.com and GitHub Enterprise perform additional post-processing and
sanitization after GFM is converted to HTML”. Cioè: quello che vedi su github.com
non è solo GFM. Alert, footnote, emoji :tada:, menzioni @utente, math, Mermaid:
niente di tutto questo è nella specifica. È post-processing del sito.
Conseguenza operativa: un README che usa gli alert > [!NOTE] è bellissimo su GitHub e
diventa un blockquote con dentro [!NOTE] scritto in chiaro ovunque altro.
1.4 Gli altri dialetti che incontrerai
| Dialetto | Dove vive | Perché esiste |
|---|---|---|
| Obsidian Flavored | Obsidian | wikilink, embed, callout, highlight → 05 - Obsidian Flavored Markdown e portabilità |
| MDX | siti React/Astro | componenti e JSX dentro il contenuto → 06 - Frontmatter e Markdown per il web |
| Markdoc | Stripe, Astro | tag dichiarativi {% ... %}, validabili con uno schema |
| Pandoc Markdown | conversione documenti | il superset più ricco: definition list, citazioni BibTeX, note inline |
| MyST | editoria scientifica | direttive, cross-reference, export PDF/JATS |
| Quarto / R Markdown | report riproducibili | blocchi di codice eseguibili (R, Python, Julia) |
E per completezza: le RFC 7763 e 7764 (2016) registrano il media type
text/markdown con un parametro variant. Non normano la sintassi: registrano solo i
nomi delle varianti (CommonMark, GFM, pandoc, MultiMarkdown, Extra…). Chi dice
“Markdown è uno standard IETF” sta dicendo una cosa falsa.
1.5 La mappa mentale da tenere
Markdown (Gruber 2004, ambiguo)
└── CommonMark 0.31.2 ← la specifica seria, la base di quasi tutto
├── GFM 0.29 (+5 estensioni) ← ferma al 2019
│ └── github.com (+ alert, footnote, emoji, math, mermaid…) ← non è spec
├── Obsidian (+ wikilink, embed, callout, highlight, ^blockid…)
├── MDX (+ JSX, espressioni, import) ← toglie anche delle cose
└── Markdoc (+ tag dichiarativi)
Regola pratica che deriva da questo disegno: scrivi nel sottoinsieme più stretto che ti basta. Ogni estensione che usi è un vincolo su dove quel testo potrà vivere.
1.6 La domanda da farti prima di scrivere
Non “come si scrive X in Markdown”, ma: dove finirà questo testo?
- Resta solo nel mio vault Obsidian → usa tutto quello che vuoi.
- Finirà su GitHub → CommonMark + le 5 estensioni GFM, e gli alert solo se accetti che altrove degradino.
- Diventerà un sito (Astro, Hugo, Eleventy) → CommonMark + GFM, e verifica cosa supporta il tuo generatore. Le estensioni Obsidian richiedono plugin dedicati.
- Deve essere convertito (PDF, Word, LaTeX) → Pandoc, e allora hai altre regole ancora.
- Non lo so → CommonMark puro. Sempre.
Esercizi
- Apri il Dingus di CommonMark, incolla una tua nota vera e guarda l’HTML. Trova almeno una cosa che non viene come pensavi.
- Prendi una nota Obsidian con callout e wikilink, incollala in una gist di GitHub e confronta. Fai l’elenco di cosa si è rotto: è la tua mappa di portabilità personale.
- Cerca nella specifica CommonMark l’esempio che riguarda le liste che interrompono un paragrafo. Nota che la spec documenta i casi ambigui invece di nasconderli: è la differenza fra una specifica e un tutorial.