Blocchi di codice Markdown: guida completa con sintassi, linguaggi ed esempi

I blocchi di codice delimitati (fenced code blocks) contengono sorgente multi-riga in Markdown. Il token dopo il delimitatore iniziale è un tag di linguaggio, e solo il renderer decide cosa evidenzia quel tag.

Questa guida fa parte di Strumenti per la Documentazione nel 2026: Markdown, LaTeX, PDF e Flussi di Lavoro per la Stampa.

GitHub cerca il tag di linguaggio con Linguist e le parole chiave in languages.yml. Hugo 0.164 passa lo stesso tag a Chroma. Un tag che Chroma non conosce resta comunque un blocco di codice, mostrato come testo semplice. Titoli, tabelle e altri tipi di blocco si trovano nella Scheda Rapida di Markdown.

Panoramica sui Blocchi di Codice in Markdown

Markdown ha tre modi per segnalare il codice. Il codice in linea (inline code) è una span all’interno di un paragrafo. Un blocco rientrato e un blocco delimitato sono entrambi multi-riga, e solo il blocco delimitato (fenced) ha un tag di linguaggio.

Un blocco rientrato non può contenere un linguaggio. CommonMark considera una riga rientrata di quattro spazi come codice e non fornisce nulla all’evidenziatore con cui fare il matching, il motivo per cui un blocco delimitato è la forma da usare quando l’esempio deve essere colorato.

Un delimitatore (fence) è una riga di almeno tre backtick o tre tilde, il codice, quindi una riga di chiusura dello stesso carattere, lunga almeno quanto quella iniziale. La riga di chiusura non ha una stringa di informazioni. Per mostrare un delimitatore a tre backtick all’interno dell’esempio, aprire e chiudere con quattro backtick. La documentazione di GitHub sui blocchi di codice richiede una riga vuota prima e dopo il delimitatore per rendere il file grezzo più leggibile; il delimitatore viene comunque analizzato senza quella riga vuota.

Quando la sorgente seguente è salvata come Markdown:

```python
def hello():
    print("Hello, world!")
```

questo sito Hugo lo renderizza come:

def hello():
    print("Hello, world!")

Il codice in linea usa la stessa regola dei backtick su scala ridotta. Una coppia di singoli backtick è sufficiente per git status. Quando la span stessa contiene un backtick, usare due backtick su ogni lato:

`` `codice` ``

Evidenziazione della Sintassi Diff

Un delimitatore contrassegnato diff è il modo in cui una modifica viene mostrata come testo. Il lessizzatore Chroma di Hugo accetta diff e udiff. GitHub evidenzia la stessa identica etichetta dalla sua lista di linguaggi.

- riga vecchia che verrà rimossa
+ nuova riga che verrà aggiunta
  riga invariata

Le righe che iniziano con - assumono lo stile di eliminazione, e le righe che iniziano con + assumono lo stile di inserimento. Una riga senza nessuno dei due prefissi è testo ordinario in quel lessizzatore. Il colore applica l’intera riga. Una parola modificata nel mezzo di una riga non viene contrassegnata singolarmente.

Identificatori di Lingua

La prima parola della stringa di informazioni è il linguaggio. La documentazione di Hugo considera quella parola insensibile alle maiuscole e minuscole. Se Chroma non ha un lessizzatore per essa, Hugo 0.164 emette un semplice <pre><code class="language-…"> senza involucro di evidenziazione. Un render locale di notalang lo ha fatto. guessSyntax è impostato di default su false, e la documentazione di Hugo afferma che solo cinque lessizzatori implementano il rilevamento automatico, quindi un tag omesso rimane testo semplice piuttosto che un linguaggio indovinato.

L’HTML prodotto da questi delimitatori usa la classe language-python e lo stesso token. Questa classe è ciò che un convertitore deve preservare quando trasforma una pagina evidenziata di nuovo in Markdown, ovvero la mappatura coperta in Conversione da HTML a Markdown con Python.

Gli identificatori sotto sono quelli elencati per quei linguaggi nella tabella Chroma di Hugo. In un render Hugo 0.164, cs, yml e markdown sono stati colorati anche laddove la tabella pubblicata stampa csharp, yaml e md.

I siti GitHub Pages che evidenziano ancora tramite Jekyll hanno bisogno dell’identificatore in minuscolo. La documentazione di GitHub stessa enuncia quel requisito separatamente dal rendering di github.com.

GitHub tratta anche alcuni delimitatori come diagrammi piuttosto che come sorgente colorata: mermaid, geojson, topojson e stl. La tabella Chroma di Hugo non elenca mermaid. Su un sito Hugo il delimitatore resta testo sorgente finché un hook di render, un shortcode o uno script non lo disegna. Il Guida Rapida e Scheda Rapida per i Diagrammi Mermaid copre quella configurazione.

