Markdown mit Pandoc konvertieren

Pandoc ist ein ziemlich cooler ich konvertiere von allem in alles Konverter. Da er sich sehr schön in die Struktur von SynWrite integrieren lässt, habe ich mir Pandoc im Hinblick auf Markdown in HTML-Konvertierung etwas genauer angesehen.

Vorstellung

Pandoc ist ein universeller Dokument-Konverter. Die Besonderheit: Es kann kreuz und quer konvertiert werden. Auf diese Weise ist es möglich, die verschiedensten Dokument-Formate zusammenzuführen. Diese — durchaus wesentliche — Funktionalität von Pandoc wird hier nicht weiter behandelt. Es geht vielmehr um die Möglichkeiten, die der Konverter für bestehende MarkDown-Dokumente bietet.

Pandoc wird für Windows, Mac und Linux angeboten und ist ein Kommandozeilen-Programm. Die Befehle und Funktionalitäten sind in allen Betriebssystemen (soweit mir bekannt) identisch, daher nehme ich darauf im weiteren Verlauf keine Rücksicht. Dieses Dokument ist auf einem Windows 7x64 System entstanden und die beschriebenen Dinge wurden dort ausprobiert. Daher lassen sich entsprechende Einflusse wahrscheinlich kaum vermeiden und ich will auch gar nicht so tun, als sei das beabsichtigt.

Installation

Für Windows gibt es einen Pandoc-Installer, der wunderbar funktioniert. Wird er einfach so gestartet, werden alle Daten in ein Benutzerverzeichnis installiert. Das muss nicht, kann aber unerwünscht sein. Für eine allgemeine Installation im Programmverzeichnis muss das Installationsprogramm vorzugsweise aus der Kommandozeile (Start → im Suchfeld CMDeingeben und mit ENTER abschließen) mit Parametern gestartet werden:

msiexec /i pandoc-x.xx.msi ALLUSERS=1

Dann wird Pandoc ins Programmverzeichnis installiert. Alternativ kann Pandoc auch in ein beliebiges Verzeichnis installiert werden, also z.B. auch auf einen USB-Stick, damit man es immer in der Tasche hat:

msiexec /i pandoc-x.xx.x.msi ALLUSERS=1 APPLICATIONFOLDER="C:\Pandoc"

Allerdings klappt es dann noch nicht so wirklich, denn je nach gewünschtem Ausgabeformat fehlen Pfade für die Programme (z.B. MikTeX für PDF), damit die Konvertierung funktioniert. Diverse Formate werden aus dem Stand von Pandoc transformiert. Für wiederkehrende Aufgaben empfehlen sich Batch-Dateien, die ggf. die erforderlichen Pfade kennen oder einstellen.

Pandoc installiert sich — wenn die Standards belassen werden — in das Benutzerverzeichnis. Ist das empfohlene MiKTeX ebenfalls mit den Standardeinstellungen installiert, kann der Pfad in einer Batch-Datei so eingerichtet werden:

