Dokumentationen und Anleitungen mit Markdown + Pandoc

Einleitung

Texte für verschiedene Ausgabeformate erstellen wir bei Data·Code·Design im Markdown-Format und konvertierten diese mit Pandoc in das jeweils benötigte Ausgangsformat. Der große Vorteil ist dabei, dass ein Text nur einmal in Markdown geschrieben werden muss und mit dem flexiblen Konverter Pandoc direkt in verschiedene Formate wie beispielsweise HTML, PDF, DOCX oder EPUB umgewandelt werden kann.

Die Kombination aus Markdown + Pandoc übernimmt bei der Konvertierung die Schwerstarbeit, indem sie aus einem einfachen Quelltext automatisch die Formatierungen für Überschriften, Fußnoten, interne und externe Links, das Inhaltsverzeichnis und vieles mehr erzeugt. Selbst die sonst eher komplizierte Generierung von E-Books im EPUB– oder Amazon’s Mobipocket-Format ist dank Pandoc einfach zu realisieren.

Hier sollen kurz Markdown und Pandoc vorgestellt werden. Am Ende des Beitrags werden zudem zwei plattformunabhängige Editoren zur Erstellung von Markdown-Texten vorgestellt.

Markdown – die vereinfachte Auszeichnungssprache

Markdown ist eine vereinfachte Auszeichnungssprache, bei der die Textformatierung über verschiedene Satzzeichen gesteuert wird. Dabei ist die Quelldatei auch ohne die Konvertierung in ein Ausgabeformat schon leicht lesbar und entsprechend leicht zu bearbeiten. Mittels verschiedener Konvertierungstools kann eine solche Quelldatei in eine Vielzahl von Ausgangsformaten umgewandelt werden.

Es folgende einige Beispiele für Text-Formatierungen. Kapitelüberschriften werden beispielsweise durch eine oder mehrere voran gestellte Rauten erzeugt:

# Kapitel (Ebene 1)
## Unterkapitel (Ebene 2)

Im Ausgabeformat HTML wird daraus dann:

<h1>Kapitel (Ebene 1)</h1>
<h1>Unterkapitel (Ebene 2)</h2>

Fetter Text, kursiver Text oder durchgestrichener Text wird einfach durch folgende Satzzeichen erzeugt:

**Fetter Text**, *kursiver Text* oder ~~durchgestrichener Text~~

Geordnete und ungeordnete Listen werden ebenfalls durch voran gestellte Satzeichen erzeugt. Aus folgendem Markdown:

* ungeordneter Listeneintrag 1,
- auch mit Minus-Zeichen möglich,
+ oder auch durch ein Plus-Zeichen.

1. Erster geordneter Listeneintrag
1. Zweiter Listeneintrag -- die Zahl ist egal, die Nummerierung wird einfach automatisch vorgenommen.
2. Dritter Listeneintrag

werden die folgenden Listen generiert:

• ungeordneter Listeneintrag 1,
• auch mit Minus-Zeichen möglich,
• oder auch durch ein Plus-Zeichen.

1. Erster geordneter Listeneintrag
2. Zweiter Listeneintrag – die Zahl ist egal, die Nummerierung wird einfach automatisch vorgenommen.
3. Dritter Listeneintrag

Die Markdown-Syntax ist also sehr einfach gehalten und damit auch entsprechend schnell zu lernen. Weitere Formatierungen umfassen Tabellen, Zitate, Programmcode, Links und einiges mehr. Mehr dazu findet sich auf der Webseite des Markdown-Entwicklers (Englisch), die auch auf Deutsch übersetzt wurde. Eine Erweiterung der Markdown-Syntax bietet das Pandoc-Paket an, das im Folgenden beschrieben wird.

Pandoc – der flexible Parser für Multidokumentenformate

Pandoc ist ein Parser für Multidokumentenformate, der seit 2007 von John MacFarlane unter der freien GPL-Lizenz angeboten und weiterentwickelt wird. Pandoc kann Dokumente in verschiedenen Format lesen und in eine Vielzahl von Ausgabeformaten konvertieren. Die Formate umfassen u.a. Markdown, HTML, LaTeX, Microsoft Word oder LibreOffice oder EPUB (siehe auch die Übersicht auf der Pandoc-Webseite). Pandoc kann unter Windows, Linux/BSD oder Mac OS X installiert werden und wird über die Kommandozeile aufgerufen.

Wer es ohne Installation von Pandoc einmal ausprobieren möchte: Auf der Pandoc-Webseite wird eine Demo mit einem Online-Konverter angeboten, mit dem Texte von einem in ein anderes Format umgewandelt werden können.

