Pandoc è uno strumento potente e versatile, creato nel 2006 da John MacFarlane, professore di filosofia a Berkeley (Wikipedia), per la conversione di documenti da un formato all’altro. Come si può intuire dalla sua origine, è ampiamente utilizzato in ambito accademico, dove non di rado il flusso di lavoro richiede l’uso documenti di vari formati, primi fra tutti quelli richiesti dalle riviste o dalle case editrici.

Pandoc è disponibile per tutti i principali sistemi operativi (Windows, macOS, Linux): l’installer e le le istruzioni per l’installazione sono disponibili sul sito ufficiale (in inglese, ma è molto intuitivo).

Da qualche tempo, Pandoc viene installato e aggiornato insieme ad RStudio, ed è lo strumento usato da RMarkdown e Quarto per produrre report e documenti in vari formati, senza alcun intervento da parte nostra. È bene però, per un uso un po’ più avanzato, comprendere in che modo RMarkdown e Quarto lavorano, per così dire, “sotto il cofano”.

Conoscere il suo funzionamento può infatti servire per usare meglio:

• Le opzioni del front matter, che sono perlopiù opzioni di Pandoc;
• I modelli di documento, ad esempio quelli di Word o PowerPoint;
• e i riferimenti bibliografici.

Inoltre, Pandoc potrà tornare utile anche per importare contenuti in un documento/report RMarkdown o Quarto (ad esempio, da un documento Word), passando per Markdown.

Pandoc funziona da riga di comando, quindi da terminale. La sintassi di base è:

pandoc [input_file] -o [output_file]

Per evitare problemi relativi al percorso, è consigliabile aprire il terminale direttamente nella cartella in cui è presente il file da convertire. Ad esempio, il terminale del progetto di RStudio è aperto nella cartella di lavoro.

Se all’interno della cartella ci fosse un file Word da trasformare in Markdown, per essere usato in RMarkdown, basterebbe scrivere:

pandoc input.docx -o output.md

per avere — nella stessa cartella — un documento md immediatamente utilizzabile.

Generalmente, non è necessario specificare il formato che Pandoc interpreta dalle estensioni dei file. Se però si vuole un formato Markdown specifico, ad esempio il GitHub-flavored, questo può essere specificato con -t (to) o con -f (from se si tratta del formato di partenza):

pandoc input.docx -t gfm -o output.md

Molte opzioni possono essere inserite direttamente nel front matter (o frontmatter), come si vede nella Fig. 1.

Ad esempio, quando devo scrivere una pagina di questa wiki a partire da un documento Rmd che contiene il codice, prima lo converto in markdown da RStudio (in modo che contenga anche l’output), indicando il formato di output nel front matter:

---
title: "Laboratorio di analisi dei dati con R"
subtitle: 'Unità 6: Modelli lineari generalizzati'
author: 'Agnese Vardanega'
date: "maggio 2025"
output:
  github_document: default
---

Poi, da terminale, lo converto nel formato di dokuwiki:

pandoc input.md -t dokuwiki -o output.txt

Pandoc offre molte opzioni per personalizzare l’output. In pratica, oltre ai formati, è possibile indicare molte altre opzioni che consentono di avere un controllo granulare sul tipo di file nel risultato: dimensioni della pagina, caratteri, intestazioni e pié di pagina, e quant’altro.

pandoc [input_file] -o [output_file] [opzioni]

Come detto, il metodo più semplice e diretto è quello di inserire la gran parte di queste opzioni (variabili e valori di variabili) nel front matter, il blocco YAML del file Markdown.

Ad esempio, per elaborare i riferimenti bibliografici, il comando da terminale sarebbe:

pandoc input.md --citeproc --bibliography mia-biblio.bib --csl apa.csl -o output.docx

Ma, come illustrato qui, possiamo scrivere:

---
title: "Mio documento"
bibliography: mia-biblio.bib
csl: apa.csl
lang: it
---

RStudio elaborerà il tutto senza bisogno di digitare nulla da riga di comando, che comunque sarebbe semplificata:

pandoc input.md -o output.docx --citeproc

Un altro sistema relativamente semplice per controllare l'aspetto e il formato di un documento, ad esempio LaTeX, Word e PowerPoint, è utilizzare modelli personalizzati (templates).

Il modo più affidabile per creare un template — ad esempio per Word — è:

• creare un file Word con Pandoc (o RMarkdown in RStudio);
• aprirlo e modificare il formato di pagina e gli stili di testo;
• salvarlo con un altro nome (ad esempio: modello.docx).

Indichiamo infine il modello con la variabile template nel blocco YAML (sempre facendo attenzione alla cartella in cui sono i documenti, naturalmente)

---
title: "Mio documento"
bibliography: mia-biblio.bib
csl: apa.csl
template: modello.docx
lang: it
---

E rigeneriamo il file da RStudio o da altro editor.

Da riga di comando, e senza usare il front matter:

pandoc input.md -o output.docx --template modello.docx

Quando si converte in HTML, è possibile specificare un file CSS per personalizzare lo stile dell’output. Anche il css può essere indicato nel front matter,

pandoc input.md -o output.html --css mystyle.css

Markdown: i riferimenti bibliografici

Esistono diversi programmi che possono fungere da interfaccia grafica e semplificare l’uso di Pandoc. Oltre ad offrire un ambiente di scrittura Markdown con anteprima in tempo reale, generalmente questi editor facilitano la gestione dei metadati del documento, e naturalmente l’importazione e l’esportazione dei documenti in vari formati.

Fra i molti in circolazione, ne suggerisco due, uno gratuito e uno a pagamento:

• Fra gli editor gratuiti, PanWriter è a mio parere il più versatile e semplice da usare per quanto riguarda l’importazione e l’esportazione dei formati; non ha un editor visuale come quello che troviamo in RStudio, ma un riquadro di anteprima; non apre i file RMarkdown e Quarto.

• Fra quelli a pagamento, suggerisco invece Typora perché, oltre ad avere un bell’editor visuale, lavora con i file RMarkdown e Quarto, che possono essere quindi modificati senza “distrazioni”.

Entrambe queste applicazioni permettono di selezionare i formati di output desiderati con pochi clic, e possono essere considerate appunto interfacce per Pandoc.