Guida alla Sintassi Estesa Markdown: Tabelle, Note e Altro

La sintassi estesa markdown è l'insieme di elementi di formattazione aggiunti dopo la pubblicazione della specifica originale di John Gruber nel 2004. La specifica del 2004 definiva 11 elementi di base e lasciava fuori del tutto tabelle, note a piè di pagina, elenchi di attività e testo barrato. Progetti successivi hanno colmato quei vuoti: MultiMarkdown ha introdotto tabelle e note a piè di pagina nel 2005, Pandoc è arrivato nel 2006 con il set di estensioni più ampio di qualsiasi processore, CommonMark ha standardizzato il nucleo nel 2014 lasciando spazio alle estensioni e GitHub ha pubblicato la specifica GFM nel 2017. Ogni elemento di questa pagina viene visualizzato nell'anteprima dal vivo dell'editor, quindi un incolla di 5 secondi ti dice se la tua app di destinazione lo gestisce.

Matrice di supporto

Nessuna applicazione supporta tutti i 12 elementi estesi, quindi verifica il supporto della tua destinazione prima di pubblicare. Le 4 destinazioni più comuni differiscono nettamente:

Una scorciatoia pratica: tabelle, blocchi di codice delimitati, testo barrato ed elenchi di attività vengono visualizzati quasi ovunque. Elenchi di definizioni, evidenziazione, pedice e apice sono i 4 elementi che falliscono più spesso.

Tabelle

Una tabella markdown separa le colonne con caratteri pipe e contrassegna la riga di intestazione con una riga divisoria di 3 o più trattini. I pipe esterni sono facoltativi nella maggior parte dei parser, ma migliorano la compatibilità, quindi conservali.

| Feature | Status |
| :------ | -----: |
| Export  | Done   |
| Sync    | Open   |

I due punti nella riga divisoria controllano l'allineamento. :--- allinea una colonna a sinistra, :---: la centra e ---: la spinge a destra. Il parser applica l'allineamento a ogni cella di quella colonna. Il numero di trattini non deve coincidere tra le colonne. Per stampare un pipe letterale dentro una cella, scrivi l'entità HTML |; GitHub accetta anche l'escape con barra rovesciata \|. Le celle accettano formattazione inline come grassetto e code span, ma mai elementi a blocco come elenchi o intestazioni.

MultiMarkdown ha introdotto la sintassi nel 2005 e GFM l'ha adottata nel 2017. GitHub, GitLab, Obsidian e Pandoc visualizzano le tabelle markdown. Discord no.

Blocchi di Codice Delimitati

Un blocco di codice delimitato si apre e si chiude con 3 backtick e non richiede indentazione, a differenza dei blocchi con 4 spazi della specifica del 2004. Tre tilde funzionano come delimitatore alternativo nella maggior parte dei parser.

```python
def total(items):
    return sum(items)
```

Un identificatore di linguaggio posto subito dopo il delimitatore di apertura attiva l'evidenziazione della sintassi. highlight.js, la libreria alla base di molti renderer web, include definizioni per circa 200 linguaggi, e gli identificatori più comuni sono python, js, json, bash e sql. Per mostrare un blocco di codice dentro un altro blocco di codice, usa 4 backtick per il delimitatore esterno.

Il supporto è il più ampio di qualsiasi elemento esteso. GitHub, Obsidian, Discord e Pandoc visualizzano tutti i blocchi delimitati, e tutti e 4 applicano l'evidenziazione del linguaggio.

Note a Piè di Pagina

Una nota a piè di pagina ha 2 parti: un marcatore di riferimento nel corpo del testo, scritto come [^1], e una definizione collocata in qualsiasi punto del file, scritta come [^1]: seguita dalla nota. Il renderer raccoglie ogni definizione in fondo alla pagina e collega ciascuna coppia in entrambe le direzioni.

The claim has a published source.[^1]

[^1]: Smith, 2024, p. 41.

