Markdown-Dateien mit Pandoc in PDF umwandeln
Pandoc ist ein freier Parser für Multidokumentenformate. Mit dem Tool lassen sich Dokumente von einem Format in ein andres Dateiformat umwandeln.
Pandoc ist das ultimative Werkzeug 🧰 🛠️ um Dokumente von einem Format in ein anderes Format zu konvertieren. Auf der Homepage wird es beschrieben als DAS "swiss-army knife", was es m.E. auch wirklich ist.
Es ist vielseitig einsetzbar und lässt sich mithilfe von Skripten, Hooks, etc. sehr flexibel einsetzen.
Pandoc muss für seine Aufgaben nicht zwingend auf dem eigenen Client 🧑💻 installiert werden, sondern kann auch auf einem Server, in einer virtuellen Umgebung oder gar in einer Docker-Umgebung 🐳 installiert werden.
Für große, umfangreiche Dokumente 📚, wie wissenschaftliche Arbeiten, Bücher, Dokumentationen, etc. ist Pandoc (Markdown-to-PDF) nicht geeignet. Dafür sollte von Anfang an LaTeX genutzt werden, das es einen erheblich größeren Funktionsumfang bietet.
Kürzlich habe ich meinen gesamten WordPress-Blog nach Markdown umgezogen und mit Material for MkDocs als statische Website erstellt.
Alle Dateien für meinen Blog liegen nun im Quellformat Markdown vor und können mit Pandoc sehr einfach in ein anderes Dateiformat umgewandelt werden. Die Informationen sind nicht mehr in einem Dateiformat oder einer Datenbank "eingesperrt".
In diesem Beispiel wird der Beitrag Deine Website mit Material for MkDocs bei Codeberg Pages in ein pdf-Dokument umgewandelt.
MacOS und Linux
Für das Umwandeln von Markdown-to-PDF mit Pandoc werden LaTeX-Pakete benötigt. Die Installation kann bei Linux und MacOS direkt in der CLI mit dem Paketmanager tlmgr erfolgen.
Für MacOS bietet sich aber auch das grafische Tool Tex Live Utility an, das mit Homebrew auf dem eigenen Client installiert werden kann.
brew install --cask tex-live-utility
Windows
In meinem Beitrag 🔗 Typora wird kostenpflichtig! Welche Alternativen gibt es und wie lassen sich Markdown-Dokumente konvertieren? habe ich beschrieben was für Windows benötigt wird.
Blogbeitrag in PDF-Datei
Für die Formatierung des Beitrags wird das Template Eisvogel verwendet, dass von GitHub abrufbar ist:
Für die Umwandlung sind die folgenden Dateien alle in den gleichen Ordner zu kopieren
- Markdown-Quelldatei
- Bild-Dateien
- Eisvogel-Datei
eisvogel.tex
Der Befehl zum Umwandeln wird auf der CLI eingegeben:
pandoc index.md -o beitrag.pdf --from markdown --template eisvogel --listings --number-section
Leider kann Pandoc keine Unicode-Zeichen umwandeln, weshalb diese Zeichen alle aus der Markdown-Datei entfernt werden müssen.
Unicode-Zeichen sind, z.B. Emojis.
Das Ergebnis ist eine schöne PDF-Datei der Markdown-Quelldatei.
Einfache PDF-Dokumente erstellen
Das Dokument README.md wird in das PDF-Dokument test.pdf umgewandelt.
pandoc README.md -o test.pdf
-o= Ausgabedatei
Einfache Formatierungen
Es lassen sich auf Vorlagen zusammen mit Pandoc verwenden. Damit können Formatierungen für genau definiert werden.
Die Vorlagen greifen dabei auf LaTeX zurück. Eine einfache Vorlage kann so aussehen
% Contents of listings-setup.tex
% Quelle: https://tex.stackexchange.com/questions/97474/how-to-add-lstlistoflistings-to-the-table-of-contents
\usepackage{xcolor}
\lstset{
basicstyle=\ttfamily,
numbers=left,
numberstyle=\footnotesize,
stepnumber=2,
numbersep=5pt,
backgroundcolor=\color{black!10},
showspaces=false,
showstringspaces=false,
showtabs=false,
tabsize=2,
captionpos=b,
breaklines=true,
breakatwhitespace=true,
breakautoindent=true,
linewidth=\textwidth
}
Der Pandoc-Befehl zum Umwandeln lt.
pandoc --listings -H listings-setup.tex --toc -V geometry:"left=1cm, top=1cm, right=1cm, bottom=2cm" -V fontsize=12pt test.md -o test2.pdf
Eisvogel - Ein tolles Template für Markdown-to-PDF
Das Template "Eisvogel" eignet sich sehr gut, um aus Markdown-Dokumenten aufwendigere PDF-Dokumente zu erstellen
Das Template ist in einem beliebigen Pfad abzuspeichern und kann dann über den Pandoc-Befehl aufgerufen werden. Damit lässt sich Eisvogel zentral verwalten und für alle Markdown-Dokumente verwendet werden.
Die Funktionen von Eisvogel sind in der Dokumentation auf GitHub beschreiben und werden zu Beginn in das Dokument zwischen --- eingefügt.
---
title: "Titel"
subtitle: "Sub-titel"
author: ['Stefan Strobel']
date: "Release Date: 2023-12-13"
subject: "Stefan Strobel"
keywords: [strobelstefan.de, Markdown, Pandoc, Eisvogel]
lang: "de"
header-left: "\\hspace{1cm}"
header-center: "\\leftmark"
header-right: ""Seite \\thepage""
footer-left: "Release date: 15.10.2023"
footer-center: "Version: 1.0.0"
footer-right: ""
titlepage: true,
titlepage-text-color: "FFFFFF"
titlepage-rule-color: "360049"
titlepage-rule-height: 0
titlepage-background: "`~/Documents/pictures/bild`{=latex}"
logo: "`~/Documents/eisvogel/pictures/logo`{=latex}"
logo-width: 100mm
toc-own-page: true
code-block-font-size: \normalsize
table-use-row-colors: true
---
# Kapitelüberschrift
...
In diesem Beispiel wird die Datei README.md in ein PDF-Dokument umgewandelt.
pandoc README.md --template ~/Documents/mein-tolles-markdown-dokument/eisvogel --listings --number-sections --pdf-engine=lualatex -V mainfont='JetBrainsMono Nerd Font' -V book --top-level-division=chapter --highlight-style kate -o mein-unfassbar-tolles-pdf-dokument.pdf
--template= Das Eisvogel-Template ist im Verzeichnis~/Documents/mein-tolles-markdown-dokument/eisvogelabgespeichert--top-level-division=chapter= Die Kapitel im PDF-Dokument sind die Überschriften, die im Markdown-Dokument mit einem#gekennzeichnet wurden-V book= Kapitel beginnen auf einer neuen Seite-V mainfont='JetBrainsMono Nerd Font'= Es wird die SchriftJetBrainsMono Nerd Fontgenutzt
Oft ist es sinnvoll anstatt einem großen Dokument mehrere kleine Markdown-Dokumente zum Schreiben zu verwenden.
Das Konvertieren mehrerer Markdown-Dokumente in ein finales PDF-Dokument stellt keine Herausforderung für Pandoc dar. Es werden einfach alle md-Dokumente der Reihe nach aufgerufen und in einem PDF-Dokument zusammengefasst.
Die Optionen für Eisvogel sind nur in der ersten md-Datei zu definieren, in diesem Beisiel der README.md.
pandoc README.md dokument-01.md dokument-02.md dokument-03.md dokument-04.md dokument-05.md dokument-06.md dokument-07.md --template ~/Documents/mein-tolles-markdown-dokument/eisvogel --listings --number-sections --pdf-engine=lualatex -V mainfont='JetBrainsMono Nerd Font' -V book --top-level-division=chapter --highlight-style kate -o mein-unfassbar-tolles-pdf-dokument.pdf
Pandoc und Unicode
Es gibt aktuelle keine gute Unterstützung von Unicode, was das Ganze ein wenig kniffeliger, aber nicht ganz unlösbar macht. Es lassen sich mit Pandoc alle auf dem Gerät, also auf dem eigenen Client, dem Server oder der Docker-Umgebung, installierten Fonts verwenden. Dazu muss ist im Befehl die Option -V mainfont='' mitzugeben.
Bei MacOS lassen sich die verfügbaren Fonts einfach über die App "Schriftsammlung" abfragen.
Ein Font, das zumindest eine kleine Anzahl an Emojis unterstütz, sind Nerd Fonts.
Wie geht man vor?
- Schriftzeichen in der "Schriftsammlung" auswählen
- Das Schriftzeichen kopieren und in das Markdown-Dokument einfügen
- Konvertierung mit Pandoc starten
Das Vorgehen führt leider nicht immer zum Erfolg. Viele Zeichen werden im fertigen PDF-Dokument kryptisch dargestellt. Dann ist ein anderes Schriftzeichen auszuwählen und auszuprobieren.
Das ist nicht besonders toll, aber immerhin eine Möglichkeit ein paar Zeichen zu verwenden. Wenn jemand eine bessere Lösung gefunden hat, dann bitte unbedingt
👉 mitteilen❗
Emojis und Icons lassen sich aber auch jederzeit als Bilddatei in das Dokument einbinden. Das geht zwar nicht so schnell und einfach, ist aber immerhin eine Lösung mit vertretbarem Aufwand.
LaTeX-Vorlagen und mathematische Formeln
Auch Markdown beherrscht mathematische Formeln, die aus TeX entliehen sind.
Hilfreiche Tools
Ein Snippet Manager wie MassCode eignet sich sehr gut, um unkompliziert auf eigene, vorgefertigte Codeblöcke zuzugreifen.
Für Visual Studio Code gibt es ein Plugin, damit man direkt auf den Snippet Manager zugreifen kann.
Gib mir gerne einen Kaffee ☕ aus ❗️
Wenn dir meine Beiträge gefallen und geholfen haben, dann kannst du mir gerne einen Kaffee ☕️ ausgeben.
• 
Bitcoin Address: bc1qfuz93hw2fhdvfuxf6mlxlk8zdadvnktppkzqzj
Follow Me❗️
Source
Foto von dlxmedia.hu auf Unsplash