Cos'è il
Markdown
Markdown è un modo per formattare il testo usando solo caratteri normali — senza aprire Word, senza toolbar, senza click. Scrivi **grassetto** e il testo diventa grassetto. Scrivi # Titolo e diventa un titolo grande. Semplice da scrivere, leggibile anche prima della formattazione.
Un file .md è un normale file di testo che chiunque può aprire con il Blocco Note. La differenza è che segue alcune convenzioni simboliche — # per i titoli, ** per il grassetto, - per le liste — che qualsiasi editor o piattaforma sa trasformare in una pagina formattata elegante.
Perché Markdown è diventato uno standard
- 📄Funziona ovunqueGitHub, Notion, Obsidian, LMS, Claude, ChatGPT, VS Code — tutti leggono e rendono Markdown nativamente.
- ⚡Veloce da scrivereNessun mouse, nessuna toolbar — le mani restano sulla tastiera mentre si formatta.
- 🔄Convertibile in tuttoDa un file .md puoi generare HTML, PDF, Word, slide — con un solo comando o strumento.
- 🛠️Perfetto per le skill ClaudeTutti i file SKILL.md, README, documentazione di progetto e dispense per LMS si scrivono in Markdown.
Le regole fondamentali
in 10 minuti
Tutta la sintassi Markdown che usi nel 90% dei casi si impara in pochi minuti. Ecco la cheat sheet completa con sorgente e anteprima affiancate.
**testo in grassetto** *testo in corsivo* ~~testo barrato~~ `codice inline` > Citazione o nota ---
testo in grassetto
testo in corsivo
testo barrato
codice inline
Citazione o nota
# Formattazione testo **grassetto** → testo in grassetto *corsivo* → testo in corsivo ~~barrato~~ → testo barrato `codice inline` → testo a larghezza fissa # Separatore --- → linea orizzontale # Citazione > testo citato → blocco indentato evidenziato # Interruzione di riga Riga 1 (due spazi) → a capo senza paragrafo Riga 2
Strutturare
i contenuti
I titoli e le liste sono gli elementi che usate di più in documenti didattici, README e dispense. Ecco come funzionano con anteprima immediata.
Titoli: da H1 a H6
# Titolo H1 → titolo principale, uno per documento ## Titolo H2 → sezione principale ### Titolo H3 → sottosezione #### Titolo H4 → sezione di dettaglio
Titolo H1
Titolo H2
Titolo H3
Liste non ordinate e ordinate
- Primo elemento - Secondo elemento - Sotto-elemento - Altro sotto 1. Primo passo 2. Secondo passo 3. Terzo passo
- Primo elemento
- Secondo elemento
- Sotto-elemento
- Altro sotto
- Primo passo
- Secondo passo
- Terzo passo
Molte piattaforme supportano le task list con - [ ] compito per checkbox vuota e - [x] compito per checkbox spuntata — utili per checklist in README e dispense interattive su LMS che le supportano (es. Notion, GitHub).
Collegare risorse
e organizzare dati
Link, immagini e tabelle sono gli elementi più potenti per creare dispense complete che includono risorse esterne e dati strutturati.
Link e immagini
# Link di testo [testo visualizzato](https://url-completo.it) # Link con titolo al passaggio del mouse [testo](https://url.it "Descrizione tooltip") # Immagine  # Immagine cliccabile (link + immagine combinati) [](https://destinazione.url)
Tabelle
| Strumento | Uso principale | Costo |
|-------------|-----------------|-----------|
| Claude | Scrittura e AI | Da $20/m |
| Notion | Note e database | Da $0 |
| VS Code | Codice e .md | Gratuito |
# Allineamento colonne
| Sinistra | Centro | Destra |
|:---------|:------:|-------:|
| testo | testo | testo |
| Strumento | Uso principale | Costo |
|---|---|---|
| Claude | Scrittura e AI | Da $20/m |
| Notion | Note e database | Da $0 |
| VS Code | Codice e .md | Gratuito |
Includere codice
e testo preformattato
I blocchi di codice sono essenziali nelle skill Claude, nei README tecnici e in qualsiasi dispensa che include prompt, comandi o snippet da copiare.
# Codice inline (una riga) Usa il comando `pip install requests` per installare. # Blocco di codice (più righe) — usa tre backtick ```python def saluta(nome): print(f"Ciao, {nome}!") saluta("Marco") ``` # Blocco senza evidenziazione specifica ``` testo preformattato senza colori specifici ``` # Lingue supportate per syntax highlighting ```python ```javascript ```html ```css ```bash ```json ```yaml ```sql
Nelle skill SKILL.md, i blocchi di codice sono fondamentali per includere template di output, esempi JSON, snippet HTML o prompt esatti che Claude deve usare come riferimento — resi a larghezza fissa e immediatamente distinguibili dal testo descrittivo.
Quando e perché
usare un file .md
Il Markdown non è solo per sviluppatori — è lo standard de facto per documentazione, README, dispense LMS, note personali e, in particolare, per tutte le skill e istruzioni per Claude.
| Caso d'uso | Perché .md è la scelta giusta |
|---|---|
| Skill Claude (SKILL.md) | Formato richiesto dal sistema — Claude legge la struttura Markdown per capire sezioni e priorità |
| README di progetto | GitHub, GitLab e Bitbucket lo renderizzano automaticamente come pagina formattata |
| Dispense LMS | Moodle, Canvas, Notion e altri accettano .md o lo convertono; facile da versionare con Git |
| Documentazione API | Standard per Swagger/OpenAPI, MkDocs, Docusaurus — tutti basati su Markdown |
| Note personali | Obsidian, Notion, Bear, Typora — tutti usano .md come formato nativo |
| Changelog e release notes | Formato standard su GitHub per documentare versioni e modifiche |
Usa .txt per contenuto grezzo senza formattazione. Usa .md quando la formattazione conta ma vuoi leggerezza, portabilità e compatibilità con sistemi tecnici. Usa .docx solo quando devi consegnare un documento formale a qualcuno che usa Microsoft Word o quando servono funzioni avanzate come revisioni tracciate o intestazioni pagina.
Dove scrivere
e visualizzare .md
Non serve alcuno strumento speciale per scrivere Markdown — qualsiasi editor di testo funziona. Ma alcuni strumenti rendono l'esperienza molto più piacevole con anteprima in tempo reale.
Da .md a PDF,
HTML e Word
Uno dei vantaggi principali di Markdown è la facilità di conversione in altri formati — con strumenti gratuiti e spesso con un solo comando.
Pandoc — lo strumento universale
Pandoc è uno strumento da riga di comando gratuito che converte tra 40+ formati. È lo standard de facto per chi lavora con documenti tecnici e accademici.
# Da Markdown a PDF pandoc documento.md -o documento.pdf # Da Markdown a Word (.docx) pandoc documento.md -o documento.docx # Da Markdown a HTML pandoc documento.md -o documento.html # Con stile personalizzato pandoc documento.md --css=stile.css -o documento.html
Alternative senza riga di comando
| Strumento | Come usarlo | Formati output |
|---|---|---|
| VS Code + Markdown PDF | Tasto destro → "Export" nell'estensione | PDF, HTML, PNG, JPEG |
| Typora | File → Esporta | PDF, HTML, Word, LaTeX |
| Dillinger.io | Pulsante "Export As" in alto | PDF, HTML, Styled HTML |
| Claude / ChatGPT | "Converti questo .md in HTML formattato" | HTML, Word (incolla il risultato) |
Il flusso più pratico per le dispense Volta Institute: scrivi in .md (struttura e contenuto), poi usa Claude per generare la versione HTML con lo stile editoriale completo — oppure Pandoc per il PDF. Il file .md rimane la "sorgente di verità" da aggiornare nel tempo.
Metti in pratica
la sintassi Markdown
- Apri VS Code o Dillinger.io e crea un nuovo file
README.md. - Aggiungi: H1 con il nome del progetto, H2 per le sezioni principali (Descrizione, Requisiti, Come usarlo, Contatti).
- Includi almeno una lista puntata, una lista numerata, un blocco di codice e una tabella.
- Aggiungi un link a una risorsa esterna e una nota in blockquote.
- Visualizza l'anteprima — la struttura è chiara e leggibile senza formattazione?
- Scegli un compito che ripeti spesso con Claude (es. scrivere post social, preparare quiz, analizzare testi).
- Crea il file
SKILL.mdcon le 4 sezioni: Nome, Descrizione, Istruzioni, Esempi — usando Markdown correttamente per ciascuna. - Usa titoli H2 per le sezioni principali, H3 per le sotto-sezioni, liste per le regole e blocchi di codice per i template di output.
- Apri l'anteprima in VS Code: la struttura è visivamente chiara e gerarchicamente corretta?
- Chiedi a Claude: "Leggi questo file SKILL.md e dimmi cosa faresti se ricevessi la richiesta [inserisci un trigger]." — verifica che abbia capito la skill correttamente.