Markdown Guida ai blocchi di codice: codice in linea, blocchi recintati e sintassi evidenziata

La formattazione del codice è una delle caratteristiche più forti di Markdown. Sia che tu stia documentando una funzione, mostrando un comando terminale, o scrivendo un tutorial, la sintassi del codice Markdown mantiene il codice visivamente distinto, corretto formato e (sulla maggior parte delle piattaforme) sintassi evidenziata. Questa guida copre tutto ciò che riguarda Markdown blocchi di codice.

Codice in linea

Avvolgere un breve frammento o una singola espressione in singoli backtick:

Use `console.log()` to print output.
Set the variable with `const x = 42;`.
The file is saved as `README.md`.

Il codice in linea rende in un font monospaziale, visivamente distinto dal testo circostante. Utilizzalo per:

• Nome della funzione e del metodo: addEventListener()
• Nomi delle variabili: isLoading
• Nomi dei file: package.json
• Argomenti di comando: --verbose
• Espressioni di codice brevi

Se il tuo codice in linea contiene un backtick, usa doppi backtick per avvolgerlo:

`` `backtick inside` ``

Blocchi codici recintati

Per il codice a più righe, utilizzare il triplo backtick (`) per aprire e chiudere il blocco:

```
This is a code block.
It preserves all whitespace and line breaks.
No formatting is applied inside.
```

L'indentamento, l'intervallo e le nuove linee sono tutte conservate esattamente.

Sottolineamento della sintassi

Aggiungere un identificatore linguistico dopo l'apertura di tre backtick per abilitare l'accentuamento della sintassi:

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("World"))
```

```javascript
const greet = (name) => `Hello, ${name}!`;
console.log(greet("World"));
```

```bash
#!/bin/bash
echo "Hello, World!"
ls -la ~/Documents
```

Identificatori linguistici comuni

Blocchi di codice indentati

Una vecchia sintassi Markdown utilizza l'indentamento a 4 spazi per i blocchi di codice:

    function oldStyle() {
        return "This is a code block";
    }

Questo è compatibile con CommonMark ma meno leggibile e non supporta gli identificatori di lingua. Usate invece blocchi recintati (triplici bacchetti).

Convertire codice da Word documenti

Monospazio testo in Word (Courier Nuovo, Consolas, ecc.) converte in codice in linea quando si utilizza WordToMD. Multi-line code in Word converts depending on how it was formatted:

• Paragrafo di carattere monospaziale → Può diventare più frammenti di codice in linea
• Word Stile Codice → Converte in un blocco di codice
• Blocco di testo letterale → Potrebbe essere necessaria una recinzione manuale

Dopo la conversione, controllare le sezioni di codice e aggiungere, se necessario, una corretta recinzione:

1. Trova il codice che dovrebbe essere un blocco
2. Lo avvolgi con tre bacchette .
3. Aggiungere l'identificatore linguistico appropriato

Esempi specifici per le lingue

Richieste HTTP

```http
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer TOKEN

{
  "name": "Alice",
  "email": "alice@example.com"
}
```

Comandi terminali

```bash
npm install
npm run build
npm run dev
```

Diffusore

```diff
- const oldValue = "hello";
+ const newValue = "world";
  console.log(newValue);
```

Configurazione YAML

```yaml
server:
  host: localhost
  port: 8080
  debug: true
database:
  url: postgresql://localhost:5432/mydb
```

Blocchi di codice inseriti (per la documentazione)

Quando si documenta Markdown stesso, utilizzare 4 backtick per avvolgere un blocco che contiene 3 backtick:

````markdown
```python
# This is a code block inside documentation
```
````

Supporto alla piattaforma

Numeri di riga

Lo standard Markdown non supporta i numeri di riga nei blocchi di codice. Alcune piattaforme e generatori di siti statici aggiungono questo tramite plugin:

• Prism.js (utilizzato da molti SSG) aggiungere {numberLines: true} nella recinzione del codice
• GitHub nessun numero di riga nativo nel rendering Markdown (utilizzare invece GitHub Vista di colpa)
• GitBook numeri di riga tramite impostazioni di blocco di codice

Copiare il codice da blocchi

GitHub e molte piattaforme aggiungono un pulsante Copy ai blocchi di codice automaticamente. Questo è un miglioramento del rendering non richiede nulla di speciale nel tuo Markdown.

FAQ

Perché la mia sintassi del blocco di codice non è evidenziata? L'identificatore della lingua è mancante o sbagliato, oppure la piattaforma non supporta la lingua specifica. Controlla l'elenco di identificatori sopra.

Come faccio a mostrare i backtick all'interno di un blocco di codice? All'interno di un blocco di codice recintato, i backtick sono trattati come caratteri letterali. Solo la recinzione a tre bacchette ha bisogno di un trattamento speciale.

Il mio documento Word aveva un codice colorato con sintassi sottolineata. WordToMD conserverà i colori? Nessun blocco di codice Markdown non conserva la formattazione a colori. WordToMD converte il testo in un blocco di codice; il sottolineamento della sintassi viene quindi applicato dal renderer Markdown basato sull'identificatore della lingua.

Posso evidenziare linee specifiche all'interno di un blocco di codice? Lo standard Markdown non supporta questo. Alcune piattaforme (come Astro con Shiki, o Hugo) sostengono la linea sottolineando attraverso i commenti: {1,3-5} dopo l'identificatore della lingua.

Guida correlata

• Markdown Sintassi guida rapida Riferimento completo
• Word a API Documentazione Documentazione che richiede molta codifica
• Word a GitHub Markdown GitHub-specific code formatting

Conclusioni

I blocchi di codice di rilevamento sono semplici: backticks per il codice in linea, triple backticks con un identificatore linguistico per i blocchi. Dopo aver convertito un documento Word con WordToMD, verificare che il testo monospaziale sia stato corretamente inserito nella sintassi del codice, e aggiungere identificatori linguistici per una corretta sintassi evidenziata sulla piattaforma di destinazione.