ADMIN
2021
12
2021-12-01T12:00:00
Small Business IT
PRAXIS
058
Dokumentationen
Open-Source-Tipp
Tools
Dokumente layouten mit Markdown
In Form bringen
von Thorsten Scherf
Veröffentlicht in Ausgabe 12/2021 - PRAXIS
Zum Schreiben von technischer Dokumentation können Entwickler und Administratoren zwischen einer Vielzahl an unterschiedlichen Tools auswählen. Der Open-Source-Tipp in diesem Monat zeigt, wie Sie mit Hilfe von Markdown und pandoc Ihre Texte in viele unterschiedliche Formate transformieren und nebenbei auch noch anspruchsvolle Präsentationen erstellen.

Klassischerweise kommen für das Erstellen von Dokumentationen oder Anleitungen Textbearbeitungsprogramme wie beispielsweise Microsoft Word, Apple Pages oder das Open-Source-Tool LibreOffice zum Einsatz. All diese Programme haben gemeinsam, dass unterschiedliche Elemente eines Dokuments miteinander vermischt werden. So besteht eine gute Dokumentation oder Anleitung ja nicht nur aus reinem Text, sondern enthält auch Bilder, Grafiken, Tabellen, Listen und andere Elemente. Dies bedeutet im Umkehrschluss, dass beim Schreiben nicht nur auf den eigentlichen Inhalt des Dokuments zu achten ist, die einzelnen Elemente müssen auch vom Layout her gut aufeinander abgestimmt sein.
Dabei ist es ein wenig verwunderlich, dass dieses What-you-see-is-what-you-get-Prinzip (WYSIWYG) immer noch großen Anklang findet, da sich in anderen Bereichen eine Trennung zwischen dem Inhalt eines Dokuments und dem Layout schon seit langer Zeit durchgesetzt hat – beispielsweise in der Webentwicklung. Hier würde niemand mehr auf die Idee kommen, das Layout einer Webseite zusammen mit dem Inhalt der Seite zu vermischen. Stattdessen kommt für das Layout ein Stylesheet zum Einsatz, das zumeist als CSS-Datei (Cascading Style Sheet) [1] vorliegt. Um ein Layout für die Webseite zu erzeugen, ist somit nur noch das CSS anzupassen, ohne irgendwas am Inhalt der Seite ändern zu müssen.
Textsatzsysteme TeX, LaTeX und Markdown
Wer eine solche logische Trennung zwischen Inhalt und Darstellung auch bei der Bearbeitung von Texten einsetzen möchte, kann beispielsweise auf TeX [2] oder LaTeX [3] zurückgreifen. Hierbei handelt es sich allerdings um komplexe Textsatzsysteme, deren Syntax nicht unbedingt eingängig ist und eine gewisse Einarbeitungszeit voraussetzt. Wobei es sich bei LaTeX strenggenommen eigentlich auch nur um eine Sammlung von Makros handelt, die die Benutzung von TeX vereinfachen sollen.
Klassischerweise kommen für das Erstellen von Dokumentationen oder Anleitungen Textbearbeitungsprogramme wie beispielsweise Microsoft Word, Apple Pages oder das Open-Source-Tool LibreOffice zum Einsatz. All diese Programme haben gemeinsam, dass unterschiedliche Elemente eines Dokuments miteinander vermischt werden. So besteht eine gute Dokumentation oder Anleitung ja nicht nur aus reinem Text, sondern enthält auch Bilder, Grafiken, Tabellen, Listen und andere Elemente. Dies bedeutet im Umkehrschluss, dass beim Schreiben nicht nur auf den eigentlichen Inhalt des Dokuments zu achten ist, die einzelnen Elemente müssen auch vom Layout her gut aufeinander abgestimmt sein.
Dabei ist es ein wenig verwunderlich, dass dieses What-you-see-is-what-you-get-Prinzip (WYSIWYG) immer noch großen Anklang findet, da sich in anderen Bereichen eine Trennung zwischen dem Inhalt eines Dokuments und dem Layout schon seit langer Zeit durchgesetzt hat – beispielsweise in der Webentwicklung. Hier würde niemand mehr auf die Idee kommen, das Layout einer Webseite zusammen mit dem Inhalt der Seite zu vermischen. Stattdessen kommt für das Layout ein Stylesheet zum Einsatz, das zumeist als CSS-Datei (Cascading Style Sheet) [1] vorliegt. Um ein Layout für die Webseite zu erzeugen, ist somit nur noch das CSS anzupassen, ohne irgendwas am Inhalt der Seite ändern zu müssen.
Textsatzsysteme TeX, LaTeX und Markdown
Wer eine solche logische Trennung zwischen Inhalt und Darstellung auch bei der Bearbeitung von Texten einsetzen möchte, kann beispielsweise auf TeX [2] oder LaTeX [3] zurückgreifen. Hierbei handelt es sich allerdings um komplexe Textsatzsysteme, deren Syntax nicht unbedingt eingängig ist und eine gewisse Einarbeitungszeit voraussetzt. Wobei es sich bei LaTeX strenggenommen eigentlich auch nur um eine Sammlung von Makros handelt, die die Benutzung von TeX vereinfachen sollen.
Wesentlich leichter fällt dabei der Umgang mit Markdown [4]. Hierbei handelt es sich um eine einfache Auszeichnungssprache, die jeder sehr schnell erlernen und somit auch einsetzen kann. Ein weiterer Vorteil ist, dass Sie ein Markdown-Dokument in jedem beliebigen Texteditor schreiben können und kein spezielles Programm hierfür benötigen. Für einen leichten Einstieg in die Syntax der Sprache empfiehlt sich ein Blick in den Markdown-Guide [5].
Um aus einem Markdown-Text schließlich ein fertiges Dokument zu erzeugen, können Sie beispielsweise das Tool pandoc [6] einsetzen. Die Software besteht aus einer in Haskell geschriebenen Bibliothek und einem Kommandozeilen-Tool. Hiermit wandeln Sie eine Vielzahl von unterschiedlichen Textformaten in andere Formate um – also beispielsweise Markdown in HTML, EPUB oder PDF. Auch Formate wie DOCX oder PPTX (Microsoft Word oder PowerPoint) unterstützt das Werkzeug.
Möglich wird dies durch den Einsatz eines sogenannten Readers und Writers, die für jedes Format vorhanden sind. Ein Reader wandelt den Text in einen Abstract Syntax Tree (AST) um, bevor ein Writer die Elemente aus dem AST dann in das passende Zielformat überführt. Teilweise ist hierfür ein Zwischenschritt notwendig. Um beispielsweise Markdown in PDF zu wandeln, wird zuerst eine LaTeX-Version erzeugt, bevor diese mithilfe von pdflatex in das eigentliche PDF-Format umgewandelt wird.
Installation von pandoc unter Linux, macOS und Windows
Die pandoc-Software steht in den Repositories nahezu sämtlicher Linux-Distributionen zur Installation zur Verfügung. Unter [6] finden Sie auf der Pandoc-Projektseite ebenfalls Installationsarchive sowohl für Linux als auch Windows und macOS. Für Letzteres können Sie die Software allerdings auch mithilfe des Paketmanagers brew installieren. Wichtig zu erwähnen ist an dieser Stelle noch, dass Sie eine TeX-Umgebung benötigen, wenn Sie Texte in das PDF-Format transformieren möchten. Für macOS gelingt dies ganz einfach wieder mittels brew und der Installation des Pakets basictex. Für Windows steht unter [7] MiKTeX als TeX-Distribution zur Verfügung.
Webseiten in Markdown erzeugen
Nachfolgend zeigen wir Ihnen nun einige Beispiele für den praktischen Einsatz von pandoc. Zuerst soll es darum gehen, einen Markdown-Text in (X)HTML zu transformieren, sodass Sie diesen dann auf einer Webseite veröffentlichen können. Hierfür kommt der folgende Befehl zum Einsatz:
pandoc -M title="pandoc" -s foo.md -o foo.html
Mit der Option "-M" können Sie beliebige Metadaten für das Ausgabeformat definieren, in diesem Fall den Titel der Webseite. Die Option "-s" sorgt dafür, dass als Ausgabe lediglich eine einzelne Datei geschrieben wird. Somit sind die Stylesheet-Informationen ebenfalls in der HTML-Datei im Header enthalten. Ein einfacher Markdown-Text sieht also wie folgt aus:
Hallo IT-Administrator
Mit pandoc können Sie wie erwähnt Texte in eine Vielzahl von unterschiedlichen Formaten exportieren.
Zu den unterstützten Formaten zählen beispielsweise HTML, PDF, EPUB, DOCX oder PPTX.
Ein Blick in die **pandoc**-Hilfeseite mittels 'man pandoc' zeigt Ihnen sämtliche unterstützte Formate an.
Ganz ähnlich verhält es sich nun, wenn Sie den Markdown-Text in ein PDF umwandeln möchten. Der passende Befehl hierfür lautet
pandoc -s foo.md -o foo.pdf
Die jeweiligen Ein- und Ausgabeformate versucht pandoc dabei anhand der Dateiendungen zu erkennen. Sie können die Formate aber auch mittels "-f/--from" und "-t/--to" explizit angeben:
pandoc -f markdown -t pdf foo.md -o foo.pdf
Präsentationen in Markdown erstellen
Besonders interessant ist auch die Möglichkeit, dass Sie mit pandoc anspruchsvolle Präsentationen in Markdown erzeugen können. Hierzu existieren mehrere Varianten. So können Sie beispielsweise einen HTML-basierten Foliensatz auf Basis eines JavaScript-Web-Frameworks oder einen PDF-Satz mithilfe der LaTeX-Klasse beamer [8] erzeugen. Als Web-Frameworks unterstützt pandoc S5 [9], DZSlides [10], Slidy [11], Slideous [12] oder auch reveal.js [13].
Um eine neue Präsentation zu erzeugen, rufen Sie pandoc in gewohnter Weise auf. Für einen PDF-Foliensatz lautet das Kommando:
pandoc -t beamer slides.md -o slides.pdf
Möchten Sie stattdessen lieber einen HTML-Foliensatz auf Basis eines der zuvor genannten JavaScript-Web-Frameworks erzeugen, ändert sich der Befehl nur marginal:
pandoc -t revealjs slides.md -o slides-reveal.html
Im letzten Beispiel ist darauf zu achten, dass sich das JavaScript-Web-Framework im gleichen Verzeichnis befindet wie auch die Markdown-Datei. Alternativ dazu können Sie auch mit der Option "-V revealjs-url" einen anderen Pfad zu dem Framework bestimmen.
Natürlich existieren eine Vielzahl von weiteren Optionen, mit denen Sie beispielsweise verschiedene Themes einbinden können. Die Dokumentationen zu den jeweiligen Frameworks enthalten hierfür alle notwendigen Informationen.
Fazit
Um ansprechende Textdokumentationen zu erstellen, müssen Sie nicht unbedingt zu Klassikern wie Word oder LibreOffice greifen. Mit der Kombination aus Markdown und pandoc können Sie Texte in viele unterschiedliche Formate transformieren. Auch PDF-Foliensätze lassen sich erzeugen, solange Sie eine LaTeX-Distribution zusammen mit der Klasse beamer auf Ihrem System installiert haben. Für HTML-Präsentationen können Sie auf unterschiedliche JavaScript-Web-Frameworks zurückgreifen, um eine Slideshow dann innerhalb eines beliebigen Browsers zu starten.
(dr)
Link-Codes
[1] Cascading Style Sheets (CSS):
https://www.w3.org/Style/CSS/[2] TeX-Textsatzsystem:
https://www.tug.org/