Markdown in Word da riga di comando: guida Pandoc

Per portare Markdown in Word dalla riga di comando la risposta è pandoc, e tutto il lavoro sta in una riga:

pandoc report.md -f gfm -o report.docx

Quel comando basta per la maggior parte dei documenti. Ciò che i tutorial da una riga non raccontano è dove smette di funzionare — e una parte di quello che si legge in giro sui limiti di pandoc è semplicemente superata. Ho eseguito pandoc 3.7.0.2 su un documento di prova zeppo di tabelle, elenchi di attività, equazioni LaTeX e un diagramma Mermaid, poi ho decompresso il .docx risultante per vedere cosa ne era uscito davvero. Alcuni risultati mi hanno sorpreso.

In questa guida trovi installazione, i comandi che vale la pena conoscere, lo styling del DOCX, la conversione batch e — sulla base di quel test — una mappa onesta dei punti in cui pandoc si inceppa e dei casi in cui un convertitore online è la scelta più sensata.

👉 Vai ai risultati del test | Salta al confronto CLI vs online

Installare Pandoc

Pandoc è un singolo binario, con installer per ogni piattaforma principale:

• macOS: brew install pandoc
• Windows: winget install --id JohnMacFarlane.Pandoc (oppure l'installer MSI)
• Debian/Ubuntu: sudo apt install pandoc

Un avvertimento prima di fidarti di un vecchio pacchetto di sistema: i repository delle distribuzioni spesso distribuiscono versioni di pandoc indietro di anni. Ubuntu LTS ha fornito a lungo la 2.x, mentre la linea di rilascio attuale è la 3.x — e come vedrai più avanti, l'età della versione cambia cosa viene convertito in modo pulito. Controlla la tua con pandoc --version.

Il comando base, spiegato

Il comando minimo funziona, ma nei progetti reali il grosso del lavoro lo fanno tre flag:

pandoc report.md -f gfm -o report.docx --toc

Perché -f gfm invece del dialetto Markdown predefinito di pandoc? Perché il Markdown che quasi tutti scrivono oggi — nei README di GitHub, nelle risposte di ChatGPT e Claude, negli export di Notion — è GFM. Il dialetto predefinito di pandoc è più accademico: abilita note a piè di pagina e citazioni, ma interpreta alcuni costrutti in modo diverso. Se la tua sorgente arriva da un assistente AI o da uno strumento per sviluppatori, gfm è il lettore più sicuro.

Nota sulla matematica: con il lettore GFM, le formule $...$ e $$...$$ funzionano e basta nelle versioni attuali di pandoc. Le equazioni diventano equazioni Word native, non immagini. Ci torniamo più avanti, perché è il comportamento di pandoc più travisato sul web.

Dare uno stile all'output con un reference document

Un DOCX generato da pandoc si apre in Word con uno stile generico. Se il documento deve rispettare un template aziendale, non lo sistemi con dei flag — usi un reference document.

Il flusso ha tre passaggi:

1. Genera il template predefinito di pandoc come punto di partenza:

   pandoc -o custom-reference.docx --print-default-data-file reference.docx
   

2. Apri custom-reference.docx in Word e modifica gli stili — Heading 1, Normal, Table, blocchi di codice. Il contenuto testuale del file viene ignorato; passano solo gli stili e l'impostazione della pagina.

3. Converti applicando il template:

   pandoc report.md -f gfm --reference-doc=custom-reference.docx -o report.docx
   

Il manuale di pandoc documenta quali nomi di stile vengono rispettati. Il modello mentale che fa scattare tutto: non stai formattando un documento, stai insegnando a pandoc gli stili Word della tua organizzazione una volta sola, per riutilizzarli a ogni conversione.

Conversione batch di più file

Qui la riga di comando batte davvero qualsiasi strumento web. Per convertire un'intera cartella:

Bash (macOS/Linux):

for f in docs/*.md; do
  pandoc "$f" -f gfm -o "${f%.md}.docx"
done

PowerShell (Windows):

Get-ChildItem docs -Filter *.md | ForEach-Object {
  pandoc $_.FullName -f gfm -o ($_.FullName -replace '\.md$', '.docx')
}

E siccome pandoc è un'unica dipendenza, entra in CI senza cerimonie. Uno step di GitHub Actions che rigenera le copie Word della documentazione a ogni push somiglia a questo:

- uses: pandoc/actions/setup@v1
- run: |
    for f in docs/*.md; do
      pandoc "$f" -f gfm --reference-doc=brand.docx -o "out/$(basename "${f%.md}").docx"
    done

I team usano questo schema per mantenere una copia Word di un wiki Markdown per revisioni di conformità o consegne ai clienti. Se converti lo stesso insieme di file più di due volte, lo script si ripaga da subito.

Dove Pandoc mostra i suoi limiti (testato su 3.7)

Ecco il test che ho fatto. Un unico file Markdown con una tabella, un elenco di attività, matematica inline ($E = mc^2$), un'equazione display su più righe, un flowchart Mermaid e un blocco alert GFM. Convertito con pandoc 3.7.0.2; poi ho decompresso il .docx e letto direttamente word/document.xml. Tre risultati.

La matematica funziona meglio di quanto ti abbiano detto

L'XML del documento contiene due blocchi <m:oMath> — uno per equazione. È OMML, il formato nativo delle equazioni di Word. Entrambe le equazioni sono pienamente modificabili nell'editor di equazioni di Word, hanno una resa da stampa e sopravvivono al copia-incolla verso altri documenti Office.

Questo smentisce un'affermazione che si trova ancora nei tutorial più vecchi (e, fino a poco tempo fa, in una delle nostre stesse guide): che il LaTeX complesso venga rasterizzato in immagini. Nel pandoc attuale non succede. La matematica LaTeX standard — frazioni, sommatorie, lettere greche, pedici — si converte in equazioni native senza configurazione aggiuntiva.

Il confine onesto: pandoc risolve la sintassi matematica LaTeX standard, non LaTeX arbitrario. Le macro personalizzate \newcommand, le figure TikZ e gli ambienti che dipendono da pacchetti non arriveranno a destinazione. E se la tua distribuzione ha installato pandoc 2.x, il comportamento è diverso — controlla pandoc --version prima di dare la colpa allo strumento.

Mermaid è il vero punto di rottura

Il flowchart Mermaid non è diventato un diagramma. È passato come testo monospazio letterale — il sorgente flowchart LR grezzo, formattato come blocco di codice. L'XML del documento mostra zero oggetti di disegno.

La cosa pesa più oggi che cinque anni fa, perché gli assistenti AI adorano Mermaid. Chiedi a ChatGPT o Claude una panoramica di architettura e c'è un'ottima probabilità che la risposta includa un blocco di codice mermaid. Converti quella conversazione con pandoc e il tuo documento Word conterrà quello che sembra codice sorgente dimenticato lì. Se il tuo flusso di lavoro è questo, la nostra guida su come esportare l'output di ChatGPT in Word copre i dettagli specifici dell'AI.

Un rimedio da CLI esiste: mermaid-filter, un filtro pandoc che renderizza i diagrammi durante la conversione. Funziona, ma valuta il costo di setup con onestà — è un pacchetto npm che si porta dietro un Chromium headless via Puppeteer, e l'invocazione diventa pandoc -F mermaid-filter .... Per una pipeline di documentazione che converte diagrammi ogni giorno, quel costo si ammortizza. Per un report da consegnare questo pomeriggio, è una deviazione.

Piccole perdite di fedeltà ai margini

Due risultati più silenziosi dallo stesso test. I blocchi alert GFM (> [!NOTE]) conservano il testo ma perdono il riquadro colorato — in Word si leggono come normali citazioni. E le voci degli elenchi di attività arrivano come semplice testo di elenco, non come controlli casella di Word. Nessuno dei due rompe il documento; entrambi appiattiscono una formattazione che l'autore probabilmente aveva scelto apposta. Se la tua conversione va storta in altri modi, abbiamo catalogato i casi di errore più frequenti in problemi comuni di conversione Markdown.

Riga di comando o convertitore online?

Dopo quel test, ecco il criterio di scelta che userei davvero:

Entrambe le strade sono legittime. Pandoc si guadagna il posto in qualsiasi pipeline ricorrente. Per il caso una tantum "mi serve come .docx nei prossimi cinque minuti" — soprattutto se c'è di mezzo Mermaid — un convertitore online gratuito da Markdown a Word ti restituisce un documento pulito con le equazioni e i diagrammi renderizzati, senza installare nulla.

Domande frequenti

D: Posso convertire Markdown in Word senza installare niente?
R: Non dalla riga di comando — pandoc va installato. Se installare software non è un'opzione, i convertitori nel browser sono la via pratica; la conversione avviene lato server e scarichi il .docx finito.

D: Pandoc converte la matematica LaTeX in vere equazioni Word?
R: Sì. Nel mio test con Pandoc 3.7.0.2, sia la matematica inline sia quella display sono diventate equazioni OMML native, modificabili nell'editor di equazioni di Word. Le eccezioni sono le versioni di pandoc molto vecchie e le macro LaTeX personalizzate.

D: Perché il mio diagramma Mermaid compare come codice in Word?
R: Pandoc tratta un blocco di codice mermaid come codice letterale — non renderizza diagrammi. Puoi aggiungere mermaid-filter alla tua pipeline (richiede Node.js) oppure usare un convertitore con rendering Mermaid integrato.

D: Come conservo i font e gli stili dei titoli della mia azienda?
R: Usa --reference-doc=template.docx. Modifica gli stili in quel template una volta sola in Word; pandoc li applica a ogni conversione. Il contenuto del template viene ignorato, passano solo gli stili.

D: Che differenza c'è tra -f markdown e -f gfm?
R: markdown è il dialetto esteso di pandoc (note a piè di pagina, citazioni); gfm corrisponde a ciò che producono GitHub, ChatGPT e la maggior parte degli strumenti moderni — tabelle, elenchi di attività, testo barrato. Per Markdown generato dall'AI o scritto da sviluppatori, gfm riserva meno sorprese.

D: Pandoc può riconvertire Word in Markdown?
R: Sì — inverti gli argomenti: pandoc report.docx -o report.md. Il viaggio di andata e ritorno perde parte della formattazione specifica di Word (caselle di testo, commenti), quindi trattalo come una migrazione di contenuti, non come un ciclo senza perdite.

Risorse correlate

• La guida completa da Markdown a Word: il panorama completo delle opzioni di conversione oltre la riga di comando
• ChatGPT in Word: il flusso Markdown per i documenti generati dall'AI
• Markdown in PDF: quando il risultato finale dev'essere un PDF
• Problemi comuni di conversione Markdown: rimedi per tabelle rotte, problemi di codifica e derive di formattazione

Conclusione

Pandoc resta la risposta giusta a "come converto Markdown in Word da riga di comando" — un comando per un singolo file, uno script breve per una cartella, --reference-doc per lo stile aziendale. Nel mio test con Pandoc 3.7 il supporto matematico si è rivelato migliore della sua reputazione: il LaTeX standard diventa equazioni Word vere e modificabili.

Il suo divario autentico è visivo: i diagrammi Mermaid arrivano come codice sorgente, a meno di montare una catena di filtri basata su Node. Quindi scegli in base al flusso di lavoro. Pipeline ricorrente con documenti di solo testo: automatizza con pandoc. Documento singolo con diagrammi e una scadenza: convertilo nel browser e tieni intatti equazioni e flowchart.

Riferimenti

• Pandoc User's Guide — manuale ufficiale: reader, writer, --reference-doc, gestione della matematica
• Installing pandoc — installer ufficiali per tutte le piattaforme
• mermaid-filter — filtro pandoc della community per renderizzare i diagrammi Mermaid
• pandoc/actions — GitHub Actions ufficiali per pandoc in CI