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

Qui sto rivedendo opzioni per i blocchi di codice in Markdown.

Blocchi di codice Markdown

I blocchi di codice Markdown sono un modo per visualizzare codice o testo preformattato all’interno dei documenti Markdown, mantenendo il formato 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 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 la colorazione della sintassi e sono meno comuni nel Markdown moderno.
• 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 il linguaggio di programmazione dopo gli apici inversi per la colorazione della sintassi.
  • Mantengono il formato 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 apici inversi) per il codice multi-riga per garantire chiarezza e compatibilità tra le piattaforme.
• Specifica il linguaggio dopo gli apici inversi per la colorazione 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 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à nel Markdown grezzo.

Funzionalità speciali

• Alcune piattaforme supportano identificatori aggiuntivi per i linguaggi, come diff per mostrare le modifiche al codice, che possono evidenziare 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).

OutTake

Utilizza blocchi di codice delimitati con un identificatore del linguaggio per la migliore leggibilità e colorazione della sintassi. Riserva codice inline per frammenti brevi 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 apici inversi (```) per iniziare e terminare il blocco.
• Specifica diff come identificatore del linguaggio immediatamente dopo gli apici inversi di apertura. 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, rivedimenti del codice o blog tecnici.
• Inserisci una riga vuota prima e dopo il blocco di codice per migliorare la leggibilità nel Markdown grezzo.
• Nota che la colorazione diff evidenzia solo intere righe in base al carattere iniziale; non evidenzia le 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.

Linguaggi supportati

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

Linguaggi comuni supportati su piattaforme principali (come GitHub, VS Code, Bitbucket, Docusaurus e 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 dei dati su GitHub)
• Altri: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme, e molti altri

Come specificare un linguaggio: Utilizza il nome del linguaggio immediatamente dopo i tre apici inversi di apertura:

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

I seguenti linguaggi sono ampiamente supportati da MOLTI renderer Markdown:

Nota: L’identificatore effettivo può variare (es. js vs. javascript). La maggior parte dei renderer è insensibile al caso per i nomi dei linguaggi.

Per trovare l’elenco completo dei linguaggi supportati:

• GitHub: Utilizza Linguist per la colorazione della sintassi, supportando centinaia di linguaggi.
• VS Code e molti renderer web: Utilizzano highlight.js o Pygments — consulta la loro documentazione per elenchi esaustivi.
• Bitbucket: Si riferisce a CodeMirror modes e a Pygments lexers.

Punti chiave:

• La maggior parte delle piattaforme supporta tutti i linguaggi di programmazione, scripting e markup principali.
• Alcune piattaforme supportano anche formati di diagramma e dati (come mermaid, geojson).
• L’identificatore del linguaggio è generalmente insensibile al caso, ma dovrebbe essere in minuscolo per la migliore compatibilità.
• Se utilizzi un identificatore di linguaggio non supportato, il blocco di codice verrà visualizzato come testo normale.

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 (ad esempio alcuni generatori di siti statici, strumenti di documentazione e piattaforme di blogging) supportano una sintassi meta in cui aggiungi il nome del file dopo il linguaggio, 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 da tutte le piattaforme (es. il Markdown di GitHub non supporta attualmente questa funzionalità).

2. Titolo o codice inline per il nome del file

Per una compatibilità universale (inclusi GitHub, Stack Overflow e la maggior parte dei renderer Markdown), posiziona il nome del file sopra al blocco di codice, utilizzando un titolo o codice inline 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 inline in grassetto sopra al blocco di codice per la massima compatibilità, e considera l’aggiunta di un commento all’interno del codice per la chiarezza quando si condividono contenuti su diverse piattaforme.

Link utili

• Foglio di appunti Markdown - Strutture e comandi più utili
• Foglio di appunti Hugo
• Foglio di appunti Bash - Comandi Bash più utili
• Foglio di appunti LaTeX
• Temi più popolari per Hugo
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks