Appunti di Simon

04. GitHub Flavored Markdown

5 minuti

04: GitHub Flavored Markdown

← 03 - Inline - enfasi, link, escaping · Indice · successivo → 05 - Obsidian Flavored Markdown e portabilità

Due categorie da tenere separate, perché si comportano in modo diverso fuori da GitHub:

  • Le 5 estensioni nella spec GFM: implementate da moltissimi parser (Astro, Obsidian, VS Code, Discourse…). Ragionevolmente portabili.
  • Quello che fa solo github.com: post-processing del sito. Fuori non esiste.

4.1 Tabelle (spec)

| Colonna | Numero | Nota |
|:--------|-------:|:----:|
| a       |     10 | ok   |
| b       |      2 | ok   |
  • :--- allinea a sinistra, ---: a destra, :---: al centro.
  • Le pipe iniziali e finali sono raccomandate ma non obbligatorie.
  • Non serve allineare le colonne nel sorgente: è solo per leggibilità (Prettier lo fa per te).

Tre trappole vere:

1. Senza riga di separazione non è una tabella. ✅ verificato: | a | b | seguito da | 1 | 2 | resta testo letterale. È l’errore numero uno.

2. Header e separatore devono avere lo stesso numero di celle, altrimenti la tabella non viene riconosciuta e diventa un paragrafo. Le righe dati invece possono avere celle in più o in meno: quelle mancanti diventano vuote, quelle in eccesso spariscono in silenzio. Un dato che scompare senza errore è il tipo di bug peggiore.

3. La pipe va escapata anche dentro il codice. Lo split sulle pipe avviene prima del parsing inline, quindi i backtick non proteggono: si scrive | `a \| b` |.

Infine: dentro una cella ci sta solo contenuto inline. Niente liste, niente blocchi di codice, niente paragrafi multipli. Se ti serve, la tabella è lo strumento sbagliato.

4.2 Task list (spec)

- [ ] da fare
- [x] fatto
  - [ ] sottopunto

Nella spec esistono solo [ ] e [x] (o [X]). Le caselle sono disabled nell’HTML generato: l’interattività è una cosa che aggiunge GitHub nelle issue, non una feature del formato.

Obsidian invece accetta qualsiasi carattere dentro le parentesi come “completato” ([-], [/], [?]), e i temi ci disegnano icone diverse. Fuori da Obsidian sono testo.

4.3 Strikethrough (spec)

~~testo~~ → testo. La spec dice “due tilde”, ma l’implementazione di riferimento di GitHub accetta anche una sola tilde (~testo~). Non contarci: scrivine due.

https://esempio.it e www.esempio.it e [email protected] diventano link senza fare niente. Solo per gli schemi http://, https://, ftp://.

La punteggiatura finale viene esclusa dal link, e le parentesi vengono bilanciate: quindi “vai su https://esempio.it.” non ti lascia il punto dentro l’URL.

4.5 Filtro sull’HTML pericoloso (spec)

Nove tag vengono neutralizzati (< diventa &lt;): title, textarea, style, xmp, iframe, noembed, noframes, script, plaintext. Tutto il resto dell’HTML passa. Sapendolo, sai anche perché non puoi mettere un <iframe> in un README.

4.6 Footnote (NON è nella spec)

Un'affermazione da documentare.[^1]
 
[^1]: La fonte, con il link.

Funzionano su github.com, in Obsidian, in Astro e in molti parser: ma non sono nella specifica GFM: sono un’estensione separata, spesso da abilitare esplicitamente.

Dettagli utili: la posizione della definizione nel sorgente è irrilevante (le note finiscono sempre in fondo), la numerazione segue l’ordine dei riferimenti, e una nota mai referenziata non viene renderizzata affatto. Sui wiki di GitHub non funzionano.

4.7 Alert (solo github.com)

> [!NOTE]
> 
> Informazione utile anche a chi legge in diagonale.
 
> [!TIP]
> 
> Consiglio pratico.
 
> [!IMPORTANT]
> 
> Informazione necessaria per riuscire.
 
> [!WARNING]
> 
> Serve attenzione immediata per evitare problemi.
 
> [!CAUTION]
> 
> Rischi o conseguenze negative.

Cinque tipi, solo maiuscoli, non annidabili, senza titolo personalizzato. Introdotti a dicembre 2023.

Fuori da GitHub degradano a blockquote con dentro [!NOTE] in chiaro. Obsidian ha un sistema di callout molto più ricco che usa la stessa sintassi ma minuscola e con tantissimi tipi: l’intersezione sicura fra i due mondi è note, tip, important, warning, caution (05 - Obsidian Flavored Markdown e portabilità).

4.8 Ancore degli heading (solo github.com)

GitHub genera un id da ogni heading: minuscole, spazi → trattini, punteggiatura rimossa, duplicati numerati (-1, -2). Da cui ## Setup del progetto → #setup-del-progetto.

Due conseguenze pratiche:

  • I link interni al documento ([vedi](#setup-del-progetto)) sono fragili: se rinomini l’heading, il link si rompe in silenzio. markdownlint ha una regola (MD051) che li controlla.
  • Con caratteri accentati, emoji o CJK l’algoritmo non è documentato con precisione: verifica invece di indovinare.

4.9 Il resto di github.com

Emoji :tada:, menzioni @utente, riferimenti automatici a issue e PR con #123, espressioni matematiche $x^2$ e blocchi ```math, diagrammi ```mermaid, anteprima dei colori quando scrivi #FF0000 fra backtick, sezioni collassabili con <details>.

Tutto questo è post-processing del sito: prezioso in un README, inesistente altrove.

4.10 Il sottoinsieme sicuro

Se un documento deve funzionare bene su GitHub e altrove:

  • CommonMark completo
  • tabelle, task list, ~~strike~~, autolink nudi
  • footnote solo se hai verificato che l’altro lato le supporti
  • alert solo se accetti il degrado a blockquote
  • niente emoji :code:, menzioni, math, mermaid

Esercizi

  1. Costruisci una tabella con allineamenti misti, una cella che contiene una pipe dentro del codice e una riga con una cella in meno. Guarda cosa succede alla cella mancante.
  2. Scrivi un README con un <details> che contiene una lista e un blocco di codice.
  3. Prendi un documento con alert GitHub e aprilo in Obsidian. Poi fai il contrario con un callout Obsidian in minuscolo. Annota cosa sopravvive.
  4. Aggiungi due footnote a una nota e verifica dove finiscono nell’HTML.

Vista grafico

Link entranti