Formati di file
Cos'è il Markdown? Sintassi, CommonMark e GFM
Il Markdown è un linguaggio di markup leggero che aggiunge titoli, elenchi e collegamenti al testo semplice con pochi simboli. Ne vediamo la storia, gli standard e cosa si conserva trasformando i file MD in Word o PDF.
Autore: Hemen Dönüştür Editör EkibiPubblicato: 8 min di lettura
Pensa al README di un progetto software, agli elenchi con titoli di un'app per appunti o alle parole che metti in grassetto con gli asterischi in un'app di messaggistica. Dietro a tutto questo c'è la stessa idea: il Markdown. Il Markdown è un linguaggio di markup leggero che permette di definire titoli, elenchi, collegamenti e tabelle aggiungendo pochi simboli al testo semplice. Il file resta leggibile in qualsiasi editor di testo, ma all'occorrenza può diventare una pagina HTML pulita, un documento Word o un PDF. In questo articolo vediamo come è nato il Markdown, la sua sintassi di base, le differenze tra CommonMark e GitHub Flavored Markdown e cosa controllare quando si convertono i file MD.
Cos'è il Markdown?
Il Markdown è sia un insieme di convenzioni di scrittura sia il nome comune degli strumenti che convertono in HTML i testi scritti seguendole. I file si salvano di solito con estensione .md o .markdown. Secondo il suo creatore, John Gruber, l'obiettivo principale del progetto è la leggibilità: un documento Markdown deve poter essere pubblicato così com'è, come testo semplice, senza sembrare pieno di tag o istruzioni di formattazione. Dove l'HTML richiede <strong>importante</strong>, il Markdown usa **importante**, e anche la versione grezza si legge in modo naturale.
Breve storia
John Gruber creò il Markdown nel 2004, con Aaron Swartz come interlocutore con cui confrontare le idee. La sintassi riprendeva le convenzioni delle email in testo semplice (asterischi per l'enfasi, trattini per gli elenchi) e linguaggi di markup precedenti come setext e Textile. La versione 1.0.1 di Markdown.pl, lo script Perl che Gruber pubblicò sul suo sito Daring Fireball, è datata 17 dicembre 2004.
La descrizione di Gruber, però, era una spiegazione per esempi più che una specifica formale. I casi ambigui (elenchi annidati, blocchi di codice rientrati, HTML mescolato al testo) portarono ogni implementazione a fare scelte proprie, e lo stesso testo cominciò a produrre risultati diversi in strumenti diversi. Seguirono due risposte importanti:
- CommonMark (2014): una specifica guidata da John MacFarlane che definisce il Markdown senza ambiguità e lo rende verificabile con centinaia di esempi. Le prime versioni uscirono nell'autunno 2014; quella attuale è la 0.31.2, del 28 gennaio 2024. La specifica non è ancora stata dichiarata 1.0.
- GitHub Flavored Markdown (GFM, 2017): la specifica formale di GitHub costruita sopra CommonMark. Aggiunge estensioni come tabelle, elenchi di attività, testo barrato, collegamenti automatici estesi e, per sicurezza, il filtraggio di alcuni tag HTML grezzi. L'ultima specifica pubblicata è la 0.29-gfm, del 6 aprile 2019.
Il Markdown ha ottenuto riconoscimento anche nell'infrastruttura di internet: la RFC 7763, pubblicata nel marzo 2016, ha registrato il tipo di media (tipo MIME) text/markdown con un parametro facoltativo variant che indica a quale variante di Markdown pensava l'autore.
Le principali varianti del Markdown
Oltre a CommonMark e GFM esistono altre varianti diffuse. La RFC 7764, pubblicata insieme alla RFC 7763, ne ha registrate diverse e ha fornito indicazioni d'uso:
- Markdown Extra: una delle prime estensioni, che aggiunse note a piè di pagina, elenchi di definizioni e tabelle.
- MultiMarkdown: una variante pensata per la scrittura accademica, con metadati, citazioni e riferimenti incrociati.
- Pandoc Markdown: la variante usata dal convertitore Pandoc, con molte estensioni per scrivere libri e articoli.
Una regola pratica: se il tuo documento usa solo titoli, elenchi, collegamenti, codice e tabelle semplici, apparirà uguale quasi ovunque. Se ti servono note a piè di pagina, elenchi di definizioni o tipi di blocco speciali, verifica quale variante supporta l'ambiente di destinazione.
Sintassi di base
La parte del Markdown che serve ogni giorno si impara in pochi minuti:
# Titolo di primo livello
## Titolo di secondo livello
Questo paragrafo contiene **grassetto**, *corsivo* e `codice`.
- Elenco puntato
- Secondo elemento
- Sottoelemento rientrato
1. Elenco numerato
2. Secondo passaggio
[Testo del collegamento](https://example.com)
> Citazione
```
Blocco di codice su più righe
```Tabelle ed elenchi di attività, aggiunti da GFM, hanno questo aspetto:
| Formato | Estensione |
|---------|------------|
| Markdown | .md |
| Testo semplice | .txt |
- [x] Scrivere la bozza
- [ ] RileggerlaI paragrafi sono separati da righe vuote. Nella maggior parte delle implementazioni un singolo a capo viene considerato parte dello stesso paragrafo; per forzare un'interruzione di riga, termina la riga con due spazi. Puoi anche scrivere HTML direttamente nel Markdown: CommonMark lo consente, anche se ambienti come GFM bloccano alcuni tag per sicurezza.
Dove si usa il Markdown?
- Sviluppo software: README, changelog e guide per i contributori, oltre a issue e commenti di code review su piattaforme come GitHub e GitLab.
- Documentazione tecnica: generatori di siti statici che creano siti web a partire da file Markdown.
- Appunti: molte app per appunti salvano o esportano le note in Markdown.
- Chat e community: piattaforme come Reddit e Discord usano varianti del Markdown.
- Scrittura ed editoria: produrre HTML, PDF, DOCX ed EPUB da un'unica fonte Markdown con strumenti come Pandoc.
- Strumenti di intelligenza artificiale: gli assistenti AI basati su chat formattano spesso le risposte in Markdown.
Punti di forza e punti deboli
| Punti di forza | Punti deboli |
|---|---|
| Leggibile anche in forma grezza | Le varianti si comportano in modo diverso |
| Testo semplice: leggero, portabile, adatto al controllo versione | Niente caratteri tipografici, colori o impaginazione |
| Si converte facilmente in HTML, PDF e Word | Niente tabelle complesse (celle unite) |
| Si impara in pochi minuti | Le immagini sono file separati |
| Non è legato a nessun programma | Errori di spaziatura e rientro cambiano il risultato |
Quali programmi aprono il Markdown?
Essendo testo semplice, il Markdown si apre in qualsiasi editor di testo, compresi il Blocco note e TextEdit. Per un'anteprima formattata puoi usare l'anteprima Markdown integrata in Visual Studio Code o editor dedicati come Obsidian e Typora. GitHub e GitLab visualizzano automaticamente i file .md nei repository. Word, invece, non apre il Markdown come testo formattato, quindi prima devi convertire il file.
Problemi comuni e come risolverli
Un elenco o un titolo non viene visualizzato
CommonMark richiede uno spazio dopo il simbolo del titolo: ## Titolo, non ##Titolo. Anche un elenco che segue un paragrafo spesso ha bisogno di una riga vuota in mezzo per essere visualizzato correttamente.
Le righe si uniscono
Un singolo a capo non divide un paragrafo. Lascia una riga vuota per iniziare un nuovo paragrafo, oppure termina la riga con due spazi per andare a capo all'interno del paragrafo.
Una tabella funziona su una piattaforma ma non su un'altra
Le tabelle non fanno parte del Markdown originale di Gruber né del nucleo di CommonMark; provengono da estensioni come GFM. Verifica quale variante supporta la piattaforma di destinazione.
Un paragrafo che inizia con un numero diventa un elenco numerato
Una riga come "2024. è stato un anno intenso" inizia con cifre seguite da un punto, quindi può essere interpretata come elenco. Per evitarlo, fai precedere il punto da una barra rovesciata (2024\.).
Consigli per convertire i file Markdown
Sul nostro convertitore i file Markdown vengono caricati sul nostro server ed eliminati entro 30 minuti. Per la lettura usiamo la libreria Markdig con CommonMark e le estensioni in stile GitHub (tabelle, elenchi di attività, note a piè di pagina, collegamenti automatici).
- Le conversioni da Markdown a PDF e da Markdown a Word mantengono titoli, elenchi, blocchi di codice, citazioni e tabelle con bordi. Le caselle degli elenchi di attività diventano i caratteri ☑ e ☐, così restano visibili in Word e in PDF. Per impostazione predefinita il testo è composto in un carattere con grazie da 12 pt e i blocchi di codice in un carattere a spaziatura fissa.
- La conversione da Markdown a HTML trasforma un README in una pagina web autonoma con la codifica dei caratteri dichiarata.
- Nella direzione opposta, le conversioni da Word a Markdown, da HTML a Markdown e da PDF a Markdown producono Markdown compatibile con GitHub: titoli, grassetto e corsivo, elenchi, tabelle, collegamenti, blocchi di codice e citazioni vengono mantenuti; caratteri, colori e impaginazione vengono eliminati. Nelle tabelle senza riga di intestazione, la prima riga diventa l'intestazione, perché le tabelle GFM ne richiedono una. I paragrafi normali che iniziano con un numero, come "1. Clausola", vengono protetti con l'escape perché non diventino elenchi per errore. Il file viene salvato in UTF-8 senza BOM.
Domande frequenti
Come apro un file MD?
Lo apre qualsiasi editor di testo. Per vederlo formattato usa l'anteprima di Visual Studio Code o un editor Markdown; se vuoi leggerlo in Word, convertilo in DOCX.
Che differenza c'è tra CommonMark e GitHub Flavored Markdown?
CommonMark definisce con regole precise la sintassi di base del Markdown. GFM è un sovrainsieme che aggiunge estensioni sopra CommonMark, come tabelle, elenchi di attività, testo barrato e collegamenti automatici estesi.
Si possono creare tabelle in Markdown?
Sì, con estensioni come GFM puoi scrivere tabelle semplici usando barre verticali e trattini. Per strutture complesse come le celle unite, usa una tabella HTML oppure prepara il documento in Word.
Che differenza c'è tra Markdown e HTML?
Il Markdown è un formato di scrittura più semplice, pensato per essere convertito in HTML. Non può esprimere tutto ciò che esprime l'HTML, ma la sua forma grezza è molto più leggibile. All'occorrenza puoi comunque scrivere HTML dentro il Markdown.
Il Markdown ha uno standard ufficiale?
La descrizione originale di Gruber non è una specifica formale. Oggi la definizione precisa più accettata è CommonMark, e il tipo di media text/markdown è stato registrato dalla RFC 7763 nel marzo 2016.
Fonti
- John Gruber, Daring Fireball: Markdown
- CommonMark Spec (cronologia delle versioni)
- GitHub Flavored Markdown Spec
- IETF RFC 7763: The text/markdown Media Type (marzo 2016)
- IETF RFC 7764: Guidance on Markdown
- Wikipedia: Markdown (storia, fonte secondaria)
- Markdig: a CommonMark-compliant Markdown processor for .NET
