Guida Markdown: primi passi

Markdown è una sintassi di formattazione in testo semplice che trasforma simboli digitati in documenti strutturati, e per imparare le basi bastano circa 10 minuti. John Gruber lo ha pubblicato a marzo 2004 con il contributo di Aaron Swartz, e 22 anni dopo formatta i file README su GitHub, le note in Obsidian e i post su Reddit. L'intero sistema si regge su due elementi: un file di testo salvato con estensione .md e un processore che converte quel testo in HTML. Tutto quello che leggerai qui sotto parte da questi due elementi.

Cos'è Markdown?

Markdown è un linguaggio di markup leggero nato nel 2004 che aggiunge istruzioni di formattazione al testo semplice tramite caratteri visibili come #, * e >. Un # all'inizio di una riga crea un titolo. Due asterischi attorno a una parola la rendono in grassetto. Un trattino apre un elenco puntato. La prima versione era un singolo script Perl, Markdown.pl, pubblicato sul sito Daring Fireball di Gruber.

I linguaggi di markup più pesanti, HTML e LaTeX tra questi, avvolgono i contenuti in tag e comandi che appesantiscono il file grezzo. Markdown ha scelto la strada opposta. Gruber ha progettato la sintassi attorno a un solo obiettivo: un file Markdown deve leggersi in modo pulito come testo semplice ancora prima di qualsiasi conversione. La riga ## Pricing è chiaramente un titolo anche per chi non ha mai sentito parlare di Markdown. Questa leggibilità è il motivo per cui il formato si è diffuso dai blog nel 2004 a GitHub nel 2008, a Stack Overflow nel 2010 e alle app per appunti come Obsidian e Joplin lungo tutti gli anni 2010.

In cosa Markdown si distingue dagli editor WYSIWYG

Un editor WYSIWYG come Microsoft Word o Google Docs applica la formattazione tramite i pulsanti della barra degli strumenti e nasconde le istruzioni; Markdown mantiene ogni istruzione visibile come caratteri nel file. WYSIWYG significa "what you see is what you get", cioè quello che vedi è quello che ottieni. In Word selezioni una frase e clicchi sul pulsante Grassetto, e il file registra quella scelta in XML binario che non vedrai mai. In Markdown digiti **data di lancio** e le due coppie di asterischi sono la formattazione.

La differenza emerge al momento del salvataggio. Un file .docx si apre correttamente in una lista ristretta di programmi, soprattutto Word, LibreOffice e Pages. Un file Markdown si apre in qualsiasi editor di testo uscito dagli anni 1970 in poi, da Notepad a vim a VS Code. Molti editor Markdown colmano il divario visivo con un'anteprima live a schermo diviso: sintassi grezza nel riquadro sinistro, risultato renderizzato nel riquadro destro, aggiornato a ogni battitura. Ottieni il riscontro immediato di Word con la trasparenza del testo semplice.

Perché usare Markdown

Chi scrive sceglie Markdown per quattro ragioni pratiche: portabilità, indipendenza dalla piattaforma, durata nel tempo e diffusione. Ognuna deriva dalla base in testo semplice.

• Portabilità. Un file Markdown passa da un'applicazione all'altra senza conversioni. Scrivi la bozza di un post in iA Writer, la modifichi in VS Code, la pubblichi con Ghost. Il file non cambia mai forma. I formati proprietari come .docx e .pages bloccano i contenuti nell'ecosistema di un singolo produttore.
• Indipendenza dalla piattaforma. Markdown funziona in modo identico su Windows 11, macOS, Linux, iOS e Android. Il file è testo UTF-8, quindi una nota digitata su un telefono nel 2026 si apre byte per byte identica su un desktop.
• Durata nel tempo. I software muoiono; i file di testo sopravvivono. WordPerfect dominava la videoscrittura nel 1990 e oggi i suoi vecchi file sono un progetto di recupero. Un file Markdown del 2004 si apre ancora in meno di un secondo, un dettaglio che conta per tesi, contratti e manoscritti di libri con orizzonti di 20 anni.
• Diffusione. Piattaforme come GitHub, GitLab, Reddit, Discord, Notion e Slack accettano input in Markdown. Impari la sintassi una volta sola e la riutilizzi su tutte.

Come funziona l'elaborazione di Markdown

Markdown diventa un documento formattato attraverso una pipeline in 4 passaggi: scrivi un file .md, un processore lo analizza, il processore genera HTML e un browser visualizza quell'HTML. Il processore, chiamato anche parser o implementazione, è il motore dentro ogni applicazione Markdown. Tra i processori più diffusi ci sono markdown-it, marked, cmark e Pandoc, e cmark converte un documento tipico in meno di 10 millisecondi.

Strumenti diversi mostrano porzioni diverse di questa pipeline. Un editor online con anteprima live esegue i passaggi da 2 a 4 in modo invisibile a ogni battitura. Un generatore di siti statici come Hugo esegue la stessa pipeline su centinaia di file con un solo comando di build. La pipeline in sé non cambia mai, e l'HTML prodotto si abbina a qualsiasi foglio di stile CSS o si converte ulteriormente in PDF, EPUB o .docx con uno strumento come Pandoc.

A cosa serve Markdown?

Markdown copre sette impieghi comuni: siti web, appunti, documenti, libri, presentazioni, email e documentazione tecnica. La stessa sintassi da 10 minuti li copre tutti e sette.

Siti web

