Sintassi base di Markdown: guida completa con esempi
Padroneggia ogni elemento della sintassi base di Markdown con esempi chiari e gli errori comuni da evitare. Il tuo riferimento definitivo per titoli, liste, link e molto altro.
La sintassi base di Markdown è il fondamento che ogni sviluppatore, scrittore e creatore di contenuti deve padroneggiare. Che tu stia scrivendo documentazione, creando un articolo per il blog o formattando una issue su GitHub, questi elementi fondamentali sono i mattoni che userai ogni giorno.
Questa guida esamina ogni elemento della sintassi base con esempi chiari, confronti con l'output HTML e gli errori comuni da evitare. Salvala tra i preferiti: ci tornerai più spesso di quanto pensi.
Titoli
I titoli strutturano il contenuto in una gerarchia logica. Markdown supporta sei livelli di titoli, creati posizionando i simboli # prima del testo.
# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6
Questo produce il seguente HTML:
<h1>Heading Level 1</h1>
<h2>Heading Level 2</h2>
<h3>Heading Level 3</h3>
<h4>Heading Level 4</h4>
<h5>Heading Level 5</h5>
<h6>Heading Level 6</h6>
Buone pratiche per i titoli
Aggiungi sempre uno spazio tra il # e il testo del titolo. Senza lo spazio, alcuni parser non lo riconosceranno come titolo.
✅ ## This Works
❌ ##This Doesn't
Usa i titoli in ordine. Non saltare da H2 a H4: questo rompe la struttura logica del documento e compromette sia l'accessibilità che la SEO. Pensa ai titoli come a un indice: ogni livello deve annidarsi logicamente sotto quello superiore.
Usa un solo H1 per pagina. L'H1 è il titolo della tua pagina. Tutto il resto dovrebbe essere H2 o inferiore.
Paragrafi e interruzioni di riga
I paragrafi sono l'elemento Markdown più semplice: basta scrivere del testo. Separa i paragrafi con una riga vuota.
This is the first paragraph.
This is the second paragraph.
Interruzioni di riga
Qui è dove molti principianti si confondono. Premere Invio una sola volta non crea una nuova riga nella maggior parte dei renderer Markdown. Devi fare una delle seguenti cose:
- Terminare una riga con due o più spazi (poi premere Invio)
- Usare il tag HTML
<br>
This is the first line.
This is the second line.
Or use HTML:<br>
This starts a new line.
Errore comune
Premere semplicemente Invio tra due righe le unirà in un unico paragrafo nell'output renderizzato:
Line one
Line two
Questo viene renderizzato come: "Line one Line two" — una singola riga. Usa sempre una riga vuota per un nuovo paragrafo o gli spazi finali per un'interruzione di riga all'interno dello stesso paragrafo.
Formattazione del testo
Markdown rende semplice enfatizzare il testo. Ecco le opzioni di formattazione principali:
Grassetto
Racchiudi il testo tra doppi asterischi o doppi trattini bassi:
**This is bold text**
__This is also bold__
Output HTML: <strong>This is bold text</strong>
Corsivo
Racchiudi il testo tra singoli asterischi o singoli trattini bassi:
*This is italic text*
_This is also italic_
Output HTML: <em>This is italic text</em>
Grassetto e corsivo
Combina tre asterischi per entrambi:
***Bold and italic***
___Also bold and italic___
**_Or mix like this_**
Output HTML: <strong><em>Bold and italic</em></strong>
Barrato
Usa le doppie tilde (questa è un'estensione GFM, ma supportata quasi ovunque):
~~This text is crossed out~~
Output HTML: <del>This text is crossed out</del>
Errore comune
Usare i trattini bassi nel mezzo di una parola non funziona in modo affidabile. Usa gli asterischi per l'enfasi a metà parola:
✅ This is**very**important
❌ This is__very__important
Citazioni
Le citazioni si creano con il carattere >. Sono comunemente usate per citare fonti, evidenziare note importanti o richiamare l'attenzione su informazioni chiave.
> Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
> — John Gruber
Output HTML:
<blockquote>
<p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
— John Gruber</p>
</blockquote>
Citazioni multi-paragrafo
Aggiungi > sulla riga vuota tra i paragrafi:
> First paragraph of the quote.
>
> Second paragraph of the quote.
Citazioni annidate
Usa >> per l'annidamento:
> This is the outer quote.
>
>> This is a nested quote inside it.
Citazioni con altri elementi
Puoi combinare le citazioni con altre formattazioni Markdown:
> ### A Heading Inside a Quote
>
> - List item one
> - List item two
>
> Text with **bold** and *italic* formatting.
Liste
Le liste sono uno degli elementi Markdown più utilizzati. Ne esistono tre tipi: non ordinate, ordinate e liste di attività.
Liste non ordinate
Usa -, * o + come marcatori. Scegline uno e mantienilo per coerenza:
- First item
- Second item
- Third item
Output HTML:
<ul>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
</ul>
Liste ordinate
Usa i numeri seguiti da un punto. I numeri effettivi non contano: Markdown li numera automaticamente:
1. First step
2. Second step
3. Third step
Curiosamente, anche questo produce lo stesso output:
1. First step
1. Second step
1. Third step
Entrambi vengono renderizzati come una lista numerata correttamente 1-2-3. Tuttavia, la buona pratica è usare numeri sequenziali per migliorare la leggibilità del file sorgente.
Liste annidate
Indenta con due o quattro spazi per creare sotto-liste:
1. Main item
- Sub-item A
- Sub-item B
- Sub-sub-item
2. Another main item
Liste di attività
Le liste di attività (una funzionalità GFM) usano - [ ] per gli elementi non completati e - [x] per quelli completati:
- [x] Write the draft
- [x] Add code examples
- [ ] Proofread the article
- [ ] Publish
Errore comune
Dimenticare la riga vuota prima di una lista quando segue un paragrafo. Alcuni parser la richiedono:
✅ Here is my list:
- Item one
- Item two
❌ Here is my list:
- Item one
- Item two
Codice
La visualizzazione del codice è una delle funzionalità più potenti di Markdown, e renderla correttamente è importante per la leggibilità.
Codice inline
Racchiudi il codice tra singoli backtick per la visualizzazione inline:
Use the `print()` function to output text.
Output HTML: Use the <code>print()</code> function to output text.
Se il codice stesso contiene un backtick, usa i doppi backtick:
``There is a literal `backtick` here.``
Blocchi di codice
Per il codice su più righe, usa i tripli backtick (blocchi di codice delimitati) con un identificatore di linguaggio opzionale per la colorazione della sintassi:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
L'identificatore del linguaggio (javascript, python, html, css, bash, ecc.) abilita la colorazione della sintassi nella maggior parte dei renderer. Includilo sempre: migliora drasticamente la leggibilità.
Blocchi di codice indentati
Puoi anche creare blocchi di codice indentando ogni riga con quattro spazi o un tab:
function add(a, b) {
return a + b;
}
Tuttavia, i blocchi di codice delimitati sono fortemente preferiti perché supportano la colorazione della sintassi e non richiedono l'indentazione di ogni riga.
Link
I link sono essenziali per collegare i contenuti. Markdown supporta diversi formati di link.
Link inline
Il formato più comune — testo tra parentesi quadre, URL tra parentesi tonde:
[Visit Example](https://example.com)
Output HTML: <a href="https://example.com">Visit Example</a>
Link con titoli
Aggiungi un titolo tra virgolette dopo l'URL (appare come tooltip al passaggio del mouse):
[Visit Example](https://example.com "Example Website")
Link in stile riferimento
Per un testo sorgente più pulito quando hai molti link, usa lo stile riferimento:
I use [Google][1] and [GitHub][2] daily.
[1]: https://google.com "Google"
[2]: https://github.com "GitHub"
Questo mantiene i paragrafi puliti e raggruppa tutti gli URL in fondo — particolarmente utile nei documenti lunghi.
Link automatici
Racchiudi un URL o un'email tra parentesi angolari per il collegamento automatico:
<https://example.com>
<contact@example.com>
La maggior parte dei renderer moderni (come GitHub) crea automaticamente link anche dagli URL senza parentesi angolari, ma usarle garantisce la compatibilità.
Errore comune
Dimenticare che gli spazi negli URL richiedono la codifica. Usa %20 per gli spazi:
✅ [My Doc](files/my%20document.pdf)
❌ [My Doc](files/my document.pdf)
Immagini
Le immagini usano la stessa sintassi dei link, ma con un punto esclamativo ! davanti:
Output HTML: <img src="/path/to/image.webp" alt="Alt text describing the image">
Immagini con titoli
Immagini cliccabili
Combina la sintassi dei link e delle immagini per rendere un'immagine cliccabile:
[](https://example.com)
Buone pratiche per il testo alternativo
Scrivi sempre un testo alternativo descrittivo. Serve a due scopi fondamentali:
- Accessibilità — i lettori di schermo lo usano per descrivere le immagini agli utenti con disabilità visive
- SEO — i motori di ricerca lo usano per comprendere il contenuto delle immagini
✅ 
❌ 
❌ 
Linee orizzontali
Crea una linea orizzontale (interruzione tematica) per separare visivamente le sezioni. Usa tre o più trattini, asterischi o trattini bassi:
---
***
___
Tutti e tre producono lo stesso HTML: <hr>
Buona pratica: Usa --- in modo coerente e aggiungi sempre righe vuote prima e dopo:
Content above the rule.
---
Content below the rule.
Escape dei caratteri
E se volessi mostrare un asterisco o un simbolo cancelletto letterale senza attivare la formattazione Markdown? Usa una barra rovesciata \ prima del carattere:
\* This is not italic \*
\# This is not a heading
\- This is not a list item
Ecco l'elenco completo dei caratteri che puoi fare l'escape:
\ Backslash
` Backtick
* Asterisk
_ Underscore
{} Curly braces
[] Square brackets
() Parentheses
# Hash
+ Plus sign
- Hyphen
. Dot
! Exclamation mark
| Pipe
Tabella di riferimento rapido
Ecco ogni elemento della sintassi base in un'unica tabella per una consultazione veloce:
Element Syntax HTML
-------------- ------------------ -----------
Heading 1 # Text <h1>
Heading 2 ## Text <h2>
Heading 3 ### Text <h3>
Bold **text** <strong>
Italic *text* <em>
Bold + Italic ***text*** <strong><em>
Strikethrough ~~text~~ <del>
Blockquote > text <blockquote>
Ordered list 1. item <ol><li>
Unordered list - item <ul><li>
Inline code `code` <code>
Link [text](url) <a href>
Image  <img>
Horizontal rule --- <hr>
Line break spaces + Enter <br>
Metti in pratica
Ora che hai imparato ogni elemento della sintassi base di Markdown, è il momento di usarli. Ecco cosa fare:
-
Esercitati a scrivere: Crea un file
notes.mde prova ogni elemento della sintassi. Più scrivi, più diventerà naturale. -
Usa uno strumento di anteprima: L'anteprima Markdown integrata di VS Code (
Ctrl+Shift+V/Cmd+Shift+V) ti permette di vedere l'output renderizzato in tempo reale mentre scrivi. -
Converti e condividi: Quando il tuo documento Markdown è pronto per il mondo, trasformalo in un output professionale — converti Markdown in HTML per la pubblicazione web, genera un PDF per documenti pronti per la stampa, o esporta in Word per la modifica collaborativa.
-
Approfondisci: Una volta che ti senti a tuo agio con la sintassi base, immergiti nella nostra guida alla sintassi estesa di Markdown per tabelle, note a piè di pagina, liste di definizioni e altro ancora. Sei completamente nuovo con Markdown? Inizia con Cos'è Markdown per una panoramica generale.
La bellezza di Markdown è che questi elementi base coprono la grande maggioranza di tutto ciò che dovrai mai scrivere. Padroneggiandoli una volta, li userai ovunque — da GitHub a Notion, dalla documentazione agli articoli di blog come questo.