La maggior parte dei documenti inizia come un semplice file di testo con qualche asterisco e cancelletto. Quel file è solitamente Markdown. Non è l'unico modo di scrivere per il web, ma è il formato predefinito per README, issue tracker, chatbot e siti statici, perché il sorgente è leggibile prima di essere renderizzato.
Questo articolo è un tutorial rapido e pratico. Si presume che tu abbia dieci minuti e un editor di testo. Nessuna installazione richiesta.
Cos'è Markdown
Markdown è una sintassi di markup leggera. John Gruber pubblicò la specifica originale nel 2004 con un obiettivo: un formato che fosse leggibile in testo semplice e si convertisse pulitamente in HTML. Da allora è diventato il formato di input per GitHub, Obsidian, Notion, molti generatori di siti statici e la maggior parte degli output dei grandi modelli di linguaggio.
L'idea di base è semplice. Si marca la struttura con segni di punteggiatura invece che con tag:
# Questo è un titolo
Questo è un paragrafo.
- Questo è un elemento di elenco
- Questo è un altro elemento
Un parser trasforma questo in HTML. Diversi parser supportano diverse estensioni, ed è qui che entrano in gioco gli standard.
Gli standard Markdown contano
Markdown non ha un unico standard ufficiale. La specifica originale di Gruber lascia delle lacune che diversi strumenti hanno colmato in modo incompatibile. Se scrivi una tabella in un'applicazione e la incolli in un'altra, potrebbe rompersi. Devi sapere a quale dialetto ti stai rivolgendo.
- CommonMark. Una specifica rigorosa e ben testata avviata nel 2014. Definisce con precisione la sintassi di base. Se vuoi portabilità, scrivi in CommonMark.
- GitHub Flavored Markdown (GFM). Aggiunge tabelle, elenchi di attività, testo barrato, blocchi di codice recintati e autolink. È quello che vedi nei README e nei commenti delle issue di GitHub.
- Pandoc Markdown. Aggiunge citazioni, note a piè di pagina, elenchi di definizioni, pedici, apici e matematica. Comune nella scrittura accademica.
- Obsidian / Quarto / MDX. Aggiungono wikilink, callout, celle di codice eseguibili o componenti incorporati. Sono potenti ma poco portabili.
Per il lavoro quotidiano, GFM è il bersaglio più sicuro. Per documenti lunghi che potrebbero spostarsi tra strumenti diversi, è meglio CommonMark più un insieme documentato di estensioni.
Basi di Markdown
Titoli
Usa da uno a sei cancelletti. Uno è il titolo più grande.
# Titolo 1
## Titolo 2
### Titolo 3
Paragrafi e interruzioni di riga
Separa i paragrafi con una riga vuota. Termina una riga con due spazi o una barra rovesciata per forzare un'interruzione di riga.
Questo è il primo paragrafo.
Questo è il secondo.
Enfasi
_corsivo_ o _corsivo_
**grassetto** o **grassetto**
**_grassetto e corsivo_**
~~barrato~~ (solo GFM)
Elenchi
Gli elenchi non ordinati usano -, * o +:
- Elemento uno
- Elemento due
- Elemento annidato
Gli elenchi ordinati usano numeri:
1. Passo uno
2. Passo due
3. Passo tre
I numeri non devono essere corretti. Markdown li rinumererà al rendering. Usa comunque numeri sequenziali per rendere il sorgente leggibile.
Link e immagini
[Testo del link](https://example.com)
[Link con titolo](https://example.com "Titolo")
Per i link interni, usa percorsi relativi:
[Converti Markdown in PDF](/tools/markdown-to-pdf)
Codice
Il codice inline usa backtick singoli: `console.log("hi")`.
I blocchi di codice usano tre backtick:
```python
def hello():
return "hello"
```
Aggiungi un identificatore di lingua dopo i backtick di apertura in modo che l'evidenziazione della sintassi funzioni.
## Trucchi comuni ed esempi
### Citazioni
```markdown
> Questa è una citazione.
> Può estendersi su più righe.
Puoi annidarle:
> Citazione esterna
>
> > Citazione annidata
Linee orizzontali
---
Usa tre o più trattini, asterischi o trattini bassi da soli su una riga.
Elenchi di attività
GFM supporta le caselle di controllo:
- [x] Scrivere la bozza
- [ ] Controllare le tabelle
- [ ] Pubblicare l'articolo
Vengono renderizzate come caselle di controllo disabilitate in HTML. Non usarle come sostituto di veri campi di input.
Escape di caratteri
Fai precedere i caratteri Markdown da una barra rovesciata quando vuoi che appaiano letteralmente:
\*non corsivo\*
\# non un titolo
Trucchi avanzati ed esempi
Tabelle
Le tabelle sono un'estensione GFM, non parte della specifica Markdown originale.
| Funzionalità | CommonMark | GFM |
| ------------------- | ---------- | --- |
| Tabelle | No | Sì |
| Elenchi di attività | No | Sì |
L'allineamento è opzionale:
| Sinistra | Centro | Destra |
| :------- | :----: | -----: |
| A | B | C |
Mantieni le tabelle semplici. Tabelle annidate, celle unite per righe o colonne non sono standard e spesso falliscono.
Note a piè di pagina
Pandoc e alcuni parser GFM supportano le note a piè di pagina:
Qui c'è un'affermazione.[^1]
[^1]: Questo è il testo della nota.
Se hai bisogno di note a piè di pagina in un PDF renderizzato, usa un convertitore che supporti la sintassi Pandoc o inseriscile manualmente.
Matematica
Pandoc e molti editor moderni supportano la matematica LaTeX:
Matematica inline: $E = mc^2$
Matematica in blocco:
$$
\int_a^b f(x) \, dx = F(b) - F(a)
$$
Il rendering matematico dipende dal parser e dal formato di output. HTML di solito richiede MathJax o KaTeX. I convertitori PDF spesso richiedono un backend LaTeX.
Elenchi di definizioni
Un'altra estensione di Pandoc:
Termine
: Definizione del termine.
Altro termine
: Un'altra definizione.
HTML dentro Markdown
Quando Markdown non basta, puoi usare HTML direttamente:
<p style="color: red;">Questo testo è rosso.</p>
Funziona per layout, video incorporati o attributi che Markdown non supporta. Ma riduce la portabilità, quindi usalo con parsimonia.
Quando convertire Markdown
Markdown è eccellente per scrivere e il controllo delle versioni. È scarso per documenti finali che devono apparire identici ovunque. Per questo esistono i convertitori.
Se hai una bozza Markdown da trasformare in un PDF condivisibile, usa il convertitore Markdown in PDF. Funziona nel browser, quindi il tuo file non lascia mai la tua macchina.
Se parti da un PDF e vuoi Markdown modificabile, usa il convertitore PDF in Markdown. Estrae titoli, elenchi e paragrafi senza caricare nulla su un server.
Cheatsheet Markdown
| Elemento | Sintassi | Output di esempio |
|---|---|---|
| Titolo 1 | # H1 | H1 |
| Titolo 2 | ## H2 | H2 |
| Titolo 3 | ### H3 | H3 |
| Grassetto | **bold** | bold |
| Corsivo | *italic* | italic |
| Barrato | ~~text~~ | |
| Codice inline | `code` | code |
| Link | [text](url) | text |
| Immagine |  | immagine |
| Citazione | > quote | citazione |
| Elenco non ordinato | - item | elemento di elenco |
| Elenco ordinato | 1. item | elemento di elenco |
| Linea orizzontale | --- | linea orizzontale |
| Blocco di codice | ```lang | blocco con evidenziazione |
| Elenco attività | - [ ] task | casella di controllo |
| Tabella | | a | b | | tabella |
Stampa questa tabella, attaccala vicino al monitor e raramente avrai bisogno di cercare di nuovo la sintassi Markdown.
Note finali
Markdown premia la contenione. Usa la sintassi di base per il 90% di ciò che scrivi. Ricorri a tabelle, note a piè di pagina e HTML solo quando il documento ne ha davvero bisogno. Se ti attieni a CommonMark o GFM, i tuoi file si sposteranno tra editor, piattaforme e convertitori senza sorprese.
