La guida completa al Markdown

Questa è la sintassi del Markdown per intero, con esempi che puoi modificare mentre leggi. Se non sai ancora cos’è, parti da cos’è il Markdown; se lo sai già, il prontuario in fondo è la tabella da tenere aperta le prime settimane.

Una regola vale più di tutte le altre e risolve da sola la maggior parte dei “perché non si formatta?”: lascia una riga vuota fra un blocco e l’altro — fra un paragrafo e un titolo, fra un titolo e un elenco, fra un elenco e il paragrafo dopo.

Provalo subito

# Titolo del documento

Un paragrafo con **grassetto**, *corsivo* e `codice`.

## Sezione

- Primo punto
- Secondo punto

1. Primo passo
2. Secondo passo

> Una citazione.

[Un collegamento](https://www.inkiostro.app)

Le basi

Titoli

Da uno a sei cancelletti all’inizio della riga, seguiti da uno spazio. Un cancelletto è il titolo principale, sei è il livello più profondo.

# Titolo di primo livello
## Titolo di secondo livello
### Titolo di terzo livello

Lo spazio dopo il cancelletto serve: #Titolo senza spazio in molti compositori resta testo. E usa un solo # per file, trattandolo come il titolo del documento: è quello che si aspettano sia i lettori sia gli strumenti che generano l’indice.

Grassetto, corsivo e barrato

*corsivo* oppure _corsivo_
**grassetto** oppure __grassetto__
***grassetto e corsivo***
~~barrato~~

Gli asterischi sono più sicuri dei trattini bassi: _ dentro una parola (nome_variabile_lunga) viene interpretato da alcuni compositori e da altri no. Con gli asterischi il problema non si pone.

Paragrafi e a capo

Una riga vuota apre un nuovo paragrafo. Un a capo singolo, invece, vale come uno spazio: non fa niente di visibile. Per forzare un a capo dentro lo stesso paragrafo servono due spazi a fine riga o una barra rovesciata.

→ Guida completa all’andare a capo — la trappola dei due spazi invisibili.

Elenchi

Elenco puntato con - (o *, o +), numerato con 1.:

- Primo
- Secondo
  - Annidato, indentato di due spazi
- Terzo

1. Primo passo
2. Secondo passo
3. Terzo passo

Curiosità utile: i numeri che scrivi non contano. Se scrivi 1. su tutte le righe, l’elenco viene comunque numerato 1, 2, 3 — comodissimo quando devi inserire un passo in mezzo e non vuoi rinumerare a mano.

Collegamenti

[testo del collegamento](https://esempio.it)
[con un titolo](https://esempio.it "Appare al passaggio del mouse")
<https://esempio.it>

L’ultima forma è il collegamento automatico: l’URL diventa cliccabile e resta visibile com’è.

Immagini

Come un collegamento, ma con un punto esclamativo davanti. Il testo fra parentesi quadre è il testo alternativo, quello che leggono i lettori di schermo e che appare se l’immagine non si carica — scrivilo sempre.

![Una descrizione dell'immagine](immagine.jpg)

Citazioni

> Una citazione su una riga.
>
> Su due paragrafi, con il segno anche sulla riga vuota.

Codice

Codice in linea fra apici inversi singoli, blocchi di codice fra tre apici inversi. Il nome del linguaggio dopo i tre apici accende l’evidenziazione della sintassi:

Il comando `git status` mostra lo stato.

```python
def saluta(nome):
    return f"Ciao, {nome}"
```

def saluta(nome):
    return f"Ciao, {nome}"

Linea orizzontale

Tre o più trattini su una riga da soli. Attenzione a una trappola: se la riga sopra non è vuota, --- non produce una linea ma trasforma quella riga in un titolo.

---

Caratteri da proteggere

Per mostrare un carattere del Markdown alla lettera, mettici davanti una barra rovesciata. \*niente corsivo\* si compone come *niente corsivo*.

Sintassi estesa

Oltre alla specifica originale, quasi tutti gli strumenti moderni supportano delle estensioni, rese popolari soprattutto dal GitHub Flavored Markdown (GFM). Queste sono quelle che vale la pena conoscere.

Tabelle

Si costruiscono con le barre verticali | e una riga di trattini che separa l’intestazione. I due punti nella riga di separazione decidono l’allineamento delle colonne:

| Funzione   | Gratis | Pro |
|:-----------|:------:|----:|
| Anteprima  |   ✓    |  ✓  |
| Export     |   ✓    |  ✓  |
| Modo focus |   —    |  ✓  |

Le barre non devono essere allineate nel sorgente: un editor con anteprima live compone la tabella ordinatamente in entrambi i casi.

→ Guida completa alle tabelle — allineamento, barre da proteggere e cosa le tabelle non sanno fare.

Caselle di spunta

Una voce di elenco con [ ] o [x]:

- [x] Scrivere la bozza
- [ ] Rileggerla
- [ ] Esportare in PDF

Note a piè di pagina

Un riferimento nel testo e la definizione dove preferisci nel documento:

Il Markdown è nato nel 2004.[^1]

[^1]: Da John Gruber, con il contributo di Aaron Swartz.

Collegamenti automatici e barrato

Il GFM rende cliccabili gli URL e gli indirizzi email scritti così come sono, e ~~testo~~ diventa barrato.

CommonMark, GFM e le altre varianti

Siccome la descrizione originale di Gruber lasciava aperti alcuni casi limite, è nato il CommonMark, che definisce il Markdown in modo preciso e non ambiguo. Quasi tutti gli editor moderni seguono il CommonMark e poi aggiungono estensioni. Il GitHub Flavored Markdown è CommonMark più tabelle, caselle di spunta, barrato e collegamenti automatici. Alcuni strumenti vanno oltre, con le formule LaTeX e i diagrammi — vedi le formule matematiche in Markdown.

In pratica: impara le basi e le estensioni GFM qui sopra e i tuoi documenti si comporranno correttamente quasi ovunque.

Prontuario Markdown

Tutto su una schermata: è la tabella da tenere a portata di mano.

Consigli per scrivere meglio in Markdown

• Lascia le righe vuote fra i blocchi: titoli, paragrafi, elenchi. È la correzione che risolve da sola quasi tutti i “perché non si compone?”.
• Usa un’anteprima live. Vedere il risultato mentre scrivi intercetta gli errori sul momento e ti lascia pensare alle parole.
• Resta portabile. Preferisci la sintassi universale e le estensioni GFM qui sopra, ed evita le stranezze di un singolo strumento, così i file si aprono puliti ovunque.
• Scrivi il testo alternativo su ogni immagine.
• Un solo # per file. Trattalo come il titolo del documento e struttura il resto con ## e ###.

Un buon editor rende tutto questo naturale: una barra di formattazione inserisce i simboli giusti, l’evidenziazione tiene leggibili i file lunghi, e l’anteprima mostra il risultato. Inkiostro fa esattamente questo su Mac, iPad e iPhone, e tiene anche un prontuario integrato a una scorciatoia di distanza.

Domande frequenti

Il Markdown è difficile da imparare?

No. Le cose essenziali — titoli, grassetto, corsivo, elenchi e collegamenti — si imparano in un paio di minuti e coprono quasi tutta la scrittura quotidiana. Il resto si aggiunge quando serve. Il Markdown è stato progettato apposta per essere leggibile come testo semplice, quindi anche il sorgente grezzo si segue facilmente.

Che differenza c’è fra Markdown e CommonMark?

Il Markdown è la sintassi originale del 2004 di John Gruber. Il CommonMark è una specifica rigorosa e non ambigua di quella sintassi, creata perché ogni editor componesse lo stesso testo in modo identico. Quasi tutti gli strumenti moderni seguono il CommonMark e ci aggiungono sopra estensioni come le tabelle e le caselle di spunta.

Posso usare il Markdown per qualcosa di più degli appunti?

Sì. Il Markdown si usa per documentazione, articoli, libri, file README, testi tecnici con la matematica dentro. Con le estensioni aggiungi tabelle, note a piè di pagina, equazioni LaTeX e diagrammi, e poi esporti in PDF, HTML o EPUB: un appunto in testo semplice diventa un documento finito.

Come converto un file Markdown in PDF o Word?

Con un editor Markdown che esporta. Inkiostro esporta in PDF, HTML, TXT e Markdown, e in EPUB con Pro, con il controllo su intestazioni, piè di pagina e margini — e mantiene formule, diagrammi e codice evidenziato come testo selezionabile nel PDF invece di appiattirli in immagini.

Quali caratteri devo proteggere in Markdown?

Metti una barra rovesciata davanti a qualsiasi carattere che vuoi mostrare alla lettera invece di far interpretare: più spesso *, _, #, `, [, ], (, ) e \. Per esempio \*stella\* mostra gli asterischi invece di mettere la parola in corsivo.

Perché il mio elenco non viene composto come elenco?

Quasi sempre manca la riga vuota fra il paragrafo precedente e la prima voce, oppure manca lo spazio dopo il trattino. -voce non è un elenco, - voce sì. Se l’elenco è annidato, controlla anche l’indentazione: servono due spazi per ogni livello.