Nach der Installation bietet Pandoc einen interaktiven Modus, an mit dem die Konvertierung von einem Format in ein anderes demonstriert werden kann. Mit den Optionen -f und -t wird das Ein- bzw. Ausgabeformat festgelegt. Um zum Beispiel einen Markdown-Text nach HTML umzuwandeln reicht folgender Befehl:

pandoc -f markdown -t html

Wird dann die Zeile

<p>Hello <em>pandoc</em>!</p>

eingegeben, wird mit Ctrl+D daraus in HTML:

<p>Hallo <em>Welt</em>!</p>

Um nun eine ganze in Markdown vorliegende Datei in ein HTML-Dokument umzuwandeln reicht folgender Befehl:

pandoc dateiname.md -f markdown -t html -s -o dateiname.html

Mit der Option -o wird der Name der Ausgabedatei angeben. Die Option -s steht für standalone und sorgt dafür, dass die Datei vollständig samt Header und Footer erstellt wird, und nicht nur der Inhalt als Fragment.

Die Dateiformate kann Pandoc übrigens auch an der Dateiendung erkennen. Obiger Befehl kann also auch kurz wie folgt geschrieben werden:

pandoc dateiname.md -s -o dateiname.html

Eine weitere oft genutzte Option ist --smart, die unter anderem dafür sorgt, dass Bindestriche korrekt übersetzt werden. Aus -- und --- werden so verschieden lange Gedankenstriche („–“ bzw. „—“, statt dem einfachen Bindestrich „-“).

Mit --toc wird automatisch ein Inhaltsverzeichnis aus dem im Dokument vorkommenden Überschriften erzeugt. Mit --toc-depth=N werden dabei Überschriften bis zu einer Tiefe N berücksichtigt.

Eine ausführliche Dokumentation zu Pandoc findet sich auf der Pandoc-Webseite (Englisch) oder auch in einem Artikel auf Deutsch auf Pro-Linux.

Passende Texteditoren

Die Markdown-Textdateien können prinzipiell mit jedem beliebigen Texteditor geschrieben werden, allerdings bieten einige Editoren deutlich mehr Komfort beim Schreiben von Markdown-Texten. Hier sollen zwei Editoren vorgestellt werden, Atom und Visual Studio Code, die beide mittels Erweiterungen sehr praktische Zusatzfunktionen für Markdown anbieten, die weit über einfaches Syntax Highlighting hinaus gehen. Sowohl Atom als auch Visual Studio Code basieren auf dem modernen Electron-Framework und sind sowohl für Windows, Linux als auch macOS verfügbar. Beide sind kostenlos unter der quelloffenen MIT-Lizenz veröffentlich worden.

Atom

Atom wird vom Projekt-Hosting-Dienst GitHub entwickelt und in einer stabilen Version seit Februar 2016 angeboten. Atom unterstützt fast alle Programmiersprachen und ist über sogenannte Packages sehr flexibel erweiterbar. Mit dem Package markdown-preview-plus ist beispielsweise eine Vorschaufunktion für Markdown verfügbar, die sogar spezielle Pandoc-Befehle mit berücksichtigt. Atom kann auf der offiziellen Webseite herunter geladen werden.

Visual Studio Code

Visual Studio Code (oder kurz VS Code) ist der etwas neuere Stern am Editor-Himmel, der von Microsoft entwickelt und seit April 2016 angeboten wird. Der Fokus liegt auf der Entwicklung von Webanwendungen und der Software-Entwicklung in diversen Programmiersprachen. Mit Markdown all in one steht aber auch eine Erweiterung des Editors zur Verfügung, die das Schreiben von Texten in Markdown extrem erleichtert. So bietet die Erweiterung unter Anderem diverse Textformatierungen mittels Tastenkombinationen an, eine automatisch aktualisierte Vorschau sowie ein Generator für Inhaltsverzeichnisse. VS Code kann auf der offiziellen Webseite herunter geladen werden.

Versionsverwaltung mittels Git

Sowohl Atom als auch Visual Studio Code haben schon in der Grundversion Git implementiert. Git ist eine sehr flexible, dezentrale Versionsverwaltung, mit deren Hilfe sich die Historie von Quelltexten festhalten lässt.

Die Entwicklung eines Textes kann sogar in verschiedenen Zweigen verfolgt werden, wenn zum Beispiel mehrere Personen parallel an einem Text oder einem Programmcode arbeiten. Die Zweige lassen sich jederzeit auch wieder zusammenführen. Eine der große Stärken von Git ist dabei, das die verschiedenen Versionen automatisch zusmmengeführt werden. Natürlich lassen sich auch frühere Versionen eines Textes schnell und einfach wieder herstellen.

Eine ausführliche Beschreibung zur Benutzung von Git findet sich auf der Git-Webseite (Englisch) oder in der deutschen Übersetzung des Buches “Pro Git”, sowie natürlich in den Dokumentation zu den Texteditoren Atom und VS Code.