Specificare un Nome File

Nessun elemento in CommonMark o nella documentazione di GitHub sui blocchi di codice trasforma la stringa di informazioni in un nome file. Le opzioni di evidenziazione di Hugo sono coppie di parentesi graffe come {linenos=inline}. Non includono un campo per il nome file.

Due punti dopo il linguaggio

Alcuni generatori trattano js:app.js come linguaggio più un nome:

```js:app.js
console.log("Hello, world!");
```

GitHub non lo fa. Hugo 0.164 mantiene l’intero token come classe dell’elemento di codice (language-js:app.js) e non stampa un nome file. Quali dialetti aggiungono significato oltre la prima parola è il confronto in GFM vs CommonMark vs Pandoc Markdown.

Nome sopra il delimitatore

Una riga di codice in linea in grassetto sopra il delimitatore mostra il nome su GitHub, su questo sito e in altri renderer CommonMark:

**`app.js`**

```js
console.log("Hello, world!");
```

Un titolo funziona allo stesso modo:

#### `app.js`

```js
console.log("Hello, world!");
```

Nome all’interno dell’esempio

Un commento nella prima riga viaggia con il codice quando qualcuno copia il blocco:

```js
// app.js
console.log("Hello, world!");
```

Fuga dai Backtick (Escaping Backticks)

Quattro backtick all’esterno mostrano un delimitatore a tre backtick, che è il modello per una pagina che documenta Markdown:

````markdown
```python
# Questo delimitatore a tre backtick è all'interno di un delimitatore a quattro backtick
print("hello")
```
````

Il delimitatore di chiusura deve essere lo stesso carattere di quello iniziale, e lungo almeno quanto quest’ultimo. Una chiusura più corta termina il blocco prematuramente e lascia il resto dell’esempio come paragrafi ordinari.

Opzioni di Evidenziazione di Hugo

Il config.toml di questo sito non ha un blocco [markup.highlight], quindi si applicano i valori predefiniti di Hugo: i blocchi delimitati sono evidenziati, lo stile è monokai, gli stili sono scritti in linea (noClasses true), e i numeri di riga sono disattivati. Hugo 0.164 colora ancora un delimitatore che chiede solo un linguaggio, come fa l’esempio Python sopra.

I numeri di riga e le righe enfatizzate sono opzioni tra parentesi graffe dopo il linguaggio. Questo delimitatore chiede numeri in linea e marca la riga 2:

```python {linenos=inline hl_lines=[2]}
def hello():
    print("Hello, world!")
```

1def hello():
2    print("Hello, world!")

linenos accetta inline, table, true o false. hl_lines è una lista di numeri di riga o intervalli. linenostart imposta il primo numero visualizzato. Le stesse chiavi sono insensibili alle maiuscole e minuscole. Lo shortcode highlight li accetta come una stringa singola tra virgolette, e quella stringa ha ancora renderizzato i numeri di riga su Hugo 0.164:

{{< highlight python "linenos=true,hl_lines=2" >}}
def hello():
    print("Hello, world!")
{{< /highlight >}}

Per spostare i colori in un stylesheet, impostare noClasses su false e generare il CSS. Hugo 0.164 accetta --mode e --modeSelector su quel comando:

hugo gen chromastyles --style=monokai --mode=light > assets/css/highlight.css
hugo gen chromastyles --style=monokai --mode=dark --modeSelector > assets/css/highlight-dark.css

--modeSelector delimita ogni regola sotto una classe di livello superiore come .dark .chroma. La lista dei flag è hugo gen chromastyles --help.

Quando il Delimitatore Sembra Errato

Controllare l’elemento generato prima di modificare l’esempio. Su questa versione di Hugo un linguaggio noto è un div.highlight il cui elemento di codice ha data-lang impostato sull’identificatore. Un identificatore sconosciuto è un pre e code nudi con class="language-…", che è ciò che notalang ha prodotto.

Se il nome app.js manca e la classe è language-js:app.js, è stata usata la forma con i due punti. Spostare il nome sulla riga sopra il delimitatore.

Se i delimitatori di un tutorial appaiono come paragrafi sparsi, il delimitatore esterno ha la stessa lunghezza di quello interno. Allungare il delimitatore esterno.

Se un breve comando inghiotte il backtick nel mezzo di una frase, la span ha bisogno di una coppia di backtick più lunga del carattere che contiene.

Link Utili

• https://www.markdownguide.org/extended-syntax/
• https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks
• https://gohugo.io/content-management/syntax-highlighting/