Come andare a capo in Markdown

Hai premuto Invio, le due righe sono diventate un unico paragrafo, e niente somiglia a come l’avevi scritto. È la prima cosa che sorprende chiunque, con il Markdown, ed è voluta: un solo a capo nel sorgente viene trattato come uno spazio normale, così puoi mandare a capo i paragrafi lunghi dentro l’editor senza cambiare il risultato.

Per ottenere l’interruzione che volevi ci sono tre modi. Modifica il pannello qui sotto e guarda qual è quale.

Questa riga e questa
finiscono nello stesso paragrafo.

Una riga vuota sopra apre un nuovo paragrafo.

Due spazi in fondo alla riga  
forzano l'a capo dentro lo stesso paragrafo.

Anche una barra rovesciata funziona\
ed è più facile da vedere.

La regola che c’è dietro

Il Markdown ha due concetti diversi, e confonderli è esattamente quello che genera il problema:

• Un’interruzione di paragrafo mette uno stacco fra due blocchi di testo. Diventa due elementi <p> separati. Si ottiene con una riga vuota.
• Un’interruzione di riga va a capo dentro lo stesso paragrafo. Diventa un <br>. Si ottiene con due spazi finali o con una barra rovesciata.

Nella maggior parte dei casi quello che vuoi è l’interruzione di paragrafo, e basta una riga vuota.

Il problema dei due spazi

Due spazi a fine riga sono la sintassi originale, e funzionano quasi ovunque — ma sono invisibili. Non li vedi mentre scrivi, quasi tutti gli editor eliminano gli spazi finali quando salvano, e nessuna revisione del testo te li mostrerà mai. Un file che si compone correttamente sul tuo computer può smettere di funzionare in silenzio dopo che qualcun altro lo ha aperto.

La barra rovesciata è più recente, fa parte del CommonMark, e nel sorgente si vede. Se il tuo editor e la destinazione supportano il CommonMark — quasi tutti quelli moderni lo fanno — è preferibile. Se stai scrivendo per qualcosa di vecchio o insolito, usa i due spazi e disattiva la rimozione degli spazi finali nel tuo editor.

Le rose sono rosse  
Le viole sono blu

Le rose sono rosse\
Le viole sono blu

Il risultato è identico. Ma solo uno dei due sopravvive a un salvataggio.

Dove l’a capo conta davvero

Indirizzi, poesie, testi di canzoni e firme sono i casi in cui la differenza si vede e in cui un’interruzione di paragrafo sarebbe sbagliata: metterebbe uno stacco fra una riga e l’altra di un indirizzo, che non è un indirizzo ma un elenco di frammenti.

Carlo Di Giuseppe\
Via Roma 1\
00100 Roma

Nel resto della scrittura normale — un articolo, degli appunti, della documentazione — l’a capo forzato serve molto meno di quanto si creda. Se ti accorgi di usarlo spesso, spesso è il segno che volevi un elenco puntato.

Errori comuni

• Premere Invio due volte per “distanziare” e ottenere invece un nuovo paragrafo. È corretto: quello è il modo di separare due paragrafi. Righe vuote in più non aumentano lo stacco, ne bastano una.
• Aspettarsi che tre righe vuote diano tre stacchi. Il Markdown le riduce a una sola interruzione di paragrafo. Se ti serve spazio verticale reale, è una questione di stile del documento, non di sintassi.
• Fidarsi dei due spazi in un file condiviso. Vedi sopra: spariscono al primo salvataggio di qualcun altro.
• Andare a capo dentro un elenco senza indentare. Se continui una voce di elenco sulla riga dopo, indenta di due spazi, altrimenti il Markdown la legge come un nuovo paragrafo fuori dall’elenco.

Domande frequenti

Perché il Markdown ignora il mio a capo singolo?

Perché è progettato così: un solo a capo nel sorgente viene trattato come uno spazio, in modo che tu possa spezzare i paragrafi lunghi nell’editor senza cambiare il risultato composto. Per andare davvero a capo servono due spazi a fine riga o una barra rovesciata; per aprire un nuovo paragrafo, una riga vuota.

Che differenza c’è fra i due spazi e la barra rovesciata?

Nessuna nel risultato: entrambi producono un’interruzione di riga dentro lo stesso paragrafo. La differenza è pratica. I due spazi sono la sintassi originale e funzionano quasi ovunque, ma sono invisibili e molti editor li cancellano al salvataggio. La barra rovesciata è CommonMark, si vede nel sorgente e sopravvive a qualsiasi salvataggio.

GitHub gestisce gli a capo in modo diverso?

Sì, in alcuni contesti. Nei commenti alle issue, nelle pull request e nelle discussioni, GitHub converte un a capo singolo in un’interruzione di riga vera, perché nella scrittura conversazionale è quello che le persone si aspettano. Nei file .md del repository, invece, vale la regola standard. È il motivo per cui lo stesso testo si comporta in due modi diversi sullo stesso sito.

Come aggiungo una riga vuota fra due paragrafi in Markdown?

Lasciando una riga vuota fra i due. È l’unico modo previsto, ed è sufficiente: aggiungerne altre non produce più spazio, perché il Markdown le riduce comunque a una sola interruzione di paragrafo. Lo stacco visibile fra i paragrafi è deciso dallo stile del documento, non dal numero di righe vuote nel sorgente.

Posso scrivere un paragrafo su un’unica riga lunghissima?

Sì, ed è del tutto equivalente. Un paragrafo scritto su una riga sola e lo stesso paragrafo spezzato su otto righe si compongono in modo identico, perché gli a capo singoli valgono come spazi. La scelta è solo una questione di comodità: chi usa Git spesso preferisce spezzare le righe, perché rende molto più leggibile il confronto fra due versioni.