Blocchi di codice Markdown - Foglio di riferimento e esempi di utilizzo

Ecco qui 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. Questa guida fa parte del nostro Strumenti di Documentazione nel 2026: Markdown, LaTeX, PDF e Flussi di Lavoro per la Stampa hub.

Blocchi di codice Markdown

I blocchi di codice Markdown sono un modo per visualizzare codice o testo preformattato all’interno dei documenti Markdown, preservando la formattazione e abilitando eventualmente la colorazione della sintassi. Esistono 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 backtick (`) 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 la colorazione della sintassi e sono meno comuni nel Markdown moderno.
• Blocchi di codice delimitati 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 immediatamente la lingua di programmazione dopo i backtick aperti per la colorazione della sintassi.
  • Preservano la formattazione e supportano il codice multi-riga.

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

Quando abbiamo il seguente testo formattato in Markdown:

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

Il testo visualizzato apparirà così:

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

Linee guida per l’uso dei blocchi di codice Markdown

• Utilizza blocchi di codice delimitati (tre backtick) per il codice multi-riga per garantire chiarezza e compatibilità su diverse piattaforme.
• Specifica la lingua dopo i backtick aperti per la colorazione 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 la colorazione della sintassi e possono essere meno leggibili.
• Inserisci una riga vuota prima e dopo i blocchi di codice delimitati per migliorare la leggibilità del Markdown grezzo.

Funzionalità speciali

• Alcune piattaforme supportano identificatori aggiuntivi per le lingue, come diff per mostrare modifiche al codice, che possono evidenziare le righe aggiunte o rimosse in una revisione del codice.
• Per visualizzare backtick all’interno di un blocco di codice, avvolgi il blocco in un numero maggiore di backtick (es. quattro backtick per visualizzare tre backtick).

OutTake

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

Colorazione della sintassi diff

Per utilizzare efficacemente la colorazione della sintassi diff nei blocchi di codice Markdown, segui questi passaggi:

• Utilizza blocchi di codice delimitati con tre backtick (```) per iniziare e terminare il tuo blocco.
• Specifica diff come identificatore di lingua immediatamente dopo i backtick aperti. Questo abilita la colorazione della sintassi per le differenze, simile a quanto si vede nei messaggi di commit Git o nelle richieste di pull.

Esempio:

- riga vecchia che verrà rimossa
+ riga nuova che verrà aggiunta
 riga non modificata

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

Linee guida:

• Utilizza questo formato per comunicare chiaramente modifiche al codice, correzioni o suggerimenti in documentazione, revisioni del codice o blog tecnici.
• Inserisci una riga vuota prima e dopo il tuo blocco di codice per una migliore leggibilità nel Markdown grezzo.
• Nota che la colorazione diff evidenzia solo intere righe in base al carattere iniziale; non evidenzia modifiche inline all’interno di una riga.

Consiglio:
Questo metodo è ampiamente supportato su piattaforme come GitHub, GitLab e molti renderer Markdown, rendendolo una scelta affidabile per condividere visivamente le modifiche al codice.

Lingue supportate

I blocchi di codice Markdown supportano una vasta gamma di lingue per la colorazione della sintassi, ma l’insieme esatto delle lingue supportate dipende dal renderer o dalla piattaforma che stai utilizzando. Il Markdown stesso non definisce quali lingue sono supportate; semplicemente passa l’identificatore della lingua al motore di rendering, che applica quindi la colorazione della sintassi appropriata. I blocchi di codice delimitati non definiscono un insieme fisso di lingue di programmazione ufficialmente supportate. Invece, l’elenco delle lingue supportate dipende dal renderer Markdown o dalla piattaforma che stai utilizzando (come GitHub, GitLab, VS Code, Typora, Quarto, ecc.).

Lingue comuni supportate su piattaforme principali (come GitHub, VS Code, Bitbucket, Docusaurus, ReadMe) includono:

• Web & Scripting: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programmazione: python (py), java, c, c++, 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: Utilizza il nome della lingua immediatamente dopo i tre backtick aperti:

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

Le seguenti lingue sono ampiamente supportate su MOLTI renderer Markdown:

Nota: L’identificatore effettivo può variare (es. js vs. javascript). La maggior parte dei renderer è case-insensitive per i nomi delle lingue.

Come trovare l’elenco completo delle lingue supportate:

• GitHub: Utilizza Linguist per la colorazione, supportando centinaia di lingue.
• VS Code & 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.

Punti chiave:

• La maggior parte delle piattaforme supporta tutte le principali lingue di programmazione, scripting e markup.
• Alcune piattaforme supportano anche formati per diagrammi e dati (come mermaid, geojson).
• L’identificatore della lingua è generalmente case-insensitive ma dovrebbe essere in minuscolo per la migliore compatibilità.
• Se utilizzi un identificatore di lingua non supportato, il blocco di codice verrà visualizzato come testo semplice.

Specificare il nome del file in un blocco di codice Markdown

Per specificare un nome del file in un blocco di codice Markdown, hai diverse opzioni, ma il metodo dipende dalla piattaforma e dal renderer:

1. Nome del file nell’etichetta del blocco di codice (sintassi meta)

Alcuni motori Markdown (come alcuni generatori di siti statici, strumenti di documentazione e piattaforme di blogging) supportano una sintassi meta in cui aggiungi il nome del file dopo la lingua, separato da un punto e virgola:

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

Questo visualizzerà il nome del file (es. app.js) sopra o accanto al blocco di codice, a seconda del renderer. Tuttavia, il renderer Hugo di questa pagina non lo supporta:

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

Nota: Questo non è supportato su tutte le piattaforme (es. il Markdown di GitHub non lo supporta attualmente).

2. Titolo o codice in grassetto con il nome del file sopra il blocco di codice

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

**`app.js`**

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

O:

#### `app.js`

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

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

3. Nome del file come commento nel codice

In alternativa, puoi includere il nome del file come commento all’interno del blocco di codice stesso:

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

Questo è particolarmente utile se desideri che il nome del file sia visibile quando si copia il codice.

Riepilogo e linee guida

Utilizza un titolo o codice in grassetto sopra il blocco di codice per la massima compatibilità, e considera l’aggiunta di un commento all’interno del codice per la chiarezza quando si condividono informazioni su diverse piattaforme.

Link utili

• Strumenti di Documentazione nel 2026: Markdown, LaTeX, PDF e Flussi di Lavoro per la Stampa
• Foglio di riferimento Markdown - Strutture e comandi più utili
• Foglio di riferimento Hugo
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks