GFM vs CommonMark vs Pandoc Markdown: confronto della sintassi

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

Il problema è che “Markdown” descrive una famiglia di sintassi correlate, parser e funzionalità di piattaforma, piuttosto che un unico 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 dal luogo in cui il documento deve essere renderizzato. Un file README, un post di blog Hugo e un articolo accademico hanno ciascuno requisiti diversi. Questo confronto fa parte del quadro più ampio degli strumenti per la documentazione e copre i dialetti formali, le estensioni specifiche della piattaforma e le regole pratiche di portabilità, così da poter scegliere la sintassi giusta per l’ambiente di destinazione. Per un rapido riferimento alla sintassi, la scheda rapida di Markdown copre gli elementi di formattazione essenziali.

Markdown non è una sola lingua

La sintassi originale di Markdown era intenzionalmente piccola e specificata in modo vago. Questo la rendeva facile da leggere e implementare, ma diversi parser hanno iniziato a interpretare l’input ambiguo in modo diverso.

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

Pandoc Markdown adotta un approccio diverso. Invece di restare una sintassi piccola e orientata al web, aggiunge funzionalità per documenti come citazioni, metadati, note a piè di pagina, elenchi di definizioni, attributi e notazione matematica.

Una relazione semplificata è la seguente:

Questa gerarchia è utile, ma non è un’eredità esatta in ogni implementazione. Ogni renderer può abilitare, disabilitare o aggiungere sintassi indipendentemente.

La risposta breve

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

Usa GFM quando scrivi file README, pull request, modelli di issue e documentazione tecnica destinati 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 funzioni solo perché Hugo è descritto come compatibile con GFM.

Opinione personale: se ti devi ricordare una sola regola per un blog tecnico Hugo, tratta CommonMark più tabelle e elenchi di attività in stile GFM come predefinito, e tratta tutto il resto — note a piè di pagina, matematica, avvisi, attributi di intestazione — come un’estensione esplicita e testata, non come un predefinito assunto. Questa singola abitudine previene la maggior parte dei fallimenti di portabilità descritti qui sotto.

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 il parsing consistente.

Definisce come i parser dovrebbero interpretare:

• Paragrafi
• Intestazioni ATX e Setext
• Citazioni in blocco
• Elenco ordinati e non ordinati
• Blocchi di codice con recinti e rientrati
• Enfasi ed enfasi forte
• Link e immagini
• Link in stile di riferimento
• Codice inline
• Interruzioni tematica
• Blocchi HTML grezzi
• Interlinee hard e soft

Un documento CommonMark può comunque comportarsi diversamente al livello di presentazione. CSS, evidenziazione della sintassi, ancoraggi delle intestazioni, sanitizzazione HTML e politiche di 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 renderer produca una pagina identica.

Un Esempio Portabile di CommonMark

# Service Deployment

The service exposes a small HTTP API.

## Requirements

- Linux
- Docker
- 8 GB of memory

## Start the service

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

See the [configuration guide](configuration.md) for details.

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

GitHub Flavored Markdown: CommonMark per i 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 di GFM aggiunge:

• Tabelle con pipe
• Elementi di elenco di attività
• Barratura
• Autolink estesi
• Restrizioni su alcuni tag HTML grezzi

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

Tabelle GFM

| Backend | Best use |
|---|---|
| Ollama | Local experiments |
| vLLM | Shared inference |
| SGLang | Structured workloads |

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

Elenco di Attività GFM

- [x] Install Docker
- [x] Download the model
- [ ] Add monitoring

La sintassi di elenco di attività è utile nelle issue, nelle pull request e nella documentazione del progetto. Al di fuori di un renderer supportante, può apparire come un elenco ordinario contenente parentesi quadre letterali.

Barratura GFM

Use the ~~old endpoint~~ new endpoint.

La barratura è ampiamente supportata, ma è comunque un’estensione e non una sintassi CommonMark portabile.

Autolink GFM

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

Visit https://example.com/docs for details.

Nel CommonMark rigoroso, gli autolink espliciti usano parentesi angolari:

<https://example.com/docs>

La forma esplicita è più sicura quando un documento deve attraversare processori Markdown sconosciuti.

GitHub.com Supporta Più del Formale GFM

Una fonte frequente di confusione è l’assunzione che ogni funzionalità di 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 a commit
• Shortcode Emoji
• Sezioni HTML comprimibili
• Anteprime dei colori
• Link relativi al repository
• Ancoraggi di intestazione automatici

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

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

Diagrammi Mermaid su GitHub

GitHub renderizza un blocco di codice con recinti contrassegnato mermaid come un diagramma:

```mermaid
flowchart LR
    A[Markdown] --> B[Rendered diagram]
```

Un renderer GFM generico potrebbe visualizzare lo stesso blocco come codice sorgente evidenziato. Il Markdown resta valido, ma la renderizzazione migliorata è specifica della piattaforma. Per un’introduzione pratica alla sintassi Mermaid, vedere l’introduzione rapida ai diagrammi Mermaid.

Espressioni Matematiche su GitHub

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

The cache size is approximately $2nlhd$ bytes.

$$
C = 2nlhd
$$

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

Avvisi su GitHub

GitHub supporta citazioni in blocco in stile avviso come:

> [!WARNING]
> Changing this setting clears the cache.

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

Questo fallback è leggibile, il che rende gli avvisi di GitHub meno pericolosi di estensioni che spariscono completamente. Sono comunque elementi di presentazione non portabili.

Pandoc Markdown: Markdown come Lingua per Documenti

Pandoc Markdown è progettato per la conversione di documenti e non 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
• Multipli formati di tabelle
• Elenco di definizioni
• Notazione matematica
• Identificatori e attributi di intestazione
• Attributi dei blocchi di codice
• Divisioni con recinti
• Span tra parentesi quadre
• Sovrascript e sottoscript
• Strikeout
• Blocchi di riga
• Elenco 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 Pie’ di Pagina Pandoc

Markdown has several incompatible dialects.[^dialects]

[^dialects]: CommonMark, GFM, and Pandoc Markdown are three
    important examples.

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 e non una garanzia formale GFM. Un renderer che afferma solo compatibilità con CommonMark o GFM potrebbe non supportarle.

Citazioni Pandoc

PagedAttention improves KV cache memory management
[@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 di citazione resta leggibile in un renderer non supportante, ma non diventerà un riferimento formattato senza Pandoc o un altro processore di citazioni compatibile. La flessibilità lato lettore di Pandoc sostiene anche i flussi di conversione nella direzione opposta — vedere la conversione di documenti Word in Markdown per un esempio pratico dell’uso del dialetto esteso di Pandoc come formato intermedio.

Elenco di Definizioni Pandoc

CommonMark
: A precise specification for core Markdown.

GFM
: A CommonMark-based dialect with software-oriented extensions.

Pandoc Markdown
: An extended authoring format for document conversion.

Gli elenchi di definizioni sono utili nei manuali, nei glossari e nei libri tecnici. Di solito degradano male nei renderer che non li supportano perché le righe con i due punti restano visibili come testo semplice.

Attributi di Intestazione Pandoc

## Cache Configuration {#cache-config .deployment}

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

Questo è uno degli esempi più chiari di sintassi utile che non dovrebbe essere posta in un documento atteso da renderizzare ovunque.

Divisioni con Recinti Pandoc

::: warning
Changing this option restarts the server.

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

La maggior parte dei renderer CommonMark e GFM non riconosce il recinto. 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, le pull request, le discussioni e i wiki, GFM è la linea di base naturale.

In generale si può usare:

• Sintassi CommonMark
• Tabelle
• Elenco di attività
• Barratura
• Autolink estesi
• Code fence con evidenziazione della sintassi
• Riferimenti specifici di GitHub
• Matematica supportata da GitHub
• Diagrammi supportati da GitHub
• Avvisi GitHub
• Note a piè di pagina dove supportate dalla superficie di contenuto

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

Per i file del repository che sono anche pubblicati altrove, testare la sorgente nel secondo renderer anziché trattare l’anteprima di GitHub come autorevole.

Quale Sintassi Funziona in Hugo?

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

In una configurazione Hugo tipica, i seguenti funzionano bene:

• Struttura CommonMark
• Blocchi di codice con recinti
• Tabelle con pipe
• Barratura
• Elenco di attività
• ID di intestazione automatici
• Evidenziazione della sintassi
• Note a piè di pagina quando l’estensione è abilitata
• Elenco di definizioni quando abilitati
• Sostituzioni tipografiche quando abilitate

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

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

Queste funzionalità di Hugo non viaggiano con il file Markdown. Per un esempio pratico di deployment di Hugo, vedere Deployare Hugo su AWS S3.

Il Front Matter di Hugo Non È Contenuto Markdown

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

---
title: "Markdown Compatibility"
description: "Compare Markdown dialects and renderers."
date: 2026-07-31
tags:
  - Markdown
  - documentation
---

Pandoc può anche riconoscere blocchi di metadati YAML, ma interpreta i campi secondo i propri template e scrittori. GitHub di solito 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 di default in una configurazione Hugo standard.

Un blocco come:

<div class="notice">
  Restart the service after changing this value.
</div>

può essere omesso a meno che la renderizzazione HTML grezza non sia abilitata 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 la sorgente meno portabile e dovrebbe essere una decisione deliberata a livello di sito.

Mermaid in Hugo

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

GitHub e Hugo possono quindi accettare la stessa sorgente Mermaid usando meccanismi di renderizzazione completamente diversi.

Quale Sintassi Funziona in Pandoc?

Pandoc può leggere diversi dialetti Markdown esplicitamente:

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

Questo è una delle funzionalità di portabilità più utili di Pandoc. L’operatore può dire a Pandoc quale dialetto la sorgente afferma di usare, invece di affidarsi a una vaga estensione di file .md.

Pandoc consente anche di abilitare o disabilitare estensioni individuali:

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

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

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

Si possono ispezionare le estensioni disponibili con:

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

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

Quale Sintassi Funziona in Obsidian?

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

Esempi comuni includono:

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

Un wiki link come:

[[Markdown Compatibility]]

è significativo all’interno di una cassetta Obsidian. GitHub, CommonMark e un lettore Pandoc predefinito di solito lo visualizzano come testo tra parentesi quadre letterale.

Un incorporamento è ancora più specifico dell’applicazione:

![[compatibility-table]]

Il contenuto di riferimento non è presente nel file stesso. L’export o la pubblicazione della nota richiede quindi un passo di espansione che risolva l’incorporamento.

Obsidian è un buon esempio del perché la memorizzazione in file .md non garantisce la portabilità di Markdown. Per uno sguardo pratico su Obsidian come strumento di gestione delle conoscenze, vedere Obsidian per la Gestione delle Conoscenze Personali.

Quale Sintassi Funziona in GitLab?

GitLab Flavored Markdown usa CommonMark come suo nucleo e include funzionalità GFM come tabelle e elenchi di attività. Poi aggiunge comportamento specifico di GitLab inclusi cross-riferimenti, notazione matematica, diagrammi e altre funzionalità di collaborazione.

Un README scritto in GFM conservativo di solito si muove tra GitHub e GitLab senza gravi danni.

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

Matrice di Supporto della Piattaforma

Questa matrice descrive il comportamento predefinito comune. I temi, i plugin, le estensioni e la configurazione possono cambiare celle individuali.

“Sì” non garantisce comunque HTML o presentazione visiva identici. Significa che l’ambiente riconosce la funzionalità generale.

Sintassi che è di Solito 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 con recinti usando backtick
• Codice inline usando backtick
• Enfasi usando *testo*
• Enfasi forte usando **testo**
• Link ordinari
• Immagini ordinarie
• Citazioni in blocco
• Interruzioni tematica
• Autolink espliciti tra parentesi angolari

Un documento intenzionalmente conservativo potrebbe sembrare questo:

# Deployment Guide

This guide explains how to deploy the service.

## Requirements

- Docker
- Linux
- A supported GPU

## Configuration

Create a file named `compose.yaml`.

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

For more information, see the [configuration reference](config.md).

> Back up existing data before upgrading.

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 dal CommonMark rigoroso.

Una tabella può degradare in testo illeggibile quando passa attraverso un parser che non la riconosce. Per documenti altamente portabili, considerare elenchi brevi o HTML semantico generato durante un passo di build.

Note a Pie’ di Pagina

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

Diversi strumenti possono:

• Supportare solo un formato di note a piè di pagina
• Posizionare le note a piè di pagina in modo diverso
• Generare identificatori diversi
• Rifiutare note a piè di pagina su più paragrafi
• Renderizzare la sorgente letteralmente

Usare note a piè di pagina quando la pipeline di pubblicazione è nota. Evitare di fare affidamento su di esse in file README che devono renderizzarsi su sistemi arbitrari.

ID e Attributi di Intestazione

Questa sintassi Pandoc non è portabile:

## Installation {#installation .procedure}

Usare un’intestazione ordinaria e lasciare che il renderer generi il proprio ancoraggio quando la portabilità è importante.

Evitare anche di codificare in modo rigido link a ID di intestazione generati automaticamente a meno che ogni destinazione non usi le stesse regole di slugification.

Avvisi e Alert

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

Un fallback portabile è una citazione in blocco ordinaria:

> Warning: Back up the database before upgrading.

È meno impressionante visivamente, ma preserva il significato ovunque.

Wiki Link

I wiki link sono concisi all’interno degli strumenti di gestione delle conoscenze:

[[KV Cache]]

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

Usare link Markdown standard nel contenuto destinato alla pubblicazione:

[KV cache](kv-cache.md)

HTML Grezzo

L’HTML grezzo è l’uscita di sicurezza usuale quando Markdown non può esprimere un layout. È anche un comune fallimento di portabilità e sicurezza.

Un renderer può:

• Rimuovere l’HTML
• Escapare
• Sanificare elementi selezionati
• Permettere blocchi ma non elementi inline
• Rifiutare il parsing di Markdown dentro l’HTML
• Passarlo invariato solo in modalità fidata

Usare HTML grezzo solo quando la destinazione di pubblicazione è controllata.

Notazione Matematica

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

La sorgente:

The complexity is $O(n^2)$.

può diventare:

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

Scegliere una pipeline matematica e testarla in ogni ambiente di destinazione.

Blocchi di Diagrammi Mermaid e Altri

Un code fence Mermaid è sintatticamente sicuro perché i renderer non supportanti di solito lo visualizzano come codice.

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

Questo è un degradamento elegante, non una vera compatibilità.

I Tre Livelli di Compatibilità di Markdown

Aiuta a separare la compatibilità in tre livelli.

Livello 1: Compatibilità di Parsing

Il parser riconosce la struttura?

Esempi includono intestazioni, tabelle, note a piè di pagina e divisioni con recinti.

Livello 2: Compatibilità di Trasformazione

La piattaforma applica elaborazioni aggiuntive?

Esempi includono:

• Renderizzare Mermaid
• Risolvere citazioni
• Espandere wiki link
• Collegare numeri di issue
• Elaborare shortcode
• Generare un indice

Livello 3: Compatibilità di Presentazione

Il risultato sembra e si comporta in modo appropriato?

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 sintassi identiche producendo presentazioni sostanzialmente diverse.

Un Modello di Portabilità Migliore

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

1. In quale dialetto è scritta la sorgente?
2. Quale parser la legge?
3. Quali estensioni sono abilitate?
4. Quali trasformazioni di piattaforma vengono eseguite dopo?

Ad esempio:

Dialect: CommonMark plus GFM tables
Parser: Goldmark
Extensions: tables, strikethrough, task lists, footnotes
Platform: Hugo
Additional processing: render hooks and Mermaid JavaScript

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

Scegliere un Dialetto per Caso d’Uso

File README

Usa GFM.

I file README beneficiano di:

• Tabelle
• Elenco di attività
• Code fence
• Autolink
• Barratura
• Riferimenti GitHub

Evitare un’eccessiva dipendenza da funzionalità solo di GitHub quando il repository è mirrorizzato su GitLab, renderizzato in un registro di pacchetti o incluso in documentazione generata.

Articoli Tecnici Hugo

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

Tabelle, code fence, note a piè di pagina e Mermaid possono essere ragionevoli perché si controlla la pipeline di build. Preferire shortcode o render hook di Hugo rispetto all’incorporamento di grandi quantità di HTML grezzo.

Mantenere 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, cross-riferimenti e conversione in PDF o DOCX giustificano la ridotta portabilità.

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

Libri e Documentazione di Lungo Formato

Pandoc Markdown è di solito la più forte delle tre opzioni quando più formati di output sono importanti.

Elenchi di definizioni, citazioni, attributi, metadati e trasformazioni strutturate diventano più importanti al crescere della complessità del documento.

Per documentazione solo per web ospitata in un repository Git, GFM o un generatore di documentazione basato su CommonMark può rimanere più semplice.

Note e Basi di Conoscenza Personali

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

I wiki link, gli incorporamenti e gli avvisi di Obsidian sono utili all’interno di una cassetta. Trattare l’export come un processo di compilazione piuttosto che assumere che i file grezzi siano già pubblicazioni portabili.

Documentazione Condivisa tra Sistemi Sconosciuti

Usa un sottoinsieme CommonMark conservativo.

Evitare:

• Wiki link
• Alert di piattaforma
• Attributi di intestazione
• Citazioni
• HTML grezzo
• Containner personalizzati
• Incorporamenti di applicazioni
• Shortcode

La portabilità richiede di solito di rinunciare a funzionalità di comodità.

Regole Pratiche per Markdown Portabile

Iniziare con la Struttura CommonMark

Usa CommonMark per lo scheletro del documento:

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

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

Aggiungere Funzionalità GFM Deliberatamente

Tabelle e elenchi di attività sono ragionevoli quando tutti i target importanti li supportano.

Non assumere che “la maggior parte degli strumenti supporta GFM” senza testare il target esatto. Alcuni affermano compatibilità GFM abilitando solo estensioni selezionate.

Isolare le Estensioni di Piattaforma

Mantenere la sintassi specifica della piattaforma in blocchi chiaramente identificabili.

Ad esempio, centralizzare gli shortcode di Hugo, le citazioni di Pandoc o gli incorporamenti di Obsidian invece di spargerli attraverso ogni paragrafo.

L’isolamento rende più facile la conversione successiva.

Preferire il Degradamento Elegante

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

Un incorporamento wiki può degradare in un nome di file non spiegato, mentre una divisione con recinti di Pandoc può esporre la punteggiatura attorno al contenuto.

Scegliere estensioni il cui fallback resta comprensibile.

Non Fare Affidamento su ID di Intestazione Generati Automaticamente

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

Per i link tra documenti, usare ID espliciti supportati dal renderer solo quando la pipeline di destinazione è controllata. Altrimenti, collegarsi al documento piuttosto che a un frammento generato.

Mantenere la Configurazione di Build con il Contenuto

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

Commitare i file di configurazione rilevanti con la sorgente:

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

Una sola estensione .md non cattura l’ambiente di pubblicazione. Per un approccio strutturato alla documentazione di queste decisioni, vedere Decision Records per lo Sviluppo Guidato dall’AI.

Testare Markdown contro Ogni Target Importante

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

Per Pandoc, testare 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

I warning e la punteggiatura della sorgente visibile rivelano quali funzionalità sono specifiche del dialetto.

Per Hugo, costruire il sito di produzione:

hugo --gc --minify

Poi ispezionare l’HTML generato invece di affidarsi solo a un’anteprima dell’editor.

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

Risoluzione dei Problemi di Rendering Comuni

Quando un file che funzionava su una piattaforma si rompe su un’altra, il fallimento di solito rientra in uno dei pochi modelli ripetibili. La tabella seguente elenca il sintomo come lo si vedrebbe effettivamente, la causa più probabile e un comando o controllo concreto per confermarlo e correggerlo.

Questa è la prima passata più veloce prima di assumere un “bug” di Markdown — la maggior parte di questi disallineamenti è un’estensione mancante o una funzionalità solo di piattaforma, non sintassi rotta. Per problemi specifici dei code fence come la mancata evidenziazione della sintassi o gli identificatori di lingua non supportati, vedere la guida dedicata sui blocchi di codice Markdown.

Lint del Sottoinsieme Portabile

Un linter di Markdown non può garantire la compatibilità del renderer, ma può rimuovere ambiguità evitabili.

Le regole utili includono:

• Usare stili di intestazione coerenti
• Aggiungere righe vuote attorno a elenchi e blocchi di codice
• Usare code fence invece di codice rientrato
• Specificare le lingue dei code fence
• Evitare livelli di intestazione saltati
• Usare marcatori di elenco coerenti
• Evitare enfasi ambigua attorno alla punteggiatura
• Mantenere le interlinee coerenti
• Validare link e immagini

Per la pubblicazione multi-target, aggiungere un test di build per ogni renderer importante invece di affidarsi solo al lint della sintassi.

Convertire 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 perdite potenziali includono:

• Riferimenti specifici della piattaforma
• Stile degli avvisi
• Tabelle complesse
• Oggetti incorporati dell’applicazione
• Attributi personalizzati
• Comportamento di HTML grezzo
• Sintassi di plugin
• Rendering di diagrammi
• Spaziatura e formattazione esatta

Pandoc preserva la struttura del documento meglio della formattazione della sorgente originale. Trattare la conversione come un passo di build, non come un formatter di testo reversibile.

Strategia Raccomandata per i Siti Hugo

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

1. Usare CommonMark per il testo e la struttura di base.
2. Abilitare un piccolo set documentato di estensioni Goldmark.
3. Usare tabelle e elenchi di attività in stile GFM dove migliorano la leggibilità.
4. Implementare Mermaid attraverso un unico render hook o shortcode coerente.
5. Gestire la matematica attraverso un’unica pipeline documentata KaTeX o MathJax.
6. Usare il front matter di Hugo solo all’inizio dei file di contenuto.
7. Preferire render hook e shortcode rispetto all’HTML grezzo.
8. Mantenere i link sorgente come link Markdown standard dove possibile.
9. Testare i documenti migrati o provenienti dall’esterno attraverso Hugo.
10. Documentare qualsiasi sintassi che non si renderizzerebbe correttamente su GitHub.

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

L’approccio peggiore è il mescolamento accidentale di dialetti: avvisi di GitHub, incorporamenti di Obsidian, attributi di Pandoc e shortcode di Hugo posti nello stesso documento senza una pipeline di build definita.

Tabella delle Decisioni

Conclusione

CommonMark, GitHub Flavored Markdown e Pandoc Markdown non sono versioni in competizione 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 una lingua sorgente ricca per la pubblicazione e la conversione.

La regola più sicura è semplice: scrivere il dialetto più piccolo che soddisfa la destinazione reale. Usare 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 contano più della renderizzazione universale.

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

Riferimenti

• Specifiche CommonMark
• Specifiche GitHub Flavored Markdown
• Pandoc Markdown
• Documentazione Goldmark
• Configurazione Goldmark di Hugo
• Scrittura di Espressioni Matematiche su GitHub