05: Obsidian Flavored Markdown e portabilità
← 04 - GitHub Flavored Markdown · Indice · successivo → 06 - Frontmatter e Markdown per il web
Obsidian parte da CommonMark + GFM + LaTeX e ci aggiunge una decina di estensioni sue. Sono comodissime. Sono anche la ragione per cui una nota bellissima nel vault diventa illeggibile appena esce.
(Verificato su documentazione Obsidian 1.13.x, agosto 2026. I vecchi link
help.obsidian.md ora redirigono a obsidian.md/help/….)
5.1 Le estensioni
| Sintassi | Cosa fa |
|---|---|
[[Nota]] | link interno |
[[Nota|testo]] | link interno con testo alternativo |
[[Nota\#Titolo]] | link a una sezione |
![[Nota]] | embed: incorpora il contenuto di un’altra nota |
![[immagine.png|300]] | embed con larghezza |
![[doc.pdf\#page=3]] | embed di una pagina di PDF |
^id-blocco | assegna un id a un blocco, per poterlo referenziare |
![[Nota\#^id-blocco]] | embed di un singolo blocco |
==testo== | evidenziato |
| “ | commento non renderizzato |
#tag, #area/sottoarea | tag, anche gerarchici |
> [!info] | callout |
$x^2$, $$…$$ | matematica (MathJax) |
```mermaid | diagrammi |
^[nota inline] | footnote scritta sul posto |
Sui tag: ammessi lettere, numeri, _, - e / per l’annidamento; niente spazi; deve
contenere almeno un carattere non numerico (#1984 non è un tag valido).
5.2 Callout
> [!tip] Titolo opzionale
>
> Corpo del callout.
> [!warning]- Chiuso di default
>
> Si apre cliccando.
> [!example]+ Aperto di default
>
> Con il `+` parte espanso.Tipi disponibili, con i loro alias:
| Tipo | Alias |
|---|---|
| note | |
| abstract | summary, tldr |
| info | |
| todo | |
| tip | hint, important |
| success | check, done |
| question | help, faq |
| warning | caution, attention |
| failure | fail, missing |
| danger | error |
| bug | |
| example | |
| quote | cite |
Sono annidabili (> > [!todo]) e personalizzabili via CSS con
.callout[data-callout="mio-tipo"].
Il confine con GitHub
GitHub ha solo cinque alert, in maiuscolo, senza titolo e senza pieghevoli. Se una nota deve vivere in entrambi i mondi, usa solo
[!NOTE],[!TIP],[!IMPORTANT],[!WARNING],[!CAUTION], Obsidian li accetta comunque, perchéimportantè alias ditipecautiondiwarning.
5.3 Matrice di portabilità
Cosa succede alle sintassi Obsidian quando la nota esce dal vault:
| Sintassi | GitHub | Astro (.md) | Pandoc |
|---|---|---|---|
[[wikilink]] | testo letterale | testo letterale | ✓ con +wikilinks_title_after_pipe |
![[embed]] | testo letterale | testo letterale | ✗ |
![[img.png|300]] | testo letterale | testo letterale | ✗ |
^id-blocco | testo visibile | testo visibile | testo visibile |
==evidenziato== | testo con == | testo con == | ✓ con +mark |
| “ | testo VISIBILE | testo VISIBILE | visibile |
> [!info] | blockquote con [!info] | blockquote con [!info] | blockquote |
^[nota inline] | testo letterale | testo letterale | ✓ |
#tag | testo | testo | testo |
$math$ | ✓ | con math abilitato | ✓ |
```mermaid | ✓ | serve integrazione | fence generico |
[^1] footnote | ✓ | ✓ | ✓ |
- [x] task | ✓ | ✓ | ✓ |
| tabelle GFM | ✓ | ✓ | ✓ |
Le due righe in grassetto sono quelle che fanno danno vero: “ doveva essere
invisibile e diventa testo pubblicato, e ^id-blocco sporca la fine dei paragrafi.
5.4 Due comportamenti di Obsidian che non sono Markdown
1. Gli a capo. Di default un singolo invio produce un a capo visibile. In Markdown standard è uno spazio. L’impostazione si chiama “Strict line breaks”: attivandola vedi quello che vedranno gli altri. Se scrivi contenuti destinati alla pubblicazione, tienila attiva: è meglio scoprirlo subito.
2. HTML. Obsidian non renderizza Markdown dentro elementi HTML. Un
<div>**testo**</div> che su GitHub diventa grassetto, in Obsidian resta con gli asterischi.
3. Le dimensioni delle immagini.  in Obsidian imposta la larghezza a
250px. Ovunque altro produce alt="250": hai perso l’alt text e non hai la dimensione.
Nelle note destinate alla pubblicazione, usa  e regola le
dimensioni con il CSS.
5.5 Come scrivere note portabili senza rinunciare a tutto
Una strategia a tre livelli, che è quella che consiglio:
Note private, di pensiero: usa tutto. Wikilink, embed, blocchi, commenti: sono il motivo per cui usi Obsidian.
Note che potrebbero diventare pubbliche: un sottoinsieme disciplinato:
- link interni come wikilink (si convertono facilmente con uno script o un plugin)
- callout solo nei cinque tipi compatibili con GitHub
- niente “ (o accetta la regola: prima di pubblicare, cercali e rimuovili)
- niente
==evidenziato==nel testo che deve sopravvivere - immagini con alt text vero
- “Strict line breaks” attivo
Note già destinate alla pubblicazione: CommonMark + GFM e basta, frontmatter con lo schema che si aspetta il generatore (06 - Frontmatter e Markdown per il web).
Il punto non è rinunciare alle estensioni. È sapere in quale dei tre livelli stai scrivendo mentre lo fai.
5.6 Portare un vault verso un sito
Se un giorno pubblichi delle note, i pezzi da risolvere sono sempre gli stessi:
- Wikilink → link normali.
[[Nota]]va tradotto in[Nota](/percorso/nota/). Serve una mappa da titolo/nome file a URL, e va gestito il caso dei duplicati. - Embed.
![[Altra nota]]non ha equivalente: o inlinei il contenuto o lo trasformi in un link. - Callout. Vanno convertiti nei componenti del tuo sito.
- Allegati. I percorsi delle immagini nel vault raramente coincidono con quelli del sito.
Su Astro questo si fa con un plugin del processore Markdown. Attenzione: da Astro 7 il
processore di default non è più remark/rehype ma Sätteri, quindi i plugin remark
esistenti per i wikilink funzionano solo se torni esplicitamente al processore unified
(@astrojs/markdown-remark). Tutti i tutorial “Obsidian → Astro” scritti prima di giugno
2026 danno per scontato remark: leggili con questo filtro.
Alternative: Obsidian Publish (soluzione ufficiale, a pagamento, zero lavoro) o Quartz (progetto open source pensato apposta per pubblicare vault Obsidian).
Esercizi
- Attiva “Strict line breaks” per un’ora e scrivi una nota. È fastidioso, ma ti mostra quanto del tuo stile dipende da un comportamento non standard.
- Prendi la nota che consideri più bella del vault e incollala in una gist. Fai l’elenco di tutto ciò che si è rotto.
- Definisci per iscritto la tua regola personale sui commenti
%%: o non li usi nelle note pubblicabili, o metti un controllo prima di pubblicare. Scegli, non improvvisare. - Verifica quali dei tuoi callout usano tipi fuori dai cinque compatibili con GitHub.