Pandoc ist ein vielseitiges Werkzeug für Linux, das die Konvertierung zwischen über 40 Dateiformaten ermöglicht. Es kann auch als Grundlage für ein simples „Docs-as-Code“-System dienen. Hierbei schreiben Sie in Markdown, speichern Ihre Arbeit in Git und publizieren sie dann in einem der vielen unterstützten Formate.
Dokumentenkonvertierung und „Docs-as-Code“-Ansatz
Mit Pandoc ist die Umwandlung von einem der zahlreichen unterstützten Dateiformate in ein anderes ein einfacher Prozess. Dies macht Pandoc zu einem äußerst nützlichen Werkzeug.
Die wahre Stärke von Pandoc entfaltet sich jedoch, wenn es als Kern eines „Docs-as-Code“-Systems verwendet wird. Der „Docs-as-Code“-Ansatz überträgt Techniken und Prinzipien der Softwareentwicklung auf das Erstellen von Dokumentationen, besonders im Kontext von Softwareprojekten. Diese Methode ist aber auf jede Art von Dokumentationserstellung anwendbar.
Softwareentwickler nutzen üblicherweise Editoren oder integrierte Entwicklungsumgebungen (IDEs) zum Schreiben ihres Programmcodes. Der eingegebene Code wird in Textdateien abgelegt, die den Quellcode des Programms enthalten.
Zur Nachverfolgung von Änderungen am Quellcode während der Entwicklung verwenden sie ein Versionskontrollsystem (VCS). Git ist hierbei das beliebteste. Dadurch erhält der Entwickler eine vollständige Historie aller Versionen des Quellcodes und kann jederzeit auf frühere Versionen zugreifen. Git speichert Dateien in einem Repository, wobei sowohl lokale als auch zentrale, in der Cloud gehostete Repositories existieren.
Wenn eine funktionierende Version des Programms fertig ist, wird der Quellcode mit einem Compiler in eine binäre, ausführbare Datei umgewandelt.
Indem Sie Ihre Dokumente in einer einfachen textbasierten Auszeichnungssprache verfassen, können Sie ein VCS für die Versionskontrolle Ihrer Texte einsetzen. Für die Verteilung oder Veröffentlichung können Sie mit Pandoc verschiedene Formate Ihrer Dokumentation erzeugen, darunter Web-basierte Formate (HTML), Textverarbeitungsformate (wie LibreOffice, Microsoft Word, TeX), das Portable Document Format (PDF), E-Book Formate (ePub) und viele mehr.
All dies ist mit einem Satz versionierter, schlanker Textdateien möglich.
Installation von Pandoc
Unter Ubuntu installieren Sie Pandoc mit folgendem Befehl:
sudo apt-get install pandoc
Bei Fedora verwenden Sie:
sudo dnf install pandoc
Auf Manjaro geben Sie ein:
sudo pacman -Syu pandoc
Mit der Option `–version` überprüfen Sie die installierte Version:
pandoc --version
Pandoc ohne Dateien verwenden
Wenn Sie Pandoc ohne Befehlszeilenoptionen aufrufen, akzeptiert es auch Eingaben über die Tastatur. Beenden Sie die Eingabe mit Strg+D. Pandoc erwartet Markdown-Eingabe und erzeugt eine HTML-Ausgabe.
Ein Beispiel:
pandoc
Nach Eingabe von ein paar Zeilen Markdown drücken wir Strg+D.
Daraufhin generiert Pandoc die entsprechende HTML-Ausgabe.
Für eine sinnvolle Nutzung von Pandoc ist das Arbeiten mit Dateien jedoch unerlässlich.
Grundlagen von Markdown
Markdown ist eine einfache Auszeichnungssprache, bei der bestimmte Zeichen eine besondere Bedeutung haben. Sie können Markdown-Dateien mit jedem Texteditor erstellen.
Markdown ist gut lesbar, da keine störenden Tags den Text ablenken. Die Formatierung in Markdown-Dokumenten ähnelt dem späteren Aussehen. Hier sind einige Grundlagen:
Kursiven Text erhalten Sie durch Einschließen in Sternchen: *So wird Text kursiv*. Für fetten Text verwenden Sie zwei Sternchen: **So wird Text fett**. Überschriften werden durch das Nummernzeichen (#) gekennzeichnet. Ein Leerzeichen trennt das Nummernzeichen vom Text. Verwenden Sie ein # für die Hauptüberschrift, zwei ## für eine Unterüberschrift und so weiter. Für eine Liste mit Aufzählungszeichen beginnen Sie jede Zeile mit einem Sternchen und einem Leerzeichen. Für eine nummerierte Liste beginnen Sie jede Zeile mit einer Zahl, gefolgt von einem Punkt und einem Leerzeichen. Ein Hyperlink wird erstellt, indem der Name der Website in eckige Klammern ([]) und die URL in runde Klammern [()] gesetzt wird: [Link zu einer Seite](https://www.beispiel.de/). Ein Bild fügen Sie ein, indem Sie ein Ausrufezeichen vor eckigen Klammern setzten (![]). Geben Sie einen alternativen Text in die eckigen Klammern ein und den Pfad zum Bild in runde Klammern [()]: .
Weitere Beispiele dazu folgen im nächsten Abschnitt.
Dateien konvertieren
Dateikonvertierungen sind einfach. Pandoc erkennt das Dateiformat meist automatisch anhand der Dateinamen. Hier erzeugen wir aus einer Markdown-Datei eine HTML-Datei. Die Option `-o` (Output) gibt den Namen der Ausgabedatei an:
pandoc -o sample.html sample.md
Unsere Markdown-Datei `sample.md` enthält den kurzen Markdown-Abschnitt, der unten abgebildet ist.
Die Datei `sample.html` wird erstellt. Ein Doppelklick öffnet sie im Standardbrowser.
Lassen Sie uns nun ein Open Document Format Textdokument generieren, das wir in LibreOffice Writer öffnen können:
pandoc -o sample.odt sample.md
Die ODT-Datei hat den gleichen Inhalt wie die HTML-Datei.
Der für das Bild angegebene alternative Text wird auch verwendet, um eine Bildunterschrift zu erzeugen.
Dateiformate spezifizieren
Die Optionen `-f` (from) und `-t` (to) geben die Dateiformate für die Konvertierung an. Dies ist nützlich, wenn Dateiformate die gleiche Dateierweiterung verwenden, wie TeX und LaTeX, die beide die Erweiterung „.tex“ nutzen.
Die Option `-s` (Standalone) sorgt dafür, dass Pandoc alle für ein vollständiges, in sich geschlossenes LaTeX-Dokument benötigten Präambeln erzeugt. Ohne `-s` wäre die Ausgabe zwar weiterhin valides LaTeX, das in ein anderes LaTeX-Dokument eingebunden werden könnte, aber nicht als eigenständiges Dokument.
Wir geben ein:
pandoc -f markdown -t latex -s -o sample.tex sample.md
Die generierte LaTeX-Datei `sample.tex` zeigt den generierten LaTeX-Code. Mit einem LaTeX-Editor können Sie die TEX-Datei öffnen, um eine Vorschau der Interpretation der LaTeX-Befehle anzuzeigen. Die Darstellung im Bild ist etwas gequetscht, die tatsächliche Ausgabe ist in Ordnung.
Wir haben einen LaTeX-Editor namens Texmaker benutzt. Zur Installation unter Ubuntu verwenden Sie:
sudo apt-get install texmaker
Unter Fedora lautet der Befehl:
sudo dnf install texmaker
Und unter Manjaro:
sudo pacman -Syu texmaker
Dateikonvertierung mit Vorlagen
Die Flexibilität von Pandoc wird hier deutlich. Schreiben Sie einmal und veröffentlichen Sie in fast jedem Format. Allerdings sehen die Dokumente standardmäßig etwas einfach aus.
Mit Vorlagen bestimmen Sie, welche Stile Pandoc bei der Dokumentenerstellung anwendet. Sie können Pandoc zum Beispiel anweisen, Stile aus einer Cascading Style Sheets (CSS)-Datei mithilfe der Option `–css` zu verwenden.
Wir haben eine kleine CSS-Datei mit folgendem Inhalt erstellt. Sie ändert den Abstand über und unter einer Überschrift, die Textfarbe auf Weiß und die Hintergrundfarbe auf einen Blauton:
h1 {
color: #FFFFFF;
background-color: #3C33FF;
margin-top: 0px;
margin-bottom: 1px;
}
Der vollständige Befehl lautet:
pandoc -o sample.html -s --css sample.css sample.md
Pandoc wendet den Stil aus der CSS-Datei auf die Überschrift der Ebene 1 an.
Eine weitere Feinabstimmungsmöglichkeit für HTML-Dateien ist das Einbetten von HTML-Markup in die Markdown-Datei. Dieser wird dann unverändert in die generierte HTML-Datei übernommen.
Diese Technik sollte jedoch nur für HTML-Ausgaben genutzt werden, da Pandoc bei anderen Dateiformaten das HTML-Markup ignoriert und es als Text in die Datei schreibt.
Für ODT-Dateien können Sie ebenfalls festlegen, welche Stile verwendet werden. Öffnen Sie ein leeres LibreOffice Writer-Dokument und passen Sie Überschriften- und Schriftstile nach Ihren Wünschen an. Wir haben auch eine Kopf- und Fußzeile hinzugefügt. Speichern Sie das Dokument als `odt-template.odt`.
Diese Vorlage können wir nun mit der Option `–reference-doc` nutzen:
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
Vergleichen Sie dieses mit dem vorherigen ODT-Beispiel. Dieses Dokument verwendet eine andere Schriftart, hat farbige Überschriften und enthält Kopf- und Fußzeilen. Es wurde jedoch aus der gleichen Markdown-Datei `sample.md` generiert.
Vorlagen können genutzt werden, um verschiedene Phasen der Dokumenterstellung zu kennzeichnen. So könnten Sie zum Beispiel Vorlagen mit dem Wasserzeichen „Entwurf“ oder „Zur Überprüfung“ erstellen. Für ein fertiges Dokument wird eine Vorlage ohne Wasserzeichen verwendet.
PDFs erstellen
Pandoc verwendet standardmäßig die LaTeX-PDF-Engine für die PDF-Erstellung. Am einfachsten stellen Sie die notwendigen LaTeX-Abhängigkeiten sicher, indem Sie einen LaTeX-Editor wie Texmaker installieren.
Das ist allerdings eine recht umfangreiche Installation. Wenn Sie wenig Speicherplatz haben oder wissen, dass Sie TeX/LaTeX nie verwenden werden, könnten Sie stattdessen eine ODT-Datei generieren und diese dann in LibreOffice Writer als PDF speichern.
„Docs-as-Code“
Die Verwendung von Markdown als Schreibsprache bietet mehrere Vorteile:
- Das Arbeiten in Textdateien ist schnell: Sie laden schneller als Textverarbeitungsdateien und die Navigation innerhalb des Dokuments ist auch schneller. Viele Editoren wie gedit, Vim und Emacs bieten Syntaxhervorhebung für Markdown.
- Sie haben eine Zeitleiste aller Versionen Ihrer Dokumente: Wenn Sie Ihre Dokumentation in einem VCS wie Git speichern, können Sie Änderungen zwischen zwei beliebigen Versionen derselben Datei leicht verfolgen. Dies funktioniert nur mit Textdateien.
- Ein VCS zeichnet auf, wer wann Änderungen vorgenommen hat: Dies ist besonders nützlich, wenn Sie mit anderen zusammenarbeiten. Es bietet auch eine zentrale Ablage für die Dokumente. Viele Cloud-basierte Git-Dienste wie GitHub, GitLab und Bitbucket bieten kostenlose Tarife an.
- Sie können Ihre Dokumente in verschiedenen Formaten erzeugen: Mit ein paar Shell-Skripten können Sie Stile aus CSS-Dateien und Referenzdokumenten nutzen. Wenn Sie Ihre Dokumente in einem VCS-Repository speichern, das mit Continuous Integration/Continuous Deployment (CI/CD)-Plattformen verknüpft ist, können die Dokumente automatisch mit der Software generiert werden.
Abschließende Gedanken
Pandoc bietet viele weitere Optionen und Funktionen, die wir hier nicht besprochen haben. Die Konvertierungsprozesse für die meisten Dateitypen können optimiert werden. Mehr erfahren Sie auf der offiziellen und ausführlichen Pandoc-Webseite.