SET PATH=C:\Users\Norbert\AppData\Local\Pandoc\;C:\Program Files ⟨x86⟩\MiKTeX 2.9\miktex\bin<br/>```

Hier für x32-Windows, gibt es auch für x64, dann entfällt das „(x86)“. Wobei die Pfade abhängig von der verwendeten Windows-Version abweichen können. Dann muss ggf. mit der Suche das richtige Verzeichnis ermittelt werden. Einfach nach pandoc.exe bzw. pdflatex.exe suchen und die Pfade zu diesen Dateien in den SET-Befehl eintragen.

Alternativ kann natürlich der Systempfad entsprechend erweitert werden, damit das einfach so funktioniert. Die hier beschriebene Methode gilt jeweils für die Lebensdauer des Kommandozeilen-Fensters.

Die Syntax

Die größte Hürde ist womöglich die Tatsache, dass es für Pandoc keine Klicki-Bunti-Oberfläche gibt. Je nach Sichtweise ist das jedoch eher ein Vorteil. Denn manches, dass in Fenstern mühevoll zusammengeklickt werden muss, ist in der Kommandozeile fix zusammengetippt oder aus dem Zeilenpuffer für erneutes Verwenden geholt. Für den regelmäßigen Gebrauch lässt sich eine Batch-Datei chreiben, die aus anderen Programmen heraus bequem aufgerufen werden kann.

Die grundlegende Arbeitsweise ist immer gleich:

pandoc [Optionen][Ausgabedatei][Eingabedatei⟨en⟩]

Typischerweise soll die Ausgabe in eine Datei erfolgen. Die einfachste Variante für die Umwandlung einer Markdown-Datei in eine HTML-Datei sieht so aus:

pandoc -o ausgabe.html eingabe.md

Die Ausgabedatei steht an erster Stelle, weil es immer nur ein Ergebnis geben kann, Pandoc aber mehrere Dateien, die mit einem Leerzeichen getrennt in der Befehlszeile stehen können, zusammenfügt. Technisch betrachtet werden die Eingabedateien zuerst zusammengefasst und dann bearbeitet. Das ist deshalb ein wichtiges Detail, weil so Querverweise, etc. innerhalb des am Ende entstehenden Dokuments möglich sind, oder Inhaltsverzeichnisse ordentlich durchnummeriert sind.

Damit ein Format verbindlich in ein anderes überführt wird, lässt sich das entsprechend angeben. Es kann das Leseformat (-f → f rom) und das Schreibformat (-t → t o) angegeben werden. Eine Konvertierung von Markdown in HTML wird so beschrieben:

pandoc -f markdown -t html Eingabedatei.md

Allerdings ist das im Grunde ein akademisches Detail, denn Pandoc erkennt an den Dateierweiterungen das Eingabeformat. Da das jedoch nicht zwingend passen muss, ist der Schalter (-f) eventuell nützlich.

Zeichencodierung

Die Ein- und Ausgabedateien werden standardmäßig im UTF-8 Format erwartet bzw. erzeugt. Das muss bei der Erstellung der Markdown-Datei(en) entsprechend berücksichtigt werden. Im Browser kann das Ergebnis — wenn eine HTML-Datei erzeugt wird — im ersten Moment enttäuschen, denn Browser sind häufig auf andere Code-Tabellen eingestellt, was sich in kruden Darstellungen deutscher Umlaute niederschlägt. Hierfür muss entweder die Voreinstellung des Browsers angepasst werden, oder es wird eine passende Vorlage für die Ausgabe verwendet:

pandoc -o --template=Vorlagendatei Ausgabe.html Eingabe.md

Das doppelte -- erzwingt die Erzeugung einer alleinstehenden (-s → Standalone) Datei (s. HTML-Erzeugung ).

Vorlagen

Vorlagen sucht Pandoc grundsätzlich im Ordner templates, der sich im Benutzerverzeichnis befinden muss. Eigene Vorlagen — speziell bei der portablen Nutzung — können mit Pfadangabe verwendet werden. Mit dem Vorlagenverzeichnis können die Standards von Pandoc überschrieben werden. Wenn sich dort für das Zielformat eine Vorlage mit dem Namen default.html (für HTML) befindet, wird diese Datei als Vorgabe verwendet. Dort müssen allerdings mit Platzhaltern die Positionen für die Inhalte notiert sein. Als Ausgangspunkt für Anpassungen kann die von Pandoc verwendete Standarddatei mit

pandoc -D FORMAT > default.FORMAT

Die so erzeugte Datei ist mit etwas Muse gelesen durchaus selbsterklärend. Mit den gewünschten Anpassungen ins templates-Verzeichnis verschoben, wird sie ohne weitere Einstellungen immer für das entsprechende Zielformat verwendet.

HTML-Erzeugung

Pandoc bietet einige Optionen für das erzeugte Dokument. Die (für meinen Geschmack) wichtigsten habe ich nachfolgend zusammengestellt:

Batch-Befehl	Funktionalität
`-c`	Style-Sheet, das verknüpft werden soll. Dieser Befehl kann mehrfach verwendet werden, wenn mehrere Style-Sheets integriert werden sollen.
`-t HTML5`	Ausgabeformat steuern, hier: HTML5 erzeugen
`-s`	Standalone, erzeugt eine Datei mit allen Inhalten. Bilder und Style-Sheets werden als eingebettete Dateien in das Dokument eingefügt. Eine HTML-Datei wird so zwar teilweise signifikant größer, ist jedoch portabel, weil alles drin ist.

Eine vollständige Liste der Optionen ist in der Benutzeranleitung auf Englisch verfügbar.

Pandoc-Markdown

Pandoc bietet über das Basis-Markdown von Jon Gruber hinaus weiterführende Möglichkeiten. Diese werden — wahrscheinlich — von diversen anderen Markdown-Editoren immer nur in Untermengen verstanden. Sollen Markdown-Dateien in einer Gruppe getauscht werden, sollte deshalb vorher der Notationsrahmen genau festgelegt werden. Pandoc unterstützt deshalb mehr Möglichkeiten, weil es nicht nur um den Export von HTML-Dokumenten geht. Wie bereits eingangs erwähnt, kann Pandoc erheblich mehr. Das mehr muss jedoch teilweise erst aktiviert werden, Hinweise dazu an entsprechender Stelle.

Formate

Hinter alle Auszeichnungen (Überschriften, Links, etc.) im Markdown kann in geschweiften Klammern die Formatierung des Abschnitts beeinflusst werden. In HTML gesprochen kann der Inhalt des ersten Tags bestimmt werden:

# Überschrift {#ID .klasse1 .klasse2 key=wert }

wird zu

<h1 id="ID" class="klasse1 klasse2" key=wert> … </h1>

Das entspricht den Regeln von Markdown-Extra.

Pandoc erzeugt implizit Referenzen zu Überschriften oder Abschnitten (HTML5), die vereinfacht genutzt werden können.

Auf eine Überschrift kann allein durch die Überschrift in rechteckigen Klammern referenziert werden (optional gefolgt von leeren, rechteckigen Klammern)
Ein Text kann auf eine Überschrift verweisen, indem in der Referenz der Überschrift-Titel steht

Bei mehrdeutigen Links wird der erste im Text genommen. Wenn eigene IDs vergeben werden, werden diese ebenfalls verwendet. Dieses Verfahren hat ggf. den Charme, dass auch andere Übersetzungswerkzeuge damit klar kommen.

Code-Blöcke können mit einer {…} Anmerkung hinter den einleitenden ~optional mit Nummerierung oder einer Farbauszeichnung versehen werden.

Mit der Kopfzeile ~ {.html .numberLines startFrom="100"} wird dieser Codeblock erzeugt:

100 101 102 103

104

<html>
<body>
<p>Die HTML-Tags werden farbig hervorgehoben.</p>
</body>
</html>

Listen

Pandoc berücksichtigt den Startwert einer Liste, das Trennzeichen, und beherrscht „römische“ und Buchstabennummerierung.

Aus

5. Punkt 5
1. Punkt 6
1. Punkt 7
    ⟨i⟩ römisch
    ⟨i⟩ weiter römisch
    ⟨i⟩ noch mehr römisch
        c⟩ Buchstaben ebenfalls,
        c⟩ die dann hochbuchstabiert
        c⟩ werden

wird

Punkt 5
Punkt 6
Punkt 7

römisch
weiter römisch
noch mehr römisch

Buchstaben ebenfalls,
die dann hochbuchstabiert
werden

Extra-Formate

Formatanweisung	Funktionalität
`_x`	x wird tiefgestellt: _x (subscript)
`^x`	x wird hochgestellt: ^x (superscript)
`x`	x wird durchgestrichen: x
`...` ⁽¹⁾	Fortsetzungspunkte (drei Punkte) …
`⟨@⟩` ⁽²⁾	am Zeilenanfang (!) Beispielliste, optional auch `⟨@liste⟩` mit Label. Wird im Dokument fortlaufend durchnummeriert, mit em Label kann darauf referenziert werden.

⁽¹⁾ erfordert die Option --smart

⁽²⁾ Die Liste kann sich im Dokument verteilen, jeder Listenteil muss jedoch davor und danach eine Leerzeile haben, sonst wird die Liste nicht erkannt und es kann nicht darauf referenziert werden. Aus

⟨@⟩ Listeneintrag.
⟨@⟩ Listeneintrag.
⟨@test⟩ referenzierbarer Listeneintrag.

Wie bereits in ⟨@test⟩ gezeigt wurde,...

wird

Listeneintrag
Listeneintrag
referenzierbarer Listeneintrag

Wie bereits in (3) gezeigt wurde,…

Vorlagen-Inhalte steuern

Mit diesem Block

% Titel
% Autor⟨en, durch Semikolon getrennt⟩
% Datum

kann die Ausgabe für HTML (und LaTeX) der entsprechenden Elemente erzeugt werden.