Convertire molti file markdown in PDF

A cura di Totò Fiandaca  | issue #93 | chef Andrea Borruso Gianni Vitrano

Introduzione

Utilizzando molto GitHub è altrettanto frequente l’utilizzo del linguaggio markdowm (md), un linguaggio semplice da usare che permette la formattazione del testo in brevissimo tempo. Alcune volte nasce l’esigenza di convertire molti file *.md in PDF: esistono varie estensioni (sono stati testati alcuni in VS code oppure facendo uso della riga di comando in bash (usando Pandoc) con passaggio intermedio, cioè creazione di file odt (Libre Office Writer).

Usando Pandoc

Pandoc è convertitore universale di documenti, un tool da riga di comando.

Opzione 1

Il tool da utilizzare è pandoc (nel caso è da installare). È a riga di comando, open source e disponibile per tutti i sistemi operativi.

Il comando è:

pandoc -o output.odt --reference-doc=myPandocTemplate.odt input.md

A partire da un file Markdown di input, e da un file odt che viene usato come modello per lo stile, viene generato un file di output (sempre odt) che tiene conto degli stili del modello (intestazioni, corpo testo, larghezza pagina, header, ecc.).

Il file template è un file odt a cui assegnare/modificare gli stili che si vogliono utilizzare: se ne crea uno nuovo, con F11 si apre il pannello degli stili, si modificano/aggiungono e si salva il file.

Nota bene 1: se si vuole che le immagini presenti del file Markdown si adattino alla larghezza della pagina del file odt, bisogna impostarla al 100% (ad esempio ![](./imgs/4116_1.png){ width=100% }).

Nota bene 2: è sempre bene avere installato una versione recente di pandoc.

Opzione 2

Nella modalità soprastante, è necessario “sporcare” un po’ il file Markdown, aggiungendo il parametro sulla larghezza. Inoltre c'è da ricordarsi di farlo per ogni immagine.

pandoc consente la manipolazione dei documenti tramite il linguaggio Lua; una delle cose che consente di fare, è quella di applicare un filtro, che assegna a tutte le immagini di un documento sorgente un determinato valore di un attributo (come la larghezza).

Basta creare un file imgWidth.lua con all’interno

function Image(img)
  img.attributes.width="100%"
  return img
end

e lanciare il comando

pandoc -o output.odt --lua-filter=imgWidth.lua --reference-doc=myPandocTemplate.odt input.md

Verrà prodotto un file odt, con tutte le immagini che riempiono in larghezza il 100% dello spazio disponibile (esclusi eventuali margini). L’altezza si modificherà in proporzione.

Installare Pandoc

1. creare una cartella temporanea sul desktop;
2. avvia Bash dalla cartella;
3. lanciare questo comando wget https://github.com/jgm/pandoc/releases/download/2.7.3/pandoc-2.7.3-1-amd64.deb che scaricherà il file pandoc-2.7.3-1-amd64.deb;
4. poi, lanciare il comando: sudo dpkg -i pandoc-2.7.3-1-amd64.deb che installerà Pandoc;
5. controllo versione, lanciare il comando pandoc --version
6. lanciare il comando sudo apt-get install texlive-xetex per installare --pdf-engine

Usando VS Code e estensioni

Una estensione molto potente è Markdown Converter un’estensione del codice di Visual Studio che consente di esportare il file Markdown come file PDF, HTML o immagine. Offre molte funzionalità, come la formattazione di DateTime, la configurazione dei propri stili CSS, l’impostazione di intestazioni e piè di pagina, FrontMatter e molto altro.

dopo l’installazione, premendo F1 (Tasto funzione) e digitando Markdown:

menu a tendina con le varie possibilità per convertire: export (pdf, export (html), export (all:pdf, html, png, jpg)

Il plugin automaticamente converte tutti i file .md che si trovano nella cartella radice e sottocartelle varie.

Riferimenti utili

1. Pandoc
2. lua
3. VS code
4. Markdown Converter
5. GitHub
6. markdowm
7. Libre Office Writer