Gli identificatori possono essere parole oltre che numeri, e [^note] si comporta esattamente come [^1] perché la numerazione in output segue l'ordine del documento e non l'etichetta. Una nota a piè di pagina può contenere più paragrafi quando i paragrafi aggiuntivi sono indentati di 4 spazi sotto la definizione.

MultiMarkdown ha introdotto le note a piè di pagina markdown nel 2005, Pandoc e Obsidian le supportano in modo completo e GitHub ha aggiunto il rendering delle note nel 2021. Discord non supporta le note a piè di pagina.

ID delle Intestazioni

Un ID personalizzato di intestazione sta tra parentesi graffe alla fine della riga dell'intestazione, e ## Refund Policy {#refunds} produce l'elemento HTML h2 con id="refunds". L'ID diventa un'ancora stabile per link e CSS.

## Refund Policy {#refunds}

Jump straight to [the refund policy](#refunds).

Il link è un normale link markdown con un cancelletto e l'ID come destinazione. Le pagine esterne raggiungono lo stesso punto quando #refunds viene aggiunto all'URL completo della pagina.

Pandoc e PHP Markdown Extra interpretano la forma con parentesi graffe. GitHub la ignora ma genera ID automatici dal testo dell'intestazione, quindi un link a #refund-policy funziona comunque. Obsidian usa il proprio schema [[Note#Heading]] per i link alle intestazioni. Discord visualizza le intestazioni nei messaggi ma non ha alcun sistema di ancore.

Elenchi di Definizioni

Un elenco di definizioni abbina un termine a 1 o più definizioni: il termine sta da solo su una riga e ogni definizione inizia sulla riga successiva con due punti e uno spazio.

Markdown
: A plain-text formatting syntax released in 2004.

Parser
: Software that converts markdown into HTML.
: Also called a processor.

L'output è un vero elemento <dl> con figli <dt> e <dd>, il che conta per i glossari e per gli screen reader. Righe con due punti in sequenza assegnano più definizioni a un unico termine.

Il supporto è ristretto. PHP Markdown Extra ha definito la sintassi, e Pandoc e MultiMarkdown la interpretano entrambi. GitHub e Obsidian stampano le righe con i due punti come testo semplice, e Discord fa lo stesso. L'HTML grezzo <dl> è il ripiego affidabile su GitHub.

Testo Barrato

Il testo barrato racchiude il testo tra 2 tilde per lato, quindi like this viene visualizzato come testo sbarrato. L'elemento proviene da GFM e l'output HTML è un elemento <del>.

~~Ship v2 on Friday.~~ Moved to Monday.

GitHub accetta anche una singola tilde per lato. Resta su 2 per la portabilità, perché la tilde singola significa pedice in Pandoc e una differenza di 1 carattere ribalta il significato.

Il supporto è quasi universale. GitHub, Obsidian, Discord e Pandoc visualizzano tutti il barrato con 2 tilde.

Elenchi di Attività

Una voce di elenco attività inizia come una normale voce di elenco e aggiunge le parentesi quadre: - [ ] indica un'attività aperta e - [x] una completata. Lo spazio dentro le parentesi vuote è obbligatorio.

- [x] Draft the outline
- [x] Write the copy
- [ ] Publish the page

GitHub ha introdotto la sintassi nel 2013 e ha reso le caselle interattive in issue e pull request, dove un clic aggiorna il markdown sottostante. GitHub le conta anche, quindi una issue riporta l'avanzamento come "2 of 3 tasks". Obsidian visualizza caselle cliccabili nella vista di lettura e Pandoc converte l'elenco attività markdown in caselle HTML. Discord lascia le parentesi come caratteri digitati.

Emoji

Le emoji entrano in un file markdown in 2 modi: incolla direttamente il carattere Unicode oppure digita uno shortcode come :rocket: nelle applicazioni che espandono gli shortcode. Le emoji incollate sopravvivono in qualsiasi file UTF-8, quindi 🎯 si vede anche dove gli shortcode falliscono.

Release day :tada: went live at 9 am.

Uno shortcode racchiude il nome di un'emoji tra 2 due punti. GitHub espande circa 1.800 shortcode e Discord espande il proprio set più le emoji personalizzate del server. Obsidian richiede un plugin della community per gli shortcode ma mostra nativamente le emoji incollate, e Pandoc espande gli shortcode solo con la sua estensione emoji attivata. I nomi variano tra le piattaforme, quindi uno shortcode che funziona su GitHub non è garantito altrove.

Evidenziazione

L'evidenziazione racchiude il testo tra 2 segni di uguale, e ==like this== viene visualizzato con uno sfondo stile evidenziatore, di solito giallo. L'output HTML è un elemento <mark>.

The deadline moved to ==14 March== at noon.

È uno degli elementi estesi meno portabili. Obsidian lo visualizza per impostazione predefinita e Pandoc lo interpreta una volta abilitata l'estensione mark, disponibile da Pandoc 3.0 nel 2023. GitHub e Discord stampano i segni di uguale così come sono. Dove la sintassi fallisce, il tag <mark> funziona in qualsiasi renderer che lascia passare l'HTML, inclusi i file readme di GitHub.

Pedice e Apice

Il pedice racchiude i caratteri tra tilde singole, come in H2O, e l'apice li racchiude tra accenti circonflessi singoli, come in x^2^. Entrambe le forme provengono dal set di estensioni di Pandoc e non da alcun flavor web diffuso.

H~2~O freezes at 0 degrees.
E = mc^2^ dates from 1905.

Pandoc li converte in elementi <sub> e <sup>. GitHub e Obsidian ignorano le forme con tilde e circonflesso ma lasciano passare i tag HTML, quindi H₂O funziona su entrambi. Discord non supporta nessuno dei due. Attenzione alla collisione della tilde: un'app con il barrato a tilde singola sbarrerà il tuo pedice invece di abbassarlo.

Link Automatici agli URL

Il link automatico agli URL trasforma un indirizzo nudo come https://example.com in un link cliccabile senza alcuna sintassi con parentesi. GFM ha formalizzato il comportamento come estensione autolink nella sua specifica del 2017.

Full docs at https://example.com/docs

GitHub e Discord trasformano in link gli URL nudi, e Obsidian fa lo stesso nella vista di lettura. Pandoc mantiene il comportamento disattivato a meno che non venga abilitata l'estensione autolink_bare_uris. Per impedire che un URL diventi un link, racchiudilo tra backtick; i code span non vengono mai trasformati in link, quindi https://example.com resta testo semplice negli esempi di configurazione e nei domini segnaposto.

Domande frequenti

La sintassi estesa fa parte del markdown ufficiale?

No. La specifica del 2004 definisce 11 elementi di base, e ogni elemento di questa pagina proviene da flavor e processori successivi. Markdown non ha un organo di governo, ed è per questo che il supporto cambia da un'applicazione all'altra.

Quale flavor markdown supporta più sintassi estesa?

Pandoc supporta la gamma più ampia, con oltre 30 estensioni di sintassi opzionali, e interpreta tutti i 12 elementi di questa pagina. GFM è l'obiettivo più pratico per la pubblicazione sul web, perché GitHub, GitLab e la maggior parte degli editor moderni lo seguono.

Perché una tabella si vede su GitHub ma non su Discord?

Discord implementa un sottoinsieme ristretto di markdown pensato per la chat e lascia fuori tabelle, note a piè di pagina, elenchi di attività ed elenchi di definizioni. Il suo sottoinsieme copre grassetto, corsivo, barrato, intestazioni e blocchi di codice delimitati. I contenuti destinati a Discord dovrebbero restare entro quei 5 elementi.

Come posso testare la sintassi estesa prima di pubblicare?

Incolla l'elemento nell'anteprima dal vivo dell'editor online, che visualizza GFM più le note a piè di pagina in meno di 1 secondo. Per qualsiasi altra destinazione, incolla un esempio di 2 righe direttamente nell'app di destinazione; la matrice di supporto copre i 4 casi più comuni.