I generatori di siti statici come Hugo, Jekyll ed Eleventy costruiscono interi siti web da cartelle di file Markdown. Jekyll, uscito nel 2008, alimenta GitHub Pages e il suo hosting gratuito. Anche le piattaforme di contenuti accettano Markdown: Ghost ha un editor Markdown nativo e WordPress lo accetta tramite il suo editor a blocchi. Un articolo di blog è un singolo file .md, e i sistemi di controllo versione come Git ne tracciano ogni modifica.

Appunti e documenti

Le app per appunti come Obsidian, Joplin, Bear e Simplenote salvano ogni nota come Markdown. Obsidian, in particolare, conserva ogni vault come cartella di file .md sul tuo disco, così una raccolta di 5.000 note resta ricercabile con strumenti standard. Per i documenti singoli, lettere, verbali di riunione e compiti, un editor Markdown esporta direttamente in PDF o HTML, e il PDF si stampa, si allega a un'email o si carica ovunque.

Libri e presentazioni

Leanpub trasforma una cartella di file Markdown in un ebook finito nei formati PDF ed EPUB, e Pandoc fa lo stesso dalla riga di comando. Con questo metodo alcuni autori hanno pubblicato romanzi completi e libri tecnici di 300 pagine. Per le slide, strumenti come Marp e Remark convertono un file Markdown in una presentazione, con un separatore --- per ogni slide, molto più rapida da rivedere di un file PowerPoint con 40 slide formattate a mano.

Email e documentazione tecnica

Le estensioni per browser come Markdown Here convertono Markdown in email HTML formattate dentro Gmail e altri client webmail. La documentazione è il terreno di casa di Markdown: GitHub renderizza un README.md in cima a ogni repository, e generatori come MkDocs, Docusaurus e Read the Docs costruiscono interi siti di documentazione da file sorgente .md. Docusaurus, rilasciato da Meta nel 2017, aggiunge versionamento e ricerca sopra semplici pagine Markdown.

Le versioni di Markdown: CommonMark e GFM

Un "flavor" di Markdown è una variante specifica della sintassi, e le due che contano di più sono CommonMark, specificata nel 2014, e GitHub Flavored Markdown, specificata nel 2017. La versione del 2004 di Gruber lasciava indefiniti alcuni casi limite, come l'indentazione degli elenchi annidati, quindi i primi processori producevano risultati diversi. Lo stesso file veniva renderizzato in modo diverso da strumenti diversi.

CommonMark ha risolto il problema. Pubblicata a settembre 2014 da un gruppo di lavoro che includeva John MacFarlane e Jeff Atwood, la specifica CommonMark fissa ogni regola di parsing attraverso più di 600 casi di test. Stack Overflow ha migrato il suo rendering a CommonMark a giugno 2020.

GitHub Flavored Markdown, o GFM, è un superset rigoroso di CommonMark che GitHub ha formalizzato a marzo 2017. Aggiunge cinque estensioni: tabelle, elenchi di attività, testo barrato, autolink e blocchi di codice delimitati con tag di linguaggio. Quando la pagina di un prodotto dichiara che "supporta Markdown", verifica quale flavor intende, perché una tabella GFM appare come semplici caratteri pipe in uno strumento solo CommonMark. GFM è la scelta più sicura nel 2026, ed è il flavor che l'editor di questo sito renderizza.

Come iniziare a scrivere in Markdown oggi

Apri un editor Markdown nel browser, digita un # seguito da un titolo e hai già scritto il tuo primo Markdown; non c'è niente da installare e nessun account da creare. Un editor a doppio riquadro mostra il risultato renderizzato mentre digiti, il ciclo di feedback più rapido per imparare la sintassi.

Parti dai cinque elementi più usati: # per i titoli, **grassetto**, *corsivo*, - per gli elenchi e [testo](url) per i link. Questi cinque coprono circa il 90% della formattazione quotidiana. Esercitati riscrivendo qualcosa di reale, un appunto di riunione o una lista di cose da fare, poi salva il risultato come file .md. Da lì la guida alla sintassi di base copre tutti i 9 elementi fondamentali, e la guida alla sintassi estesa aggiunge tabelle GFM, note a piè di pagina ed elenchi di attività.

Domande frequenti

Devo installare un programma per scrivere in Markdown?

Basta un browser web; un editor Markdown online gestisce scrittura, anteprima ed esportazione senza alcuna installazione. Le applicazioni desktop come Obsidian, iA Writer e VS Code aggiungono accesso offline e gestione dei file locali quando ne avrai bisogno.

Che estensione usa un file Markdown?

I file Markdown usano l'estensione .md, con .markdown come alternativa meno comune. Entrambe contengono lo stesso identico testo semplice, e ogni processore Markdown, da cmark a Pandoc, le accetta entrambe.

Quanto tempo serve per imparare Markdown?

I cinque elementi fondamentali richiedono circa 10 minuti, e l'intera sintassi di base di 9 elementi si impara in una sola sessione. Le estensioni GFM come tabelle ed elenchi di attività aggiungono altri 15 minuti. Confrontalo con LaTeX, dove una formattazione competente richiede settimane.

Qual è la differenza tra CommonMark e GFM?

CommonMark è la specifica di base del 2014 che standardizza il parsing fondamentale di Markdown, e GFM è il superset di GitHub del 2017 che aggiunge tabelle, elenchi di attività, testo barrato, autolink e blocchi di codice delimitati. Ogni documento CommonMark valido è anche GFM valido, quindi scrivere in GFM è la scelta pratica.