Le tabelle in Markdown

Le tabelle non fanno parte del Markdown originale del 2004: sono arrivate con il GitHub Flavored Markdown e da lì si sono diffuse quasi ovunque. Oggi le supportano GitHub, GitLab, quasi tutti i generatori di siti statici e tutti gli editor moderni — ma non è garantito al cento per cento, ed è l’unico elemento di questa guida per cui vale la pena controllare la destinazione prima di usarlo molto.

Prova a modificare la tabella qui sotto: le colonne si ricompongono mentre scrivi.

| Funzione   | Gratis | Pro |
|:-----------|:------:|----:|
| Anteprima  |   ✓    |  ✓  |
| Export PDF |   ✓    |  ✓  |
| Modo focus |   —    |  ✓  |
| Cronologia |   —    |  ✓  |

Le tre regole

Una tabella Markdown è fatta di tre cose, e sono tutte obbligatorie:

1. Una riga di intestazione, con le celle separate da barre verticali |.
2. Una riga di separazione, fatta di trattini, che divide l’intestazione dal corpo. È questa riga che dice al compositore “quella sopra è una tabella”.
3. Una o più righe di contenuto, con lo stesso numero di celle.

| Nome | Ruolo |
|------|-------|
| Ada  | Progetto |
| Carlo| Sviluppo |

La riga di separazione ha bisogno di almeno tre trattini per colonna in molti compositori, e di un numero di colonne identico a quello dell’intestazione. È l’errore numero uno: se la tabella non si compone, conta le celle della riga di separazione.

L’allineamento

I due punti nella riga di separazione decidono come si allinea ogni colonna. È l’unica formattazione che una tabella Markdown sa applicare a una colonna intera:

| A sinistra | Al centro | A destra |
|:-----------|:---------:|---------:|
| testo      | testo     | testo    |

• :--- allinea a sinistra (è anche il comportamento predefinito)
• :---: centra
• ---: allinea a destra

I numeri stanno quasi sempre meglio allineati a destra, perché le unità si incolonnano e i valori si confrontano a colpo d’occhio.

Le barre non devono essere allineate

Questo sorprende quasi tutti. Nel sorgente le barre possono essere disordinate quanto vuoi: il risultato composto è identico.

| Nome | Ruolo |
|---|---|
| Ada | Progetto |
| Carlo | Sviluppo |

Allineare le colonne a mano rende il sorgente più leggibile, ma è puro gusto personale — e su una tabella che modifichi spesso diventa una manutenzione noiosa. Un editor con anteprima live toglie del tutto il problema, perché la tabella ordinata la vedi comunque a fianco.

Anche le barre verticali all’inizio e alla fine di ogni riga sono facoltative in quasi tutti i compositori, ma metterle è più sicuro e si legge meglio.

Formattare dentro le celle

Dentro una cella funziona la sintassi in linea: grassetto, corsivo, codice, collegamenti, immagini.

| Elemento | Sintassi | Guida |
|---|---|---|
| **Grassetto** | `**testo**` | [vedi](/it/guida-markdown) |
| *Corsivo* | `*testo*` | [vedi](/it/guida-markdown) |

Quello che non funziona sono gli elementi di blocco: niente titoli, niente elenchi, niente blocchi di codice, niente citazioni. Una cella è una riga di testo, e basta.

Quello che le tabelle non sanno fare

Vale la pena saperlo prima di costruirci sopra qualcosa di complicato, perché nessuna di queste cose è possibile in Markdown puro:

• Celle unite, in orizzontale o in verticale.
• Più righe dentro una cella.
• Tabelle annidate.
• Intestazioni di riga (solo la prima riga può essere intestazione).
• Tabelle senza intestazione: la riga di intestazione è obbligatoria. Se non ne vuoi una, l’unico trucco è lasciarne le celle vuote — | | | — che funziona ma resta un trucco.

Se ti serve una di queste cose, le strade sono due: incorporare una tabella HTML dentro il Markdown (funziona dove l’HTML è permesso, cioè non ovunque), oppure accorgersi che quella tabella forse voleva essere un elenco.

Proteggere una barra verticale

Una | dentro una cella spezza la tabella, perché il compositore la legge come un separatore. Proteggila con una barra rovesciata:

| Comando | Cosa fa |
|---|---|
| `a \| b` | Manda l'uscita di a dentro b |

Dentro il codice in linea la protezione serve lo stesso: gli apici inversi non salvano la barra dall’essere letta come separatore di cella.

Errori comuni

• La riga di separazione manca o ha il numero di colonne sbagliato. È la causa di gran lunga più frequente di una tabella che resta testo.
• Nessuna riga vuota prima della tabella. Se il paragrafo precedente la tocca, molti compositori non la riconoscono.
• Numero di celle diverso fra le righe. Le celle in più vengono ignorate, quelle in meno lasciano la riga incompleta: nessuno dei due casi dà errore, semplicemente esce una tabella storta.
• Una | non protetta dentro il contenuto.
• Provare a scrivere un elenco dentro una cella. Non funziona in Markdown puro.

Domande frequenti

Come si crea una tabella in Markdown?

Servono tre cose: una riga di intestazione con le celle separate da barre verticali |, una riga di separazione fatta di trattini con lo stesso numero di colonne, e poi le righe di contenuto. La riga di separazione è obbligatoria: è quella che dice al compositore che il blocco è una tabella e non del testo normale.

Come allineo le colonne di una tabella Markdown?

Con i due punti nella riga di separazione: :--- allinea a sinistra, :---: centra e ---: allinea a destra. È l’unico controllo di formattazione che si può applicare a un’intera colonna, e conviene usarlo almeno per i numeri, che si leggono molto meglio allineati a destra.

Una cella di una tabella Markdown può contenere più righe?

No. In Markdown puro una cella è una singola riga di testo: non accetta a capo, elenchi, titoli né blocchi di codice. Funziona invece la formattazione in linea — grassetto, corsivo, codice e collegamenti. Se ti serve davvero una cella su più righe, l’unica strada è una tabella HTML, dove l’HTML è permesso.

Le barre devono essere allineate nel sorgente?

No. Il risultato composto è identico che le barre siano incolonnate o completamente disordinate. Allinearle rende il sorgente più gradevole da leggere, ma è solo estetica: su una tabella che modifichi spesso è manutenzione inutile, soprattutto se hai un’anteprima live che ti mostra già la tabella ordinata.

Come inserisco il carattere | dentro una cella?

Con una barra rovesciata davanti: \|. Senza, il compositore lo legge come separatore di cella e la riga si spezza. La protezione serve anche dentro il codice in linea: gli apici inversi non impediscono alla barra di essere interpretata come separatore.