Ein Tool für alle Ausgabeformate: Pandoc im Praxiseinsatz
Warum sich Markdown als zentrale Dokumentationsquelle lohnt, wenn Pandoc am Ende automatisiert die passenden Zielformate erzeugt.
Ein einziges Markdown-Dokument, das am Ende als DokuWiki-Seite, als PDF-Report mit LaTeX-Satzspiegel, als Word-Datei oder als PowerPoint-Foliensatz herauskommt, klingt nach unnötigem Aufwand. Ist es aber nicht, wenn man Pandoc dazwischenschaltet. Das Tool übernimmt genau diese Übersetzungsarbeit und hat sich in meinem Alltag zwischen Dokumentation, SIEM-Reporting und gelegentlichem Office-Kram als fester Bestandteil etabliert.
Ein Übersetzer für praktisch jedes Dokumentformat
Pandoc funktioniert nach einem simplen Prinzip. Ein Reader liest ein Eingabeformat ein und baut daraus eine interne, abstrakte Darstellung des Dokuments, den sogenannten AST. Ein Writer nimmt diesen AST und rendert ihn in ein Zielformat. Pandoc kann zwischen zahlreichen Markup- und Textverarbeitungsformaten konvertieren, darunter verschiedene Markdown-Varianten, HTML, LaTeX und Word docx. Darüber hinaus deckt das Tool Wiki-Markup-Formate wie MediaWiki, DokuWiki, TikiWiki, TWiki, Vimwiki, XWiki, ZimWiki, Jira Wiki und Creole ab, ebenso Foliensatz-Formate wie LaTeX Beamer, PowerPoint, Slidy, reveal.js, Slideous, S5 und DZSlides sowie Datenformate wie CSV- und TSV-Tabellen und Excel-Tabellen. Für PDF gibt es keinen eigenen internen Writer, stattdessen wird über externe Programme wie pdflatex, lualatex, xelatex, latexmk, tectonic, wkhtmltopdf, weasyprint, prince, pagedjs-cli, context oder pdfroff gerendert. Wer PDF-Ausgabe braucht, benötigt also zusätzlich eine funktionierende LaTeX-Installation oder eines der anderen genannten Programme, Pandoc allein reicht dafür nicht.
Dass diese Bandbreite an Formaten überhaupt möglich ist, liegt am modularen Aufbau: Ein neues Format hinzuzufügen bedeutet im Kern nur, einen weiteren Reader oder Writer zu schreiben. Für den eigenen Workflow bedeutet das vor allem eines: Eine einzige, gepflegte Markdown-Quelle reicht, der Rest ist eine Frage des passenden Zielformats beim Aufruf.
Installation und die Grundbefehle
Auf Debian- und Ubuntu-Systemen landet Pandoc klassisch über die Paketverwaltung im System:
# M. Meister
sudo apt update && sudo apt install pandoc
Der Grundaufbau eines Aufrufs ist immer derselbe: Eingabeformat mit -f oder --from, Zielformat mit -t oder --to, Zieldatei mit -o oder --output. Ohne Angabe von -f geht Pandoc von Markdown als Quelle aus und schreibt standardmäßig nach HTML. Ein Beispielaufruf, der aus einer Markdown-Datei eine eigenständige HTML-Seite samt Grundgerüst erzeugt:
# M. Meister
pandoc dokument.md --standalone --metadata title="Beispieldokument" -o dokument.html
Die --standalone-Option (kurz -s) sorgt dafür, dass Pandoc den Inhalt nicht nur als reinen Fragment-Output ausgibt, sondern in ein vollständiges Dokumentgerüst mit Kopfbereich einbettet. Titel und weitere Metadaten wie Autor lassen sich statt über die Kommandozeile auch direkt im Markdown-Dokument als YAML-Frontmatter am Dateianfang hinterlegen, etwa mit title: und author: in einem durch drei Bindestriche eingerahmten Block. Das erspart, die Angaben bei jedem Aufruf neu mitzugeben, und macht das Quelldokument selbst zur einzigen Wahrheit über seine eigenen Metadaten.
Markdown-Dokumentation landet automatisiert im DokuWiki
Meine technische Dokumentation schreibe ich grundsätzlich in Markdown, das ist für mich die bequemste Form, Inhalte zu pflegen und zu versionieren. Außerdem erfolgt die Kommunikation mit meiner KI ebenfalls in Markdown, weswegen es bei mir zu einem Standard geworden ist.
Michael Meister
Der eigentliche Anzeigeort meiner Dokumentationen ist aber ein DokuWiki, und genau diese Lücke schließt Pandoc automatisiert. Aus dem gleichen Quelldokument, das etwa auch als Referenz im Git-Repository liegt, entsteht per Konvertierungslauf die passende DokuWiki-Syntax:
# M. Meister
pandoc dokumentation.md --from markdown --to dokuwiki --output dokuwiki-seite.txt
Der Vorteil dabei ist weniger die Konvertierung selbst als der Wegfall der doppelten Pflege. Änderungen an der Markdown-Quelle wandern über ein Skript oder einen einfachen Cronjob automatisiert ins Wiki, ohne dass Inhalte manuell zwischen zwei Systemen synchronisiert werden müssen. Bei komplexeren Listenstrukturen lohnt sich ein Blick ins generierte Ergebnis, der DokuWiki-Writer ist nicht in jedem Fall perfekt, gerade bei verschachtelten oder gemischten Listen kann zusätzliches HTML im Output landen, das DokuWiki nicht sauber rendert. Für normale Dokumentationsstruktur mit Überschriften, Absätzen und einfachen Listen funktioniert die automatisierte Überführung aber zuverlässig.
SIEM-Reports mit LaTeX-Politur fürs Management
Die Incident-Reports aus meinem Wazuh-SIEM entstehen ebenfalls zunächst als Markdown, schließlich sollen sie sich schnell und ohne Formatierungsaufwand schreiben lassen. Für die Weitergabe ans Management reicht ein einfaches Markdown-Dokument aber nicht, dort zählt der optische Eindruck. Über den Umweg via LaTeX wird aus dem gleichen Report ein PDF mit sauberem Satzspiegel, konsistenter Typografie und professionellem Erscheinungsbild:
# M. Meister
pandoc incident-report.md --from markdown --to pdf --pdf-engine=xelatex -o incident-report.pdf
Der Inhalt bleibt identisch, nur die Darstellung ändert sich, und genau das macht beim Management den Unterschied. Ein technisch einwandfreier Report in reinem Klartext wirkt schlicht weniger überzeugend als das exakt gleiche Dokument mit ordentlichem Layout.
Wer öfter über Custom-Templates arbeitet, kann das Layout zusätzlich über eigene LaTeX-Templates weiter anpassen, für den Alltag reicht aber meist schon die Standardvorlage.
Word-Dokumente und PowerPoint-Folien ganz nebenbei
Gelegentlich verlangt der Alltag trotz aller Sympathie für offene Formate nach klassischen Office-Dateien, sei es, weil ein Kunde ein Word-Dokument erwartet oder eine Präsentation als PowerPoint-Datei verschickt werden soll. Auch hier bleibt die Markdown-Quelle unverändert, nur das Zielformat ändert sich:
# M. Meister
pandoc bericht.md -o bericht.docx
pandoc folien.md -o praesentation.pptx
Bei der PowerPoint-Erzeugung orientiert sich Pandoc an der Gliederungsstruktur des Markdown-Dokuments, Überschriften der obersten Ebene markieren jeweils eine neue Folie. Für einfache, textlastige Foliensätze reicht das vollkommen aus, wer aufwendigeres Layout mit individuellen Grafikpositionen braucht, wird trotzdem noch händisch nacharbeiten müssen. Für den schnellen internen Foliensatz oder den klassischen Ergebnisbericht an einen Kunden erspart der automatisierte Weg aber zuverlässig die doppelte Pflege in zwei unterschiedlichen Tools.
Fazit
Eine einzige gepflegte Markdown-Quelle reicht aus, um über Pandoc automatisiert DokuWiki-Seiten, PDF-Reports mit LaTeX-Satz, Word-Dokumente und PowerPoint-Folien zu erzeugen, ohne Inhalte mehrfach zu pflegen. Der eigentliche Gewinn liegt weniger in der einzelnen Konvertierung als in der Möglichkeit, unterschiedliche Zielgruppen und Systeme aus derselben Quelle zu bedienen. Wer viel in Markdown dokumentiert und regelmäßig zwischen Wiki, Report und Office-Formaten wechseln muss, spart mit diesem Ansatz spürbar Zeit gegenüber manueller Doppelpflege.