Blocchi di Codice Markdown: Guida Completa con Sintassi, Linguaggi & Esempi

Ecco che sto rivedendo opzioni per i blocchi di codice in Markdown—come specificare la lingua di programmazione, il formato diff e il nome del file del blocco di codice.

Questo documento fa parte del nostro Strumenti di documentazione nel 2026: Markdown, LaTeX, PDF e flussi di lavoro per la stampa hub.

Panoramica dei blocchi di codice Markdown

I blocchi di codice Markdown visualizzano codice o testo preformattato all’interno dei documenti Markdown, mantenendo la formattazione e abilitando opzionalmente l’illuminazione della sintassi. Ci sono due tipi principali di formattazione del codice in Markdown: codice inline e blocchi di codice.

Tipi di blocchi di codice Markdown

Differenze principali

• Codice inline utilizza un singolo apice inverso (`) e serve per brevi frammenti di codice all’interno di una frase.
• Blocchi di codice indentati utilizzano quattro spazi o un tab all’inizio di ogni riga. Non supportano l’illuminazione della sintassi e sono rari nell’uso moderno di Markdown.
• Blocchi di codice delimitati utilizzano tre apici inversi (```) 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 immediatamente la lingua di programmazione dopo gli apici inversi per l’illuminazione della sintassi.
  • Mantengono la formattazione e supportano il codice multi-riga.

Esempio di un blocco di codice delimitato con illuminazione della sintassi:

Quando abbiamo il seguente testo formattato in Markdown:

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

L’output visualizzato è:

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

Linee guida per l’utilizzo dei blocchi di codice Markdown

• Utilizza blocchi di codice delimitati (tre apici inversi) per il codice multi-riga per garantire chiarezza e compatibilità tra le piattaforme.
• Specifica la lingua dopo gli apici inversi per l’illuminazione della sintassi (es. ```python).
• Utilizza codice inline per brevi frammenti o comandi all’interno del testo.
• Evita i blocchi di codice indentati a meno che non siano necessari per la compatibilità con le versioni precedenti, poiché non supportano l’illuminazione della sintassi e possono essere meno leggibili.
• Inserisci una riga vuota prima e dopo i blocchi di codice delimitati per migliorare la leggibilità nel Markdown grezzo.

Funzionalità speciali

• Alcune piattaforme supportano identificatori aggiuntivi per le lingue, come diff per mostrare le modifiche al codice, che evidenzia le righe aggiunte o eliminate nei rivedimenti del codice.
• Per visualizzare gli apici inversi all’interno di un blocco di codice, avvolgi il blocco in un numero maggiore di apici inversi (es. quattro apici inversi per visualizzare tre apici inversi all’interno).

Riepilogo rapido

Utilizza blocchi di codice delimitati con un identificatore di lingua per la migliore leggibilità e illuminazione della sintassi. Riserva codice inline per i frammenti brevi e evita i blocchi indentati a meno che non siano necessari per la compatibilità.

I blocchi di codice si abbinano naturalmente ai tabelle in Markdown per costruire documentazione tecnica ben strutturata.

Illuminazione della sintassi diff

L’illuminazione della sintassi diff ti permette di mostrare le modifiche al codice in modo chiaro — utile per la documentazione, i rivedimenti del codice e i blog tecnici.

• Utilizza blocchi di codice delimitati con tre apici inversi (```) per iniziare e terminare il blocco.
• Specifica diff come identificatore di lingua immediatamente dopo gli apici inversi di apertura.

Esempio:

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

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

Linee guida:

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

Consiglio: L’illuminazione diff è ampiamente supportata su GitHub, GitLab e la maggior parte dei renderer Markdown, rendendola una scelta affidabile per comunicare modifiche al codice.

Lingue supportate per l’illuminazione della sintassi

L’insieme esatto delle lingue supportate dipende dal renderer o dalla piattaforma che utilizzi. Markdown passa l’identificatore della lingua al motore di rendering, che applica l’illuminazione della sintassi appropriata. Questo è rilevante quando convertire HTML in Markdown con Python, poiché i tag <code> che portano attributi di classe per la lingua (es. class="language-python") si mappano direttamente a questi identificatori nei blocchi delimitati.

Lingue comuni supportate su piattaforme principali (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 & Config: markdown, ini, toml, dockerfile, makefile
• Speciali: diff, mermaid, geojson, topojson, stl (per diagrammi e visualizzazioni dati su GitHub)
• Altri: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme e molti altri

Come specificare una lingua:

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

Identificatori di lingua supportati da mostri renderer:

Nota: La maggior parte dei renderer è insensibile al caso per i nomi delle lingue. Se utilizzi un identificatore non supportato, il blocco di codice viene visualizzato come testo semplice.

Per trovare l’elenco completo delle lingue supportate:

• GitHub: Utilizza Linguist, che supporta centinaia di lingue.
• VS Code e molti renderer web: Utilizzano highlight.js o Pygments—vedi la loro documentazione per elenchi esaustivi.
• Bitbucket: Si riferisce a CodeMirror modes e a Pygments lexers.

Specificare un nome del 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 per la piattaforma.

1. Nome del 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 dove si appende il nome del file dopo la lingua, separato da un punto e virgola:

```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: Questo non è supportato dal Markdown di stile GitHub.

2. Intestazione o codice inline per il nome del file

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

**`app.js`**

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

O con un’intestazione:

#### `app.js`

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

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

3. Nome del 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 quando si copia il codice.

Riepilogo della compatibilità

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

Fuga di apici inversi all’interno dei blocchi di codice

Per visualizzare i recinti di apici inversi all’interno di un blocco di codice — ad esempio quando si scrive documentazione su Markdown stesso — annidare il blocco in un numero maggiore di apici inversi:

````markdown
```python
# Questo recinto di apici inversi triplo è all'interno di un recinto di quattro apici inversi
print("hello")
```
````

Utilizzare quattro apici inversi come recinto esterno permette di visualizzare esempi di apici inversi tripli all’interno, che è utile per tutorial e fogli di calcolo su Markdown.

Specifico di Hugo: Il breve codice highlight

Se utilizzi Hugo, il breve codice highlight integrato offre un controllo maggiore rispetto ai blocchi delimitati semplici, 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 — visualizza i numeri delle righe
• hl_lines=2 4 — evidenzia le righe 2 e 4
• linenostart=10 — inizia la numerazione delle righe da 10

Questo è particolarmente utile in tutorial o documentazione dove si desidera attirare l’attenzione su righe specifiche. Vedere il Foglio di calcolo Markdown per ulteriori funzionalità di formattazione, e il Foglio di calcolo di Hugo per un riferimento più ampio sui comandi e sulle template di Hugo.

Link utili

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