Anteprima Markdown

Sull'anteprima Markdown

Markdown è il modo meno faticoso di scrivere documentazione, guide e README: testo semplice, facile da modificare, facile da versionare. Il problema è che mentre scrivete non vedete il risultato. Questo strumento colma il vuoto: digitate a sinistra, vedete a destra.

Sintassi supportata

• Titoli: da uno a sei # a inizio riga per H1–H6. Notate che lo spazio dopo il # è obbligatorio.
• Enfasi: *corsivo*, **grassetto**, ***grassetto corsivo***, ~~barrato~~.
• Elenchi: - o * avvia un elenco puntato, 1. uno numerato; rientrate di quattro spazi o una tabulazione per annidare.
• Elenchi di attività: - [ ] da fare e - [x] fatto vengono resi come caselle di controllo.
• Tabelle: celle separate da barre verticali, la seconda riga con --- segna l'intestazione e i due punti controllano l'allineamento.
• Codice: codice in linea tra backtick; codice su più righe delimitato da tre backtick, facoltativamente seguiti dal nome del linguaggio.
• Citazioni: un > iniziale, annidabili.
• Link e immagini: [testo](url) e ![alt](url).
• Riga orizzontale: tre o più -, * o _ su una riga a sé.

Come scrivere una tabella

Le tabelle sono la parte di Markdown che si sbaglia più spesso. Il formato è:

| Nome  | Team      | Importo |
|:------|:---------:|--------:|
| Alice | Sviluppo  |    1200 |
| Bob   | Marketing |     980 |

Tre punti: servono sia la riga di intestazione sia quella di separazione; i due punti nel separatore controllano l'allineamento (due punti a sinistra per allineare a sinistra, da entrambi i lati per centrare, a destra per allineare a destra); e conviene mantenere coerente il numero di barre per riga: il rendering sopravvive alle incoerenze, ma il sorgente si legge meglio quando è allineato.

Etichette di linguaggio sui blocchi di codice

Mettere il nome di un linguaggio dopo i tre backtick (come ```javascript) fa applicare la colorazione sintattica alla maggior parte degli editor. Questo strumento fornisce un suggerimento di stile corrispondente dal nome del linguaggio preservando il testo originale, così potete copiarlo altrove.

Notate che il contenuto dentro un blocco di codice non viene interpretato come Markdown, quindi scrivervi # o asterischi è sicuro: non diventeranno titoli o corsivi. È proprio per questo che log di errore o file di configurazione incollati appartengono a un blocco di codice.

La trappola del ritorno a capo

Nel Markdown standard un singolo ritorno a capo non produce un'interruzione di riga: serve una riga vuota per un nuovo paragrafo, oppure due spazi finali per un'interruzione forzata. È scomodo per chi è abituato a mandare a capo liberamente.

Perciò qui l'opzione «anche un singolo ritorno a capo interrompe» è attiva per impostazione predefinita, e corrisponde all'intuizione. Se state producendo un documento che deve essere strettamente conforme allo standard (per esempio per un generatore di siti statici), disattivatela.

Quando usare Markdown

• Adatto: documentazione tecnica, README, verbali di riunione, requisiti, bozze di post, note personali — tutto ciò che è ricco di contenuto, leggero di impaginazione e mantenuto nel tempo.
• Meno adatto: documenti formali che richiedono un controllo fine dell'impaginazione, testo e immagini mescolati o design multicolonna. Per quelli un word processor tradizionale è più diretto.

Esportazione e migrazione

Ci sono tre uscite:

• Copia Markdown: il sorgente in testo semplice, incollabile ovunque Markdown sia supportato.
• Copia HTML: il frammento HTML renderizzato, pronto da incorporare nella vostra pagina. Notate che non porta con sé alcun foglio di stile: il CSS per farlo bello lo fornite voi.
• Scarica .md: salvato come file per il versionamento o l'archiviazione.

Tutto avviene nel browser e nulla di ciò che scrivete lascia la vostra macchina. Per verificarlo aprite il pannello Rete con F12: digitando non viene inviata alcuna richiesta.

Strumenti correlati