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

Qui sto passando in rassegna le opzioni per i blocchi di codice in Markdown—come specificare il linguaggio di programmazione, la formattazione delle differenze (diff) e il nome del file nel blocco di codice.

Questa guida fa parte della nostra hub Strumenti di Documentazione nel 2026: Markdown, LaTeX, PDF & Flussi di Stampa.

Panoramica dei Blocchi di Codice Markdown

I blocchi di codice Markdown visualizzano codice o testo preformattato all’interno dei documenti Markdown, preservando la formattazione e abilitando opzionalmente l’evidenziazione della sintassi (syntax highlighting). Esistono due tipi principali di formattazione del codice in Markdown: codice inline e blocchi di codice.

Tipi di Blocchi di Codice Markdown

Differenze Chiave

• Il codice inline utilizza backtick singoli (`) ed è destinato a brevi frammenti di codice all’interno di una frase.
• I blocchi di codice indentati utilizzano quattro spazi o una tabulazione all’inizio di ogni riga. Non supportano l’evidenziazione della sintassi e sono poco comuni nel Markdown moderno.
• I blocchi di codice recintati (fenced) utilizzano tre backtick (```) o tilde (~~~) prima e dopo il codice. Questo è il metodo preferito, specialmente su piattaforme come GitHub, perché:
  • Sono più facili da leggere e scrivere.
  • È possibile specificare il linguaggio di programmazione immediatamente dopo i backtick di apertura per l’evidenziazione della sintassi.
  • Preservano la formattazione e supportano codice su più righe.

Esempio di un blocco di codice recintato con evidenziazione della sintassi:

Quando abbiamo il seguente testo formattato in Markdown:

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

Il risultato renderizzato appare così:

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

Best Practice per i Blocchi di Codice Markdown

• Utilizza blocchi di codice recintati (tre backtick) per il codice su più righe, per garantire chiarezza e compatibilità tra le piattaforme.
• Specifica il linguaggio dopo i backtick di apertura per l’evidenziazione della sintassi (es. ```python).
• Utilizza il codice inline per brevi frammenti o comandi all’interno del testo.
• Evita i blocchi di codice indentati a meno che non siano richiesti per la compatibilità con versioni precedenti, poiché non supportano l’evidenziazione della sintassi e possono essere meno leggibili.
• Inserisci una riga vuota prima e dopo i blocchi di codice recintati per migliorare la leggibilità nel Markdown grezzo.

Funzionalità Speciali

• Alcune piattaforme supportano identificatori di linguaggio aggiuntivi come diff per mostrare le modifiche al codice, che evidenziano le righe aggiunte o rimosse nelle revisioni del codice.
• Per visualizzare backtick all’interno di un blocco di codice, racchiudi il blocco in un numero maggiore di backtick (es. quattro backtick per visualizzare tre backtick all’interno).

Riepilogo di Riferimento Rapido

Utilizza i blocchi di codice recintati con un identificatore di linguaggio per la migliore leggibilità ed evidenziazione della sintassi. Riserva il codice inline per brevi frammenti e evita i blocchi indentati a meno che non sia necessario per la compatibilità.

I blocchi di codice si abbinano naturalmente con le tabelle in Markdown per creare documentazione tecnica ben strutturata.

Evidenziazione della Sintassi Diff

L’evidenziazione della sintassi Diff ti permette di mostrare chiaramente le modifiche al codice — utile nella documentazione, nelle revisioni del codice e nei blog tecnici.

• Utilizza blocchi di codice recintati con tre backtick (```) per iniziare e terminare il tuo blocco.
• Specifica diff come identificatore di linguaggio immediatamente dopo i backtick di apertura.

Esempio:

- old line that will be removed
+ new line that will be added
  unchanged line

• Le righe che iniziano con - sono evidenziate come eliminazioni (di solito in rosso).
• Le righe che iniziano con + sono evidenziate come aggiunte (di solito in verde).
• Le righe senza prefisso non sono evidenziate in modo speciale.

Best practice:

• Inserisci una riga vuota prima e dopo il tuo blocco di codice per una migliore leggibilità nel Markdown grezzo.
• Nota che l’evidenziazione diff colora solo intere righe in base al carattere iniziale; non evidenzia le modifiche inline all’interno di una riga.

Suggerimento: L’evidenziazione Diff è ampiamente supportata su GitHub, GitLab e la maggior parte dei renderer Markdown, rendendola una scelta affidabile per comunicare le modifiche al codice.

Linguaggi Supportati per l’Evidenziazione della Sintassi

L’insieme esatto dei linguaggi supportati dipende dal renderer o dalla piattaforma che utilizzi. Markdown passa l’identificatore di linguaggio al motore di rendering, che applica l’evidenziazione della sintassi appropriata. Questo è importante quando si converte HTML in Markdown con Python, poiché i tag <code> con attributi di classe linguistica (es. class="language-python") mappano direttamente su questi identificatori nel blocco recintato.

Linguaggi comunemente supportati sulle principali piattaforme (GitHub, VS Code, Bitbucket, Docusaurus, ReadMe):

• Web & Scripting: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programmazione: python (py), java, c, cpp (c++), csharp (c#), php, ruby, go, rust, scala, swift, kotlin, objective-c
• Dati & Query: sql, r, matlab
• Markup & Configurazione: markdown, ini, toml, dockerfile, makefile
• Speciali: diff, mermaid, geojson, topojson, stl (per diagrammi e visualizzazioni di dati su GitHub) — l’identificatore mermaid in particolare abilita il rendering completo dei diagrammi sulle piattaforme supportate; vedi il Quickstart e Cheatsheet per Diagrammi Mermaid per un riferimento completo della sintassi e una guida alla configurazione di Hugo
• Altri: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme, e molti altri

Come specificare un linguaggio:

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

Identificatori di linguaggio supportati nella maggior parte dei renderer:

Nota: La maggior parte dei renderer non distingue tra maiuscole e minuscole per i nomi dei linguaggi. Se utilizzi un identificatore non supportato, il blocco di codice verrà renderizzato come testo normale.

Come trovare l’elenco completo dei linguaggi supportati:

• GitHub: Utilizza Linguist, supportando centinaia di linguaggi.
• VS Code & molti renderer web: Utilizzano highlight.js o Pygments—consulta la loro documentazione per liste esaustive.
• Bitbucket: Si riferisce alle modalità CodeMirror e ai lexer Pygments.

Specificare un Nome File in un Blocco di Codice Markdown

Visualizzare il nome del file accanto a un blocco di codice aiuta i lettori a identificare a quale file appartiene un frammento. Il supporto varia in base alla piattaforma.

1. Nome File nell’Etichetta del Blocco di Codice (Sintassi Meta)

Alcuni motori Markdown (certi generatori di siti statici e piattaforme di documentazione) supportano una sintassi meta in cui si aggiunge il nome del file dopo il linguaggio, separato da due punti:

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

Questo visualizza il nome del file sopra o accanto al blocco di codice. Il renderer Hugo di questo sito non lo supporta:

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

Nota: Questa funzionalità non è supportata nel Markdown flavor di GitHub.

2. Intestazione Manuale o Codice Inline per il Nome File

Per una compatibilità universale (inclusi GitHub, Stack Overflow e la maggior parte dei renderer Markdown), posiziona il nome del file sopra il blocco di codice utilizzando il codice inline in grassetto:

**`app.js`**

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

Oppure con un’intestazione:

#### `app.js`

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

Questo funziona ovunque e associa visivamente il nome del file al blocco di codice.

3. Nome File come Commento All’interno del Codice

Includi il nome del file come commento all’interno del blocco di codice stesso:

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

Questo è particolarmente utile quando si desidera che il nome del file sia visibile durante la copia del codice.

Riepilogo di Compatibilità

Utilizza il codice inline in grassetto sopra il blocco di codice per la massima compatibilità e considera un commento all’interno del codice per chiarezza quando si condivide tra piattaforme.

Escaping dei Backtick All’interno dei Blocchi di Codice

Per visualizzare le recinzioni di backtick all’interno di un blocco di codice — ad esempio quando si scrive documentazione su Markdown stesso — nidifica il blocco in un numero maggiore di backtick:

````markdown
```python
# This triple-backtick fence is inside a four-backtick fence
print("hello")
```
````

L’uso di quattro backtick come recinzione esterna ti permette di mostrare esempi di tre backtick all’interno, il che è utile per tutorial e cheat sheet di Markdown.

Specifico per Hugo: Lo Shortcode Highlight

Se utilizzi Hugo, lo shortcode integrato highlight offre più controllo rispetto ai semplici blocchi recintati, inclusi numeri di riga e righe evidenziate:

{{< highlight python "linenos=true,hl_lines=2 4" >}}
def greet(name):
    print(f"Hello, {name}!")

greet("world")
{{< /highlight >}}

Opzioni:

• linenos=true — mostra i numeri di riga
• hl_lines=2 4 — evidenzia le righe 2 e 4
• linenostart=10 — inizia la numerazione delle righe da 10

Questo è particolarmente utile nei tutorial o nella documentazione dove si vuole attirare l’attenzione su righe specifiche. Vedi il Markdown Cheatsheet per altre funzionalità di formattazione e il Hugo Cheat Sheet per un riferimento più ampio sui comandi e i template di Hugo.

Link Utili

• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks