GFM vs CommonMark vs Pandoc Markdown: Sintassi Confrontata

Il Markdown sembra una lingua finché lo stesso file non viene renderizzato in modo diverso su GitHub, Hugo, Obsidian o Pandoc. E il problema non è che il Markdown sia inaffidabile.

Il problema è che “Markdown” descrive una famiglia di sintassi correlate, parser e funzionalità della piattaforma piuttosto che un singolo formato di documento universale. CommonMark definisce un nucleo portabile preciso, GitHub Flavored Markdown aggiunge funzionalità utili per la collaborazione software e Pandoc Markdown espande la lingua in un formato serio per la stesura di documenti.

La scelta tra di essi dipende da dove il documento deve essere renderizzato. Un file README, un post sul blog Hugo e un articolo accademico hanno ciascuno requisiti diversi. Questo confronto fa parte del quadro più ampio degli strumenti di documentazione e copre i dialetti formali, le estensioni specifiche della piattaforma e le regole pratiche di portabilità in modo da poter scegliere la sintassi giusta per il tuo ambiente target. Per un rapido riferimento alla sintassi, il riassunto delle scorciatoie Markdown copre gli elementi di formattazione essenziali.

Il Markdown non è una singola lingua

La sintassi Markdown originale era intenzionalmente piccola e definita in modo approssimativo. Questo la rese facile da leggere e implementare, ma diversi parser iniziarono a interpretare gli input ambigui in modi diversi.

CommonMark è stato creato per definire regole di parsing coerenti per le strutture fondamentali del Markdown. GitHub Flavored Markdown, solitamente chiamato GFM, si basa su questa fondazione con diverse estensioni ampiamente utilizzate.

Pandoc Markdown adotta un approccio diverso. Invece di rimanere una sintassi orientata al web e di piccole dimensioni, aggiunge funzionalità documentali come citazioni, metadati, note a piè di pagina, elenchi di definizione, attributi e notazione matematica.

Un rapporto semplificato appare così:

Questa gerarchia è utile, ma non è un’ereditarietà esatta in ogni implementazione. Ogni renderizzatore può abilitare, disabilitare o aggiungere sintassi in modo indipendente.

La risposta breve

Usa la sintassi compatibile con CommonMark quando la portabilità è più importante.

Usa GFM quando scrivi file README, pull request, modelli di issue e documentazione tecnica destinata principalmente a piattaforme compatibili con GitHub.

Usa Pandoc Markdown quando il documento sorgente deve diventare PDF, DOCX, EPUB, LaTeX, presentazioni o un articolo accademico con citazioni e metadati.

Per un blog tecnico Hugo, usa il nucleo CommonMark più le estensioni Goldmark che il tuo sito abilita esplicitamente. Non dare per scontato che ogni funzionalità visibile su GitHub funzionerà solo perché Hugo è descritto come compatibile con GFM.

Opinionata: se ricordi solo una regola per un blog tecnico Hugo, tratta CommonMark più le tabelle e gli elenchi di controllo in stile GFM come predefiniti, e tratta tutto il resto — note a piè di pagina, matematica, avvisi, attributi degli intestazioni — come un’estensione esplicita e testata piuttosto che come un’impostazione predefinita. Questa singola abitudine previene la maggior parte dei fallimenti di portabilità descritti di seguito.

CommonMark: Il nucleo portabile

CommonMark è una specifica formale per la lingua Markdown di base. Il suo principale contributo non è una grande raccolta di funzionalità, ma un parsing coerente.

Definisce come i parser dovrebbero interpretare:

• Paragrafi
• Intestazioni ATX e Setext
• Citazioni in blocco
• Elenchi ordinati e non ordinati
• Blocchi di codice delimitati e indentati
• Enfasi ed enfasi forte
• Link e immagini
• Link in stile riferimento
• Codice inline
• Interruzioni tematiche
• Blocchi HTML grezzi
• Interruzioni di riga dure e morbide

Un documento CommonMark può ancora comportarsi diversamente a livello di presentazione. CSS, evidenziazione della sintassi, ancoraggi delle intestazioni, sanitizzazione HTML e politiche sui link sono al di fuori delle regole di parsing del nucleo.

CommonMark dovrebbe quindi essere trattato come una linea di base strutturale affidabile, non come una promessa che ogni renderizzatore produrrà una pagina identica.

Un esempio portabile di CommonMark

# Distribuzione del servizio

Il servizio espone una piccola API HTTP.

## Requisiti

- Linux
- Docker
- 8 GB di memoria

## Avvia il servizio

```bash
docker compose up -d
```

Vedi la [guida alla configurazione](configuration.md) per i dettagli.

Questo tipo di documento funziona su quasi ogni ambiente Markdown moderno. Usa intestazioni, paragrafi, elenchi, codice delimitato e link ordinari senza fare affidamento su estensioni specifiche del dialetto.

GitHub Flavored Markdown: CommonMark per progetti software

GitHub Flavored Markdown è un dialetto formale basato su CommonMark. Preserva il modello di parsing di CommonMark e aggiunge funzionalità comunemente necessarie nella documentazione dei repository e nella collaborazione.

La specifica formale GFM aggiunge:

• Tabbelle con pipe
• Voci di elenchi di controllo
• Barrato
• Autolink estesi
• Restrizioni su alcuni tag HTML grezzi

Queste estensioni sono ora così comuni che molti utenti pensano che facciano parte del Markdown standard. Non fanno parte del nucleo CommonMark.

Tabelle GFM

| Backend | Utilizzo migliore |
|---|---|
| Ollama | Sperimentazioni locali |
| vLLM | Inferenza condivisa |
| SGLang | Carichi di lavoro strutturati |

Un parser CommonMark rigoroso è autorizzato a trattare questo come testo di paragrafo ordinario. Un parser compatibile con GFM lo riconosce come tabella. Per un’analisi più approfondita della sintassi delle tabelle e delle opzioni di allineamento, vedi Tabelle in Markdown.

Elenchi di controllo GFM

- [x] Installa Docker
- [x] Scarica il modello
- [ ] Aggiungi monitoraggio

La sintassi degli elenchi di controllo è utile nelle issue, nei pull request e nella documentazione dei progetti. Fuori da un renderizzatore di supporto, potrebbe apparire come un elenco ordinario contenente parentesi quadre letterali.

Barrato GFM

Usa il ~~vecchio endpoint~~ nuovo endpoint.

Il barrato è ampiamente supportato, ma è ancora un’estensione piuttosto che una sintassi CommonMark portabile.

Autolink GFM

GFM riconosce più testo simile a URL e email senza richiedere parentesi angolari o sintassi di link esplicita.

Visita https://example.com/docs per i dettagli.

In CommonMark rigoroso, gli autolink espliciti usano parentesi angolari:

<https://example.com/docs>

La forma esplicita è più sicura quando un documento deve viaggiare attraverso elaboratori Markdown sconosciuti.

GitHub.com supporta più del formale GFM

Una fonte frequente di confusione è l’assunzione che ogni funzionalità Markdown visibile su GitHub appartenga alla specifica GFM.

Non è così.

GitHub.com aggiunge elaborazione e funzionalità a livello di piattaforma attorno al parser GFM. A seconda del contesto, GitHub può supportare:

• Espressioni matematiche
• Diagrammi Mermaid
• Avvisi
• Riferimenti a issue e pull request
• Menzioni di utenti e team
• Riferimenti ai commit
• Scorciatoie emoji
• Sezioni HTML collassabili
• Anteprime dei colori
• Link relativi al repository
• Ancoraggi automatici delle intestazioni

Alcune di queste funzionalità sono estensioni sintattiche. Altre sono comportamenti di post-elaborazione o integrazioni con i dati di GitHub.

Questa distinzione è importante perché un altro renderizzatore può affermare accuratamente la compatibilità GFM senza implementare il renderer matematico di GitHub, l’integrazione Mermaid, i riferimenti alle issue o lo stile degli avvisi.

Diagrammi Mermaid di GitHub

GitHub renderizza un blocco di codice delimitato contrassegnato come mermaid come un diagramma:

```mermaid
flowchart LR
    A[Markdown] --> B[Diagramma renderizzato]
```

Un renderizzatore GFM generico potrebbe visualizzare lo stesso blocco come codice sorgente evidenziato. Il Markdown rimane valido, ma il rendering migliorato è specifico della piattaforma. Per un’introduzione pratica alla sintassi Mermaid, vedi il Quickstart dei diagrammi Mermaid.

Espressioni matematiche di GitHub

GitHub supporta espressioni matematiche inline e in blocco usando delimitatori di dollari e forme di escape aggiuntive.

La dimensione della cache è approssimativamente $2nlhd$ byte.

$$
C = 2nlhd
$$

La matematica non fa parte del formale GFM. Spostare questo contenuto su un altro renderizzatore richiede un’estensione matematica compatibile come KaTeX, MathJax o il supporto matematico di Pandoc.

Avvisi di GitHub

GitHub supporta citazioni in blocco in stile avviso come:

> [!WARNING]
> Modificare questa impostazione cancella la cache.

Su GitHub, questo può apparire come un avviso stilizzato. Su un renderizzatore CommonMark semplice, solitamente appare come una citazione in blocco ordinaria contenente [!WARNING].

Quel fallback è leggibile, il che rende gli avvisi di GitHub meno pericolosi delle estensioni che scompaiono completamente. Non sono comunque elementi di presentazione portabili.

Pandoc Markdown: Markdown come linguaggio documentale

Pandoc Markdown è progettato per la conversione di documenti piuttosto che per un particolare sito web. Usa Markdown come sintassi sorgente per produrre HTML, PDF, DOCX, EPUB, LaTeX, presentazioni e altri formati.

Il suo lettore Markdown predefinito include un grande set di estensioni. Le capacità importanti includono:

• Blocchi di metadati YAML
• Note a piè di pagina
• Citazioni
• Formati di tabella multipli
• Elenchi di definizione
• Notazione matematica
• Identificatori e attributi delle intestazioni
• Attributi dei blocchi di codice
• Divisioni delimitate
• Span tra parentesi quadre
• Apice e pedice
• Barrato
• Blocchi di riga
• Elenchi di esempi numerati
• LaTeX grezzo
• HTML grezzo
• Numerazione automatica delle sezioni
• Elaborazione della bibliografia

Pandoc Markdown è molto più espressivo di CommonMark o del formale GFM. Questa espressività lo rende potente per la pubblicazione, ma meno sicuro come formato di interscambio.

Note a piè di pagina di Pandoc

Il Markdown ha diversi dialetti incompatibili.[^dialects]

[^dialects]: CommonMark, GFM e Pandoc Markdown sono tre
    esempi importanti.

La sintassi delle note a piè di pagina è supportata da molti strumenti moderni, ma non fa parte di CommonMark o del formale GFM.

GitHub attualmente renderizza le note a piè di pagina in diversi contesti di contenuto, ma questa è una funzionalità della piattaforma GitHub piuttosto che una garanzia formale GFM. Un renderizzatore che dichiara solo compatibilità CommonMark o GFM potrebbe non supportarle.

Citazioni di Pandoc

PagedAttention migliora la gestione della memoria della cache KV
[@kwon2023pagedattention].

Con un file di bibliografia e uno stile di citazione, Pandoc può risolvere questo in una citazione accademica formattata e in una bibliografia.

pandoc article.md \
  --citeproc \
  --bibliography references.bib \
  --csl ieee.csl \
  -o article.pdf

La sintassi della citazione rimane leggibile in un renderizzatore non supportato, ma non diventerà un riferimento formattato senza Pandoc o un altro elaboratore di citazioni compatibile. La flessibilità lato lettore di Pandoc sostiene anche i flussi di lavoro di conversione nella direzione opposta — vedi convertire documenti Word in Markdown per un esempio pratico di utilizzo del dialetto esteso di Pandoc come formato intermedio.

Elenchi di definizione di Pandoc

CommonMark
: Una specifica precisa per il nucleo Markdown.

GFM
: Un dialetto basato su CommonMark con estensioni orientate al software.

Pandoc Markdown
: Un formato di autore esteso per la conversione di documenti.

Gli elenchi di definizione sono utili nei manuali, nei glossari e nei libri tecnici. Normalmente si degradano male nei renderizzatori che non li supportano perché le linee dei due punti rimangono visibili come testo normale.

Attributi delle intestazioni di Pandoc

## Configurazione della cache {#cache-config .deployment}

Pandoc interpreta le parentesi graffe come un identificatore esplicito e un elenco di classi. Molti altri renderizzatori Markdown mostrano il testo degli attributi direttamente nell’intestazione.

Questo è uno degli esempi più chiari di sintassi utile che non dovrebbe essere inserita in un documento che ci si aspetta venga renderizzato ovunque.

Divisioni delimitate di Pandoc

::: warning
Modificare questa opzione riavvia il server.

Pandoc converte questo in una divisione strutturale con una classe. Template, CSS, filtri o writer di output possono decidere come quella struttura dovrebbe apparire.

La maggior parte dei renderizzatori CommonMark e GFM non riconoscono il delimitatore. Visualizzano i due punti e il contenuto come testo ordinario.

CommonMark vs GFM vs Pandoc Markdown

La matrice seguente descrive i dialetti formali, non ogni funzionalità aggiunta da GitHub.com, Hugo, Obsidian, GitLab o un’altra piattaforma.

La parola “No” non significa che una piattaforma non possa mai supportare la funzionalità. Significa che la funzionalità non è garantita dalla specifica formale di quel dialetto.

Quale sintassi funziona su GitHub?

Per i file README, le issue, i pull request, le discussioni e le wiki, GFM è la linea di base naturale.

Generalmente puoi usare:

• Sintassi CommonMark
• Tabelle
• Elenchi di controllo
• Barrato
• Autolink estesi
• Recinti di codice con evidenziazione della sintassi
• Riferimenti specifici di GitHub
• Matematica supportata da GitHub
• Diagrammi supportati da GitHub
• Avvisi di GitHub
• Note a piè di pagina dove supportate dalla superficie di contenuto

Il rischio di portabilità inizia quando GitHub esegue un rendering aggiuntivo oltre al formale GFM. I diagrammi Mermaid, la notazione matematica, i riferimenti alle issue e la presentazione degli avvisi potrebbero non sopravvivere fuori da GitHub.

Per i file di repository che vengono anche pubblicati altrove, testa il sorgente nel secondo renderizzatore piuttosto che trattare l’anteprima di GitHub come autorevole.

Quale sintassi funziona in Hugo?

Hugo usa Goldmark come suo renderizzatore Markdown predefinito. Goldmark è conforme a CommonMark e fornisce estensioni compatibili con parti importanti di GFM.

In una configurazione Hugo tipica, i seguenti elementi funzionano bene:

• Struttura CommonMark
• Blocchi di codice delimitati
• Tabelle con pipe
• Barrato
• Elenchi di controllo
• ID automatici delle intestazioni
• Evidenziazione della sintassi
• Note a piè di pagina quando l’estensione è abilitata
• Elenchi di definizione quando abilitati
• Sostituzioni tipografiche quando abilitate

Hugo aggiunge anche funzionalità al di fuori del Markdown attraverso:

• Front matter
• Shortcode
• Render hook
• Risorse della pagina
• Funzioni di riferimento interne
• Elaborazione dei template
• Configurazione del sito

Queste funzionalità Hugo non viaggiano con il file Markdown. Per un esempio pratico di distribuzione Hugo, vedi Distribuisci Hugo su AWS S3.

Il front matter di Hugo non è contenuto Markdown

Una pagina Hugo inizia comunemente con metadati YAML, TOML o JSON:

---
title: "Compatibilità Markdown"
description: "Confronta dialetti e renderizzatori Markdown."
date: 2026-07-31
tags:
  - Markdown
  - documentazione
---

Pandoc può anche riconoscere i blocchi di metadati YAML, ma interpreta i campi secondo i suoi propri template e writer. GitHub normalmente visualizza il blocco come una sezione simile a YAML o lo tratta come metadati del repository solo in sistemi specifici.

La stessa sintassi può quindi essere riconosciuta in più di uno strumento senza avere la stessa semantica.

HTML grezzo in Hugo

Goldmark non renderizza l’HTML grezzo potenzialmente non sicuro per impostazione predefinita in una configurazione Hugo standard.

Un blocco come:

<div class="notice">
  Riavvia il servizio dopo aver modificato questo valore.
</div>

potrebbe essere omesso a meno che il rendering HTML grezzo non sia abilitato o il contenuto non sia implementato attraverso uno shortcode o un render hook.

Per un blog tecnico controllato, abilitare l’HTML grezzo può essere ragionevole. Rende comunque il sorgente meno portabile e dovrebbe essere una decisione deliberata a livello di sito.

Mermaid in Hugo

Un blocco mermaid delimitato è comunque solo un blocco di codice a meno che il tema Hugo, il render hook, lo shortcode o il pipeline JavaScript non lo trasformi in un diagramma.

GitHub e Hugo possono quindi accettare sorgente Mermaid identica mentre usano meccanismi di rendering completamente diversi.

Quale sintassi funziona in Pandoc?

Pandoc può leggere esplicitamente diversi dialetti Markdown:

pandoc --from=markdown input.md
pandoc --from=commonmark input.md
pandoc --from=gfm input.md
pandoc --from=commonmark_x input.md

Questa è una delle funzionalità di portabilità più utili di Pandoc. L’operatore può dire a Pandoc quale dialetto il sorgente dichiara di usare invece di affidarsi a un’estensione .md vaga.

Pandoc ti permette anche di abilitare o disabilitare estensioni individuali:

pandoc \
  --from=markdown-footnotes-pipe_tables \
  input.md \
  -o output.html

Oppure partire da un formato più ristretto e aggiungere una funzionalità:

pandoc \
  --from=commonmark+footnotes \
  input.md \
  -o output.html

Puoi ispezionare le estensioni disponibili con:

pandoc --list-extensions=markdown
pandoc --list-extensions=commonmark
pandoc --list-extensions=gfm

Questo modello di estensione è potente, ma significa che “Pandoc Markdown” non è sempre una configurazione fissa. I comandi di build e i file predefiniti fanno parte della specifica del documento.

Quale sintassi funziona in Obsidian?

Obsidian archivia le note come file Markdown, ma il suo modello di autore include diverse funzionalità specifiche dell’applicazione.

Esempi comuni includono:

• Link wiki
• Note incorporate
• File incorporati
• Avvisi (Callouts)
• Riferimenti ai blocchi
• Tag
• Proprietà
• Evidenziazione
• Commenti
• Query Dataview da plugin
• Link URI specifici dell’applicazione

Un link wiki come:

[[Compatibilità Markdown]]

ha significato all’interno di un vault Obsidian. GitHub, CommonMark e un lettore Pandoc predefinito normalmente lo visualizzano come testo tra parentesi quadre letterale.

Un embed è ancora più specifico dell’applicazione:

![[compatibilità-tabella]]

Il contenuto riferito non è presente nel file stesso. L’esportazione o la pubblicazione della nota richiede quindi un passaggio di espansione che risolva l’embed.

Obsidian è un buon esempio del perché l’archiviazione in file .md non garantisca la portabilità Markdown. Per un’analisi pratica di Obsidian come strumento di gestione della conoscenza, vedi Obsidian per la gestione della conoscenza personale.

Quale sintassi funziona in GitLab?

GitLab Flavored Markdown usa CommonMark come nucleo e include funzionalità GFM come tabelle ed elenchi di controllo. Aggiunge poi comportamenti specifici di GitLab tra cui incroci di riferimenti, notazione matematica, diagrammi e altre funzionalità di collaborazione.

Un README scritto in GFM conservativo si sposta solitamente tra GitHub e GitLab senza danni maggiori.

Le integrazioni della piattaforma non viaggiano in modo affidabile. I riferimenti alle issue, le menzioni degli utenti, i diagrammi, la gestione della matematica e la sintassi dei blocchi speciali possono comportarsi diversamente anche quando il Markdown di base rimane leggibile.

Matrice di supporto della piattaforma

Questa matrice descrive il comportamento predefinito comune. Temi, plugin, estensioni e configurazione possono modificare singole celle.

“Sì” non garantisce ancora un HTML o una presentazione visiva identica. Significa che l’ambiente riconosce la funzionalità generale.

Sintassi che è solitamente sicura ovunque

Il sottoinsieme portabile più sicuro include:

• Intestazioni ATX usando #
• Paragrafi ordinari
• Righe vuote tra i blocchi
• - per elenchi non ordinati
• 1. per elenchi ordinati
• Blocchi di codice delimitati usando backtick
• Codice inline usando backtick
• Enfasi usando *testo*
• Enfasi forte usando **testo**
• Link ordinari
• Immagini ordinarie
• Citazioni in blocco
• Interruzioni tematiche
• Autolink espliciti con parentesi angolari

Un documento intenzionalmente conservativo potrebbe apparire così:

# Guida alla distribuzione

Questa guida spiega come distribuire il servizio.

## Requisiti

- Docker
- Linux
- Una GPU supportata

## Configurazione

Crea un file chiamato `compose.yaml`.

```yaml
services:
  application:
    image: example/application:1.0
```

Per ulteriori informazioni, vedi il [riferimento alla configurazione](config.md).

> Effettua il backup dei dati esistenti prima di aggiornare.

Questa sintassi viaggia bene perché non dipende da tabelle, note a piè di pagina, attributi, avvisi o elaborazione della piattaforma.

Sintassi che comunemente si rompe

I problemi di portabilità tendono a raggrupparsi attorno a un piccolo numero di funzionalità.

Tabelle con pipe

Le tabelle con pipe sono ben supportate dagli strumenti orientati a GFM, ma non da CommonMark rigoroso.

Una tabella può degradarsi in testo illeggibile quando passata attraverso un parser che non la riconosce. Per documenti altamente portabili, considera elenchi brevi o HTML semantico generato durante un passaggio di build.

Note a piè di pagina

La sintassi delle note a piè di pagina è diventata comune, ma rimane un’estensione.

Diversi strumenti possono:

• Supportare solo un formato di note a piè di pagina
• Posizionare le note a piè di pagina diversamente
• Generare identificatori diversi
• Rifiutare note a piè di pagina su paragrafi multipli
• Renderizzare il sorgente letteralmente

Usa le note a piè di pagina quando il pipeline di pubblicazione è noto. Evita di dipendere da esse nei file README che devono essere renderizzati su sistemi arbitrari.

ID e attributi delle intestazioni

Questa sintassi Pandoc non è portabile:

## Installazione {#installazione .procedura}

Usa un’intestazione ordinaria e lascia che il renderizzatore generi il proprio ancoraggio quando la portabilità è importante.

Evita anche di codificare manualmente i link verso ID delle intestazioni generati automaticamente a meno che ogni target non usi le stesse regole di slugificazione.

Avvisi e Callout

GitHub, Obsidian, GitLab, MkDocs, Docusaurus e i temi Hugo possono tutti supportare blocchi simili a callout, ma spesso usano sintassi diverse.

Un fallback portabile è una citazione in blocco ordinaria:

> Attenzione: Effettua il backup del database prima di aggiornare.

È meno impressionante visivamente, ma preserva il significato ovunque.

Link wiki

I link wiki sono concisi all’interno degli strumenti di gestione della conoscenza:

[[Cache KV]]

Sono una sintassi di interscambio scadente perché il percorso target, il nome del file, le regole delle intestazioni e il comportamento di risoluzione appartengono all’applicazione.

Usa i link Markdown standard nel contenuto destinato alla pubblicazione:

[Cache KV](cache-kv.md)

HTML grezzo

L’HTML grezzo è la valvola di sfogo abituale quando Markdown non può esprimere un layout. È anche un comune fallimento di portabilità e sicurezza.

Un renderizzatore può:

• Rimuovere l’HTML
• Escaparlo
• Sanitizzare elementi selezionati
• Consentire blocchi ma non elementi inline
• Rifiutare l’analisi Markdown all’interno dell’HTML
• Passarlo invariato solo in modalità fidata

Usa l’HTML grezzo solo quando il target di pubblicazione è controllato.

Notazione matematica

La matematica delimitata da dollari è popolare ma non universalmente interpretata.

Il sorgente:

La complessità è $O(n^2)$.

potrebbe diventare:

• Matematica renderizzata
• Testo ordinario con segni di dollaro
• Enfasi errata
• Input per un parser matematico diverso

Scegli un’unica pipeline matematica e testala in ogni ambiente target.

Mermaid e altri blocchi diagramma

Un recinto di codice Mermaid è sintatticamente sicuro perché i renderizzatori non supportati normalmente lo visualizzano come codice.

Il risultato semantico è comunque diverso. I lettori potrebbero vedere un diagramma di architettura renderizzato su GitHub e sorgente Mermaid grezzo in un altro ambiente.

Questa è una degradazione elegante, non una vera compatibilità.

I tre livelli di compatibilità Markdown

Aiuta separare la compatibilità in tre livelli.

Livello 1: Compatibilità di parsing

Il parser riconosce la struttura?

Gli esempi includono intestazioni, tabelle, note a piè di pagina e divisioni delimitate.

Livello 2: Compatibilità di trasformazione

La piattaforma applica un’elaborazione aggiuntiva?

Gli esempi includono:

• Rendering Mermaid
• Risoluzione delle citazioni
• Espansione dei link wiki
• Collegamento dei numeri delle issue
• Elaborazione degli shortcode
• Generazione di un indice

Livello 3: Compatibilità di presentazione

Il risultato appare e si comporta in modo appropriato?

Gli esempi includono:

• Stile delle tabelle
• Evidenziazione della sintassi
• Colori degli avvisi
• Ancoraggi delle intestazioni
• Immagini reattive
• Posizionamento delle note a piè di pagina
• Font matematici

Due piattaforme possono analizzare la stessa sintassi producendo una presentazione sostanzialmente diversa.

Un modello di portabilità migliore

Invece di chiedere se un file è “Markdown valido”, poni quattro domande più specifiche:

1. In quale dialetto è scritto il sorgente?
2. Quale parser lo legge?
3. Quali estensioni sono abilitate?
4. Quali trasformazioni della piattaforma vengono eseguite successivamente?

Per esempio:

Dialetto: CommonMark più tabelle GFM
Parser: Goldmark
Estensioni: tabelle, barrato, elenchi di controllo, note a piè di pagina
Piattaforma: Hugo
Elaborazione aggiuntiva: render hook e JavaScript Mermaid

Questa descrizione è molto più utile che dire “il sito usa Markdown”.

Scelta di un dialetto in base al caso d’uso

File README

Usa GFM.

I file README beneficiano di:

• Tabelle
• Elenchi di controllo
• Codice delimitato
• Autolink
• Barrato
• Riferimenti GitHub

Evita un’eccessiva dipendenza da funzionalità solo di GitHub quando il repository è mirrorato su GitLab, renderizzato su un registro dei pacchetti o incluso nella documentazione generata.

Articoli tecnici Hugo

Usa Markdown compatibile con CommonMark con un set di estensioni Goldmark documentato.

Tabelle, recinti di codice, note a piè di pagina e Mermaid possono essere ragionevoli perché controlli il pipeline di build. Preferisci gli shortcode o i render hook di Hugo rispetto all’inserimento di grandi quantità di HTML grezzo.

Tieni la sintassi specifica di Hugo isolata e facile da trovare.

Documenti accademici

Usa Pandoc Markdown.

Citazioni, elaborazione della bibliografia, note a piè di pagina, metadati, notazione matematica, incroci di riferimenti e conversione in PDF o DOCX giustificano la portabilità ridotta.

Archivia il comando Pandoc, il file predefinito, i filtri, la bibliografia e i template accanto al sorgente. Il file sorgente da solo non descrive completamente la build.

Libri e documentazione lunga

Pandoc Markdown è solitamente l’opzione più forte delle tre quando contano più formati di output.

Gli elenchi di definizione, le citazioni, gli attributi, i metadati e le trasformazioni strutturate diventano più importanti man mano che la complessità del documento cresce.

Per la documentazione solo web ospitata in un repository Git, GFM o un generatore di documentazione basato su CommonMark possono rimanere più semplici.

Note e basi di conoscenza personale

Usa la sintassi nativa dell’applicazione di note selezionata quando le funzionalità dell’applicazione forniscono valore reale.

I link wiki, gli embed e i callout di Obsidian sono utili all’interno di un vault. Tratta l’esportazione come un processo di compilazione piuttosto che assumere che i file grezzi siano già pubblicazioni portabili.

Documentazione condivisa su sistemi sconosciuti

Usa un sottoinsieme CommonMark conservativo.

Evita:

• Link wiki
• Avvisi della piattaforma
• Attributi delle intestazioni
• Citazioni
• HTML grezzo
• Contenitori personalizzati
• Embed dell’applicazione
• Shortcode

La portabilità richiede solitamente di rinunciare alle funzionalità di convenienza.

Regole pratiche per Markdown portabile

Inizia con la struttura CommonMark

Usa CommonMark per lo scheletro del documento:

• Intestazioni
• Paragrafi
• Elenchi
• Link
• Immagini
• Citazioni in blocco
• Blocchi di codice

Questo assicura che il significato principale sopravviva anche quando le estensioni opzionali falliscono.

Aggiungi funzionalità GFM deliberatamente

Tabelle ed elenchi di controllo sono ragionevoli quando tutti i target importanti li supportano.

Non dare per scontato che “la maggior parte degli strumenti supporta GFM” senza testare il target esatto. Alcuni dichiarano compatibilità GFM mentre abilitano solo estensioni selezionate.

Isola le estensioni della piattaforma

Tieni la sintassi specifica della piattaforma in blocchi chiaramente identificabili.

Per esempio, centralizza gli shortcode Hugo, le citazioni Pandoc o gli embed Obsidian piuttosto che disperderli attraverso ogni paragrafo.

L’isolamento rende più facile la conversione successiva.

Preferisci la degradazione elegante

Un blocco Mermaid si degrada in codice sorgente leggibile. Un avviso GitHub si degrada in una citazione in blocco.

Un embed wiki potrebbe degradarsi in un nome di file incomprensibile, mentre una divisione delimitata di Pandoc potrebbe esporre la punteggiatura attorno al contenuto.

Scegli estensioni il cui fallback rimane comprensibile.

Non dipendere dagli ID delle intestazioni generati automaticamente

Gli algoritmi degli ancoraggi delle intestazioni differiscono tra GitHub, Hugo, Pandoc e i generatori di documentazione.

Per i link tra documenti, usa ID espliciti supportati dal renderizzatore solo quando il pipeline target è controllato. Altrimenti, collega al documento piuttosto che a un frammento generato.

Tieni la configurazione di build con il contenuto

Le estensioni Pandoc, le impostazioni Hugo, i plugin, i filtri e le integrazioni JavaScript determinano come si comporta Markdown.

Commita i file di configurazione rilevanti con il sorgente:

content/
  article.md
pandoc.yaml
references.bib
config/
  _default/
    markup.yaml
layouts/
  _default/
    _markup/

Un’estensione .md da sola non cattura l’ambiente di pubblicazione. Per un approccio strutturato alla documentazione di queste decisioni, vedi Registri delle decisioni per lo sviluppo guidato dall’IA.

Testa Markdown contro ogni target importante

L’anteprima visiva in un editor non è sufficiente. L’editor potrebbe supportare un dialetto più ricco del renderizzatore di produzione.

Per Pandoc, testa i formati di input espliciti:

pandoc --from=commonmark article.md -o commonmark.html
pandoc --from=gfm article.md -o gfm.html
pandoc --from=markdown article.md -o pandoc.html

Avvertimenti e punteggiatura del sorgente visibile rivelano quali funzionalità sono specifiche del dialetto.

Per Hugo, costruisci il sito di produzione:

hugo --gc --minify

Poi ispeziona l’HTML generato piuttosto che affidarti solo a un’anteprima dell’editor.

Per i repository, visualizza il file commitato sulla piattaforma di hosting effettiva. Le estensioni Markdown locali in VS Code potrebbero non corrispondere a GitHub o GitLab.

Risoluzione dei problemi comuni di mismatch di rendering

Quando un file che ha funzionato su una piattaforma si rompe su un’altra, il fallimento di solito rientra in uno di un pugno di pattern ripetibili. La tabella sottostante elenca il sintomo come lo vedresti effettivamente, la causa più probabile e un comando o controllo concreto per confermare e correggere.

Questa è la prima passata più rapida prima di assumere un “bug” di Markdown — la maggior parte di questi mismatch sono un’estensione mancante o una funzionalità solo della piattaforma, non una sintassi rotta. Per problemi specifici dei recinti di codice come l’evidenziazione della sintassi mancante o identificatori di linguaggio non supportati, vedi la guida dedicata sui blocchi di codice Markdown.

Lint del sottoinsieme portabile

Un linter Markdown non può garantire la compatibilità del renderizzatore, ma può rimuovere l’ambiguità evitabile.

Le regole utili includono:

• Usa stili di intestazione coerenti
• Aggiungi righe vuote attorno agli elenchi e ai blocchi di codice
• Usa codice delimitato piuttosto che indentato
• Specifica i linguaggi dei recinti di codice
• Evita livelli di intestazione saltati
• Usa marcatori di elenco coerenti
• Evita enfasi ambigua attorno alla punteggiatura
• Mantieni le interruzioni di riga coerenti
• Convalida link e immagini

Per la pubblicazione multi-target, aggiungi un test di build per ogni renderizzatore importante piuttosto che affidarti solo al linting della sintassi.

Conversione tra dialetti con Pandoc

Pandoc può normalizzare documenti da un dialetto a un altro:

pandoc \
  --from=markdown \
  --to=gfm \
  article.md \
  -o article-gfm.md

Oppure convertire GFM in Pandoc Markdown:

pandoc \
  --from=gfm \
  --to=markdown \
  README.md \
  -o document.md

Questo è utile, ma la conversione non è garantita per preservare ogni funzionalità.

Le potenziali perdite includono:

• Riferimenti specifici della piattaforma
• Stile dei callout
• Tabelle complesse
• Oggetti applicazione incorporati
• Attributi personalizzati
• Comportamento HTML grezzo
• Sintassi dei plugin
• Rendering dei diagrammi
• Spaziatura e formattazione esatti

Pandoc preserva la struttura del documento meglio della formattazione del sorgente originale. Tratta la conversione come un passaggio di build, non come un formattatore di testo reversibile.

Strategia consigliata per i siti Hugo

Per un blog tecnico Hugo, la politica più pratica è:

1. Usa CommonMark per il testo e la struttura di base.
2. Abilita un piccolo set documentato di estensioni Goldmark.
3. Usa tabelle ed elenchi di controllo in stile GFM dove migliorano la leggibilità.
4. Implementa Mermaid attraverso un unico render hook o shortcode coerente.
5. Gestisci la matematica attraverso un’unica pipeline documentata KaTeX o MathJax.
6. Usa il front matter Hugo solo all’inizio dei file di contenuto.
7. Preferisci render hook e shortcode rispetto all’HTML grezzo.
8. Tieni i link sorgente come link Markdown standard dove possibile.
9. Testa i documenti migrati o provenienti da fonti esterne attraverso Hugo.
10. Documenta qualsiasi sintassi che non verrà renderizzata correttamente su GitHub.

Questo approccio accetta che il contenuto Hugo non sia universalmente portabile mentre mantiene il confine di portabilità visibile.

Il peggior approccio è il mixing accidentale dei dialetti: avvisi GitHub, embed Obsidian, attributi Pandoc e shortcode Hugo posti nello stesso documento senza un pipeline di build definito.

Tabella delle decisioni

Conclusione

CommonMark, GitHub Flavored Markdown e Pandoc Markdown non sono versioni concorrenti dello stesso prodotto. Risolvono problemi diversi.

CommonMark fornisce una fondazione di parsing affidabile. GFM aggiunge funzionalità pratiche per la collaborazione software, mentre Pandoc Markdown trasforma Markdown in un linguaggio sorgente ricco per la pubblicazione e la conversione.

La regola più sicura è semplice: scrivi il dialetto più piccolo che soddisfi la destinazione reale. Usa CommonMark quando il contenuto deve viaggiare, GFM quando la collaborazione in stile GitHub è il target, e Pandoc Markdown quando la struttura del documento e i formati di output sono più importanti del rendering universale.

La portabilità Markdown non è raggiunta evitando ogni estensione. È raggiunta conoscendo quali estensioni fanno parte del contratto sorgente e testandole in ogni renderizzatore che conta.

Riferimenti

• Specifiche CommonMark
• Specifiche GitHub Flavored Markdown
• Pandoc Markdown
• Documentazione Goldmark
• Configurazione Goldmark di Hugo
• Scrittura di espressioni matematiche su GitHub