Markdown è un modo di scrivere testo formattato usando soltanto caratteri normali. Un asterisco intorno a una parola la rende corsiva, un cancelletto a inizio riga crea un titolo, un trattino apre un elenco. Il file resta testo semplice: si apre con qualsiasi editor, si confronta riga per riga, si conserva per decenni senza dipendere da un programma. Poi, quando serve, lo si converte in HTML, PDF o in un documento di videoscrittura.
Nel mio lavoro lo uso per appunti, documentazione, bozze di articoli e verbali. Il vantaggio principale non è estetico: è che ci si concentra sulla struttura del testo invece che sull'aspetto.
Perché vale la pena impararlo
- Leggibile anche non convertito. Un file Markdown aperto in un blocco note si capisce lo stesso: la sintassi imita le convenzioni che si usavano già nelle email in testo semplice.
- Portabile. Non esiste un formato proprietario da aprire con il software giusto. Un
.mdscritto oggi sarà leggibile tra vent'anni. - Diffuso. Lo supportano piattaforme di sviluppo, app di note, generatori di siti statici, wiki e molti sistemi di messaggistica.
- Adatto al controllo di versione. Essendo testo, Git mostra esattamente quali righe sono cambiate tra due versioni.
I titoli
Si creano con uno o più cancelletti seguiti da uno spazio. Il numero di cancelletti indica il livello.
# Titolo del documento
## Capitolo
### Paragrafo
Due regole pratiche: lasciate sempre lo spazio dopo il cancelletto (alcuni interpreti non riconoscono ##Titolo) e non saltate livelli, per esempio passando da ## a ####. La gerarchia dei titoli serve anche a chi usa lettori di schermo e ai programmi che generano l'indice automatico.
Paragrafi e a capo
Un paragrafo è un blocco di righe separato da una riga vuota. Questo è il punto che confonde di più i principianti: andare a capo una volta sola, nella maggior parte degli interpreti, non crea una nuova riga nel risultato; le due righe vengono unite. Per iniziare un nuovo paragrafo serve una riga vuota.
Se avete davvero bisogno di un'interruzione di riga senza nuovo paragrafo (un indirizzo, una poesia), potete terminare la riga con due spazi o con una barra rovesciata, a seconda dell'interprete. Usatela con parsimonia.
Enfasi
*corsivo*oppure_corsivo_produce corsivo;**grassetto**produce grassetto;***entrambi***produce corsivo e grassetto insieme.
Il trattino basso all'interno di una parola (come in nome_file_finale) viene in genere ignorato dagli interpreti moderni, ma per sicurezza scegliete l'asterisco come convenzione e usatelo sempre.
Elenchi
Gli elenchi puntati iniziano con -, * o +; quelli numerati con un numero seguito dal punto.
- Primo punto
- Secondo punto
- Sotto-punto rientrato di due spazi
1. Preparare i file
2. Controllare i nomi
3. Archiviare
Un dettaglio utile: negli elenchi numerati conta soprattutto il primo numero. Potete scrivere 1. su ogni riga e l'interprete numererà comunque 1, 2, 3. Così, se inserite un passaggio in mezzo, non dovete rinumerare tutto a mano.
Link e immagini
Un link si scrive con il testo tra parentesi quadre e l'indirizzo tra parentesi tonde: [testo visibile](indirizzo). Le immagini usano la stessa forma preceduta da un punto esclamativo: .
Il testo tra parentesi quadre dell'immagine non è decorativo: diventa il testo alternativo. Scrivete una descrizione vera di ciò che l'immagine mostra, non «immagine1».
Citazioni e codice
Una citazione si ottiene premettendo > alla riga. Il codice in linea va tra apici inversi, come in `git status`. Per blocchi di codice si usano tre apici inversi prima e dopo, eventualmente con il nome del linguaggio per attivare l'evidenziazione della sintassi:
```python
print("ciao")
```
Dentro i blocchi di codice la formattazione Markdown non viene interpretata: asterischi e cancelletti restano tali. È il posto giusto per comandi, configurazioni e output da copiare esattamente.
Linee orizzontali e caratteri speciali
Tre trattini su una riga da soli (---) creano una linea di separazione. Attenzione: se li mettete subito sotto una riga di testo, alcuni interpreti trasformano quella riga in un titolo. Lasciate una riga vuota prima.
Se volete scrivere un asterisco o un cancelletto senza che vengano interpretati, premettete una barra rovesciata: \* mostra un asterisco normale.
Errori comuni
| Errore | Effetto | Correzione |
|---|---|---|
#Titolo senza spazio |
Testo normale con un cancelletto | # Titolo |
| Nessuna riga vuota prima di un elenco | L'elenco si fonde con il paragrafo | Aggiungere una riga vuota |
| Rientri incoerenti nei sotto-elenchi | Livelli sbagliati o elenco spezzato | Usare sempre lo stesso numero di spazi |
| Asterischi non chiusi | Corsivo che si estende al resto del testo | Controllare le coppie |
Quali strumenti usare
Per iniziare basta un qualsiasi editor di testo. Editor come VS Code mostrano un'anteprima affiancata; app di note come Obsidian o Joplin salvano direttamente in Markdown; per convertire in altri formati c'è Pandoc. Il consiglio è scegliere un solo strumento e scrivere per qualche settimana: la sintassi si memorizza in fretta, e dopo un po' diventa più veloce che usare i menu di formattazione.
In sintesi
- Markdown è testo semplice con poche convenzioni: leggibile, portabile e adatto a Git.
- Paragrafi separati da una riga vuota, titoli con
#e uno spazio, livelli senza salti. - Elenchi, link, immagini e codice hanno una sintassi breve e facile da ricordare.
- Il testo alternativo delle immagini va scritto con cura, non lasciato generico.
- I problemi più frequenti nascono da spazi mancanti e righe vuote dimenticate.
