Pandoc è un programma a riga di comando che converte documenti da un formato all'altro. Legge Markdown, DOCX, HTML, LaTeX, ODT e molti altri formati, e scrive in altrettanti. È gratuito, open source e funziona su Windows, macOS e Linux.
Il suo valore pratico è permettere di scrivere una sola volta, in un formato semplice, e ottenere poi le versioni che servono: un DOCX da mandare a chi lavora in Word, un PDF da archiviare, una pagina HTML da pubblicare. Nel mio lavoro è lo strumento che chiude il cerchio tra appunti in Markdown e documenti consegnabili.
Come ragiona Pandoc
Pandoc non traduce direttamente da un formato all'altro. Legge il file di partenza, lo trasforma in una rappresentazione interna fatta di blocchi (titoli, paragrafi, elenchi, tabelle, note) e da lì genera il formato di arrivo.
Questo spiega il suo comportamento: conserva molto bene la struttura del documento e molto meno l'aspetto. Un titolo di livello 2 resta un titolo di livello 2; un colore applicato a mano in Word, invece, va perso. Se la struttura è curata, la conversione è pulita.
I comandi di base
Il formato si deduce dall'estensione dei file:
pandoc relazione.md -o relazione.docx
pandoc relazione.md -o relazione.html --standalone
pandoc relazione.docx -o relazione.md
-oindica il file di uscita.--standalone(o-s) produce un documento completo, con intestazione, invece di un frammento.- La terza riga mostra la conversione inversa: da Word a Markdown, utile per recuperare testi scritti da altri.
Per indicare formati in modo esplicito si usano -f (from) e -t (to), per esempio -f docx -t gfm.
Ottenere un PDF
Pandoc non disegna da solo i PDF: si appoggia a un motore esterno. Il più comune è LaTeX, che va installato a parte:
pandoc relazione.md -o relazione.pdf --pdf-engine=xelatex -V lang=it
XeLaTeX e LuaLaTeX gestiscono meglio i caratteri accentati e i font di sistema. In alternativa si può passare da HTML e usare un motore come WeasyPrint, che impagina con i CSS. Se l'installazione di LaTeX vi sembra pesante, esiste anche la strada più semplice: convertire in DOCX o ODT e salvare in PDF dal programma di videoscrittura.
Dare uno stile al DOCX
Per default il DOCX generato usa stili neutri. Per ottenere il vostro aspetto aziendale si usa un documento di riferimento:
- Generate il file di base:
pandoc -o riferimento.docx --print-default-data-file reference.docx. - Apritelo in Word o Writer e modificate gli stili dei titoli, del corpo del testo, delle tabelle e così via. Modificate gli stili, non il testo.
- Convertite usando quel file:
pandoc testo.md -o testo.docx --reference-doc=riferimento.docx.
Da quel momento ogni conversione eredita font, colori, margini e spaziature. È il motivo per cui conviene scrivere in Markdown anche documenti che alla fine verranno consegnati in Word.
Metadati, indice e numerazione
Titolo, autore e data possono stare nell'intestazione YAML del file Markdown oppure sulla riga di comando con -M title="...". Altre opzioni utili:
| Opzione | Effetto |
|---|---|
--toc |
Inserisce un indice dei contenuti |
--toc-depth=2 |
Limita l'indice ai primi due livelli |
-N |
Numera i titoli (1, 1.1, 1.2…) |
--resource-path=img |
Indica dove cercare le immagini |
--citeproc |
Elabora le citazioni bibliografiche |
Automatizzare con un file di configurazione
Quando le opzioni diventano tante, riscriverle ogni volta è scomodo e fonte di errori. Pandoc accetta file di impostazioni (--defaults=impostazioni.yaml) in cui elencare formato di uscita, documento di riferimento, motore PDF e filtri. In alternativa basta un piccolo script o un Makefile. Così chiunque nel gruppo ottiene lo stesso risultato con un solo comando.
Problemi frequenti
- Immagini mancanti. I percorsi sono relativi alla cartella da cui lanciate il comando, non a quella del file. Usate
--resource-patho lanciate Pandoc dalla cartella giusta. - Tabelle complesse. Celle unite e tabelle annidate di Word non hanno un equivalente in Markdown e vengono semplificate.
- Formattazione diretta persa. Grassetti e corsivi restano; colori, evidenziazioni e font scelti a mano spariscono. È un segnale che il documento originale non usava gli stili.
- Caratteri strani nel PDF. Spesso dipende dal motore: con
pdflatexalcuni caratteri Unicode falliscono, conxelatexdi solito no.
In sintesi
- Pandoc converte tra decine di formati passando per una struttura interna comune.
- Conserva bene titoli, elenchi, tabelle e note; perde la formattazione applicata a mano.
- Il PDF richiede un motore esterno, di solito XeLaTeX o LuaLaTeX.
- Con un documento di riferimento il DOCX generato prende lo stile aziendale.
- Un file di impostazioni rende le conversioni ripetibili da tutto il gruppo.
