Il Markdown originale era volutamente minimo: titoli, paragrafi, enfasi, elenchi, link e codice. Appena lo si usa per documenti reali, però, mancano pezzi importanti: una tabella di confronto, una nota a piè di pagina, una lista di cose da fare. Per questo sono nate le estensioni, cioè sintassi aggiuntive supportate da alcuni interpreti ma non da tutti.
Il primo concetto da fissare è proprio questo: Markdown non è uno standard unico. Esiste CommonMark, una specifica rigorosa della sintassi di base, e sopra di essa varianti come GitHub Flavored Markdown (GFM) o il Markdown di Pandoc, che aggiungono funzioni. Prima di usare un'estensione conviene sapere dove verrà letto il file.
Tabelle
Le tabelle a barre verticali sono l'estensione più diffusa. La seconda riga, fatta di trattini, separa l'intestazione dal corpo; i due punti indicano l'allineamento.
| Formato | Modificabile | Adatto all'archivio |
|:--------|:------------:|--------------------:|
| DOCX | sì | con riserva |
| PDF/A | no | sì |
| Markdown| sì | sì |
:---allinea a sinistra,:---:al centro,---:a destra.- Le barre non devono essere allineate a colpo d'occhio: l'interprete le riconosce lo stesso. Allinearle aiuta solo chi legge il sorgente.
- Il limite principale è che ogni cella sta su una riga. Niente elenchi o paragrafi dentro una cella, salvo trucchi poco portabili.
Se una tabella supera le cinque o sei colonne, nel sorgente diventa illeggibile. In quel caso valutate se il contenuto non sia meglio come elenco strutturato o come file CSV separato.
Note a piè di pagina
Molti interpreti, tra cui Pandoc e GFM, accettano le note con questa forma:
Il formato è stato standardizzato nel 2005.[^iso]
[^iso]: Si tratta della prima versione della norma ISO dedicata.
Il segnaposto [^iso] può essere un numero o una parola; la numerazione finale viene assegnata in automatico, nell'ordine in cui le note compaiono. Usare un'etichetta parlante, invece di [^1], rende più semplice spostare paragrafi senza confondersi.
Nelle pagine web le note finiscono in fondo al documento con un collegamento di ritorno; nella conversione in PDF diventano vere note a piè di pagina.
Liste di controllo
Le liste di controllo, o task list, sono un elenco puntato con una casella:
- [x] Raccogliere i requisiti
- [ ] Scrivere la bozza
- [ ] Revisione con il team
Sulle piattaforme di sviluppo le caselle diventano cliccabili e mostrano l'avanzamento. In un PDF o in un sito statico sono invece semplici simboli. Sono utilissime nei verbali di riunione e nei piani di rilascio, perché chi legge capisce subito cosa resta da fare.
Testo barrato, evidenziato e altre aggiunte
~~testo~~produce testo barrato in GFM e in Pandoc.==testo==per l'evidenziazione funziona in alcune app di note, ma non in GFM: è un esempio tipico di sintassi che si rompe cambiando strumento.- Gli indirizzi web scritti per esteso vengono trasformati in link automaticamente in GFM, ma non in CommonMark puro.
Elenchi di definizioni
Pandoc e altri interpreti supportano gli elenchi di definizioni, comodi per glossari:
Hash
: Impronta di lunghezza fissa calcolata da un contenuto.
Checksum
: Valore usato per verificare l'integrità di un file.
GFM non li riconosce: lì il risultato sarebbe un paragrafo con i due punti in vista.
Intestazione YAML
Molti generatori di siti e Pandoc leggono un blocco iniziale delimitato da tre trattini, con titolo, autore, data e altre informazioni:
---
title: "Manuale operativo"
author: "Ufficio tecnico"
lang: it
---
Questi metadati non compaiono nel corpo ma vengono usati per la copertina del PDF, il titolo della pagina web o i filtri di un archivio. Attenzione alle virgolette e ai due punti dentro i valori: un errore di sintassi YAML blocca spesso l'intera conversione.
Quale variante scegliere
| Destinazione | Variante consigliata | Note |
|---|---|---|
| Repository di codice | GFM | Tabelle, task list, barrato |
| Conversione in PDF o DOCX | Pandoc Markdown | Note, definizioni, citazioni, metadati |
| App di note | Quella dell'app | Verificare l'esportazione |
| Testo da far leggere a tutti | CommonMark | Massima compatibilità |
Nel mio lavoro tengo una regola semplice: se un documento deve passare tra strumenti diversi, uso solo tabelle, note e liste di controllo, che sono le estensioni più supportate, ed evito sintassi esotiche.
In sintesi
- Markdown ha più varianti: CommonMark per la base, GFM e Pandoc per le estensioni.
- Tabelle e note sono le estensioni più utili e più supportate, ma le celle restano su una riga.
- Le liste di controllo funzionano bene nei verbali e diventano interattive solo su alcune piattaforme.
- Elenchi di definizioni ed evidenziazione non sono portabili: verificate lo strumento di destinazione.
- L'intestazione YAML trasporta i metadati, ma un errore di sintassi può bloccare la conversione.
