Tabelle in Markdown: sintassi GFM, allineamento e limiti
Tabelle pipe GFM, allineamento e limiti delle celle.
Una tabella Markdown è costituita da una riga di intestazione, una riga di separatori con trattini e le righe di dati che la seguono. La riga di separatori è ciò che trasforma le barre verticali in una tabella in GFM e in Hugo.
Questa guida fa parte di Strumenti per la documentazione nel 2026: Markdown, LaTeX, PDF e flussi di stampa. Gli altri tipi di blocco si trovano nella Scheda Rapida Markdown.
Le tabelle non sono incluse nella sintassi Markdown originale né in CommonMark. Si tratta dell’estensione per le tabelle nella specifica di GitHub Flavored Markdown. Hugo 0.164 utilizza Goldmark con tale estensione abilitata per impostazione predefinita (markup.goldmark.extensions.table). Gli esempi seguenti sono racchiusi in blocchi di codice delimitati da tre backtick, in modo che le barre verticali restino letterali; questo è il pattern utilizzato nei blocchi di codice Markdown.
Sintassi delle tabelle a barre verticali
Una tabella è composta da tre parti: una riga di intestazione, una riga di separatori e zero o più righe di dati. Le celle sono separate da |. Una barra verticale all’inizio e alla fine di una riga è facoltativa. Gli spazi adiacenti a una barra verticale vengono eliminati.
| Header 1 | Header 2 |
| --- | --- |
| Cell A1 | Cell B1 |
| Cell A2 | Cell B2 |
Le guide di scrittura di GitHub indicano che ogni cella della riga di separatori deve contenere almeno tre trattini e che è necessaria una riga vuota prima della tabella affinché GitHub la renderizzi correttamente. La specifica GFM descrive la cella del separatore come trattini, con un eventuale punto e virgola su uno o entrambi i lati, e i suoi esempi includono una cella con un solo trattino. Hugo 0.164 ha reso questa struttura come una tabella:
| A | B |
| - | - |
| 1 | 2 |
La stessa renderizzazione di Hugo ha inoltre trasformato una tabella in un elemento <table> quando la riga precedente era un paragrafo e non era presente una riga vuota. Su GitHub, è necessario seguire la regola dei tre trattini per il separatore e della riga vuota. Su questo sito, un solo trattino è sufficiente e la riga vuota non è richiesta.
Anche |Troppo|Stretto| con un separatore |---|---| è stato renderizzato. Gli spazi accanto alle barre verticali vengono eliminati. Gli spazi presenti nel primo esempio mantengono leggibile la differenza nel codice sorgente.
La riga di intestazione e la riga di separatori devono avere lo stesso numero di celle. Se differiscono, Hugo non riconosce una tabella. Il testo resta ordinario e i trattini diventano soggetti al tipografo di Hugo:
| abc | def |
| --- |
| bar |
Una riga di dati può essere più corta o più lunga dell’intestazione. Una riga corta viene completata con celle vuote. Le celle oltre il conteggio dell’intestazione vengono scartate.
| A | B | C |
| --- | --- | --- |
| 1 | 2 |
| A | B |
| --- | --- |
| 1 | 2 | 3 |
Il primo di questi esempi rende una terza cella vuota. Il secondo rende solo 1 e 2.
Una riga senza barre verticali è ancora all’interno della tabella fino a quando non si incontra una riga vuota. Hugo 0.164 ha inserito un bar successivo nella tabella come una riga con una seconda cella vuota, in linea con l’esempio 202 di GFM. Il paragrafo successivo inizia dopo la riga vuota.
| abc | def |
| --- | --- |
| bar | baz |
bar
next
Allineamento delle colonne
L’allineamento si imposta con un due punti nella riga di separatori. --- senza due punti indica l’allineamento a sinistra, identico a :---.
| Left | Right | Center |
| :--- | ----: | :----: |
| text | 12.50 | yes |
| Left | Right | Center |
|---|---|---|
| text | 12.50 | yes |
I due punti nella riga di intestazione sono caratteri all’interno di quella cella. Non impostano l’allineamento. È la riga di separatori sottostante che Hugo utilizza:
| :--- Left | Right ---: |
| :-------- | ---------- |
| Correct | Alignment |
Contenuto delle celle
Gli elementi inline funzionano all’interno di una cella: enfasi, span di codice e link. Le strutture a blocco non funzionano. La specifica GFM afferma che gli elementi a livello di blocco non possono essere inseriti in una tabella, quindi un elenco o un blocco delimitato all’interno di una cella non è un elenco né un blocco delimitato.
| Feature | Status | Documentation |
| ---------- | ---------- | ------------- |
| **API v2** | *Released* | [Docs](/api) |
| `Auth` | Beta | Coming soon |
Una barra verticale letterale è \| o |. Hugo 0.164 ha renderizzato entrambi come |.
| Expression | Result |
| ---------- | ------ |
| a | b | true |
| x \| y | false |
Un’interruzione di riga all’interno di una cella è un tag HTML <br>. Questo sito imposta markup.goldmark.renderer.unsafe a true, quindi tale tag viene conservato. Un processore che rimuove l’HTML grezzo concatenerebbe le due metà.
Tre trattini scritti come testo nella cella sono un’altra trappola in Hugo. Il tipografo riscrive --- in una cella come un trattino lungo (—). Uno span di codice mantiene i trattini. \--- è stato renderizzato come -–.
| As text | As code |
| ------- | ------- |
| --- | `---` |
Celle unite
GFM non supporta rowspan o colspan. Quando una cella deve coprire due righe, la tabella deve essere in HTML. Il renderer non sicuro di questo sito lascia tale HTML nella pagina:
<table>
<tr>
<td rowspan="2">Merged</td>
<td>Cell 1</td>
</tr>
<tr>
<td>Cell 2</td>
</tr>
</table>
Lo scrittore markdown+pipe_tables di Pandoc emette la sintassi a barre verticali per questa pagina. È questo lo scrittore utilizzato quando si convertono documenti Word in Markdown. Le tabelle a griglia e altri layout esclusivi di Pandoc sono funzionalità del dialetto, illustrate in GFM vs CommonMark vs Pandoc Markdown.
Una tabella a barre verticali larga viene scorciata o sfora i limiti. Le riduzioni portatili sono un layout trasposto, diverse tabelle più piccole o una tabella HTML con il proprio CSS. La sintassi a barre verticali non ha una didascalia. L’indice dei contenuti di Hugo è costruito dai titoli.
Verifiche quando una tabella resta testo
Conta le celle nella riga di intestazione e nella riga di separatori. Se questi due conteggi differiscono, il blocco è un paragrafo. Una riga di dati corta è comunque una tabella, con una cella vuota alla fine. La regola MD056 di markdownlint richiede comunque che ogni riga corrisponda a quel conteggio, perché una riga corta sembra una cella mancante e una cella extra viene scartata.
Osserva la riga di separatori per i due punti. Un due punti nella riga di intestazione è testo e la colonna mantiene l’allineamento definito dalla riga di separatori.
Se --- all’interno di una cella appare come un singolo glifo di trattino su questo sito, il tipografo lo ha riscritto. Metti i trattini in uno span di codice.
Se GitHub mostra le barre verticali come testo, aggiungi la riga vuota richiesta dalla documentazione di GitHub e usa almeno tre trattini in ogni cella della riga di separatori. Hugo 0.164 accettava già la forma più corta.
La mancata presenza della riga di separatori è un altro modo in cui un blocco a barre verticali resta testo. Hugo 0.164 ha lasciato questo come un paragrafo:
| Header 1 | Header 2 |
| Cell A | Cell B |
Una tabella dei parametri
La stessa riga di separatori porta l’allineamento e lascia spazio per il codice inline:
| Parameter | Type | Default | Required |
| :-------- | :------ | :-----: | :------: |
| `apiKey` | string | — | Yes |
| `timeout` | number | 30000 | No |
| `retries` | number | 3 | No |
