Markdown und kramdown

Markdown ist eine von John Gruber und Aaron Swartz entwickelte, einfache Auszeichnungssprache mit dem Ziel, schnell und komfortabel Webseiten zu erstellen, ohne sich mit den Tücken von HTML herumschlagen zu müssen. Dabei sollte der Text für Menschen leicht lesbar bleiben. Die Referenzimplementierung ist in der Skriptpsrache Perl geschrieben und RubyFrontier ruft dieses Perl-Skript auf.

Markdown hatte nie das Ziel, HTML zu ersetzen, an allen Stellen, an denen Markdown nicht ausreicht, kann man HTML einsetzen, das der Markdown-Interpreter einfach unangetastet durchreicht. Markdown ist mittlerweile so etwas wie ein (Quasi-) Standard, es existieren Implementierungen in vielen anderen Skript- und Programmiersprachen und es gibt etliche Erweiterungen, von denen eine — nämlich kramdown durch RubyFrontier von Hause aus unterstützt wird.

Es ist nicht Ziel des Kapitels, die komplette Syntax von Markdown vorzustellen, dazu gibt es eine hervorragende deutschsprachige Webseite, ich möchte nur die wichtigsten Elemente vorstellen, die ich tagtäglich nutze:

# Das ist eine H1-Überschrift und
## Das eine H2-Überschrift

das geht natürlich weiter bis H5. Textauszeichnungen sind auch möglich:

**dieser Text wird fett dargestellt** und *dieser Text kursiv*
und so sieht ein [Link zur
RubyFrontier-Dokumentation](http://www.apeth.com/RubyFrontierDocs/default.html)
aus.
In RubyFrontier kann man interne Links natürlich auch abkürzen:
Hier geht es zur [Startseite](Startseite)

Text, der mit einem Tabulatorschritt eingerückt ist, wird als Quelltext behandelt, also in einem <code><pre>-Block eingeschlossen. Um das eventuelle Maskieren von reservierten Zeichen kümmert sich Markdown selber. Das gilt auch für Inline-Code-Elemente, die zwischen zwei Backticks (`) eingeschlossen werden.

Listen gehen auch. Zunächst eine ungeordnete Liste:

  * Listenpunkt 1
  * Listenpunkt 2

wird zu

• Listenpunkt 1
• Listenpunkt 2

Dabei ist zu beachten, daß zwei Leerzeichen vor dem Stern stehen müssen.

Geordnete (durchnumerierte) Listen sehen ähnlich aus. Auch zwei Leerzeichen einrücken und dann

  1. Listenpunkt 1
  2. Listenpunkt 2

schreiben. Das ergibt das gewünschte Ergebnis:

1. Listenpunkt 1
2. Listenpunkt 2

Die Reihenfolge der Ziffern und welche gewählt wird, ist dabei völlig unerheblich. Auch

  9. Listenpunkt 1
  9. Listenpunkt 2

wird zu

1. Listenpunkt 1
2. Listenpunkt 2

Die korrekte Numerierung übernimmt Markdown für uns. Das ist manchmal recht nützlich, wenn man nachträglich in einer großen Liste noch einige Punkte einfügen muß.

Das ist eigentlich alles, was ich benötige und was ich mir gemerkt habe, denn für Bilder nutze ich RubyFrontiers <%= imageref() %>-Makro. Brauche ich doch einmal mehr, schreibe ich dies entweder direkt in HTML (z.B. Tabellen) oder ich schaue doch einmal im Syntax-Manual nach.

Es gibt (mindestens) zwei Probleme, die bei der Nutzung des Markdown-Interpreters auftreten. Links mit Klammern, wie sie zum Beispiel in der Wikipedia häufig vorkommen (http://de.wikipedia.org/wiki/Pascal_(Programmiersprache)) werden in Markdown nicht korrekt interpretiert, die schließende Klammer ist nicht mehr Teil des Links, der daher dann in die Leere geht. Als Workaround kann man an dieser Stelle direkt mit HTML arbeiten, also zum Beispiel

<a href="http://de.wikipedia.org/wiki/Pascal_(Programmiersprache)">Pascal</a>

schreiben, schön ist dies natürlich nicht. Andere Markdown-Implementierungen und/oder -Erweiterungen wie kramdown haben diesen Fehler nicht. Das gilt auch für das zweite Problem:

Da nicht nur das Sternchen (*), sondern auch der Unterstrich (_) genutzt werden kann, um Text kursiv zu setzen, sind Unterstriche in Links und Dateinamen problematisch (auch im <%= imageref() %>-Makro). Das ist ärgerlich, da Unterstriche speziell in Dateinamen für Bilder häufig vorkommen. Aber es gibt nur einen Lösung (wenn man mit Markdown arbeiten will): Alle Unterstriche in Dateinamen zum Beispiel durch Bindestriche ersetzen. Die sind unproblematisch. Auch dieser Fehler tritt in kramdown nicht auf.

Doch was ist mit Fußnoten?

Jetzt haben Sie mich erwischt! Fußnoten kann Markdown nicht! Vermutlich haben die Schöpfer von Markdown Fußnoten als etwas dem Web völlig Fremdes angesehen und deshalb darauf verzichtet. Eine Aussage, die ich durchaus unterstreichen kann. In der Besten aller Welten kommen Fußnoten auf Webseiten nicht vor. Nur leider leben wir nicht in der Besten aller Welten und auch ich habe einige Projekte, die ohne Fußnoten nicht auskommen. Und so habe ich es mit kramdwon versucht. In der Theorie war dies auch recht einfach: Sie müssen bloß in der #prefs.yaml

:markdown: true

durch

:kramdown: true

ersetzen und schon flutscht alles. Denn RubyFrontier kümmert sich um alles andere und nimmt in diesem Fall den kramdown-Interpreter. Doch leider erlebte ich einige unschöne Überraschungen: RubyFrontier ruft in der Default-Implementierung den Markdown-Interpreter im pageFilter auf und der arbeitet auf dem :bodytext, also ohne das ganze HTML des Templates drumherum. kramdown dagegen wird im postMacroFilter aufgerufen, da das mächtigere kramdown einige unschöne Sachen mit den Makros anstellt (genauer: Es setzt »intelligente« Anführungszeichen statt der doppelten Hochkommata). Abgesehen davon, daß »intelligente« Anführungszeichen außerhalb der anglo-amerikanischen Welt nie eine gute Idee sind, da fast jede Sprache eigene Anführungszeichen besitzt (zum Beispiel in Deutschland „“, in Frankreich »« und in der Schweiz «» — oder umgekehrt), ist das natürlich katastrophal für Makro-Aufrufe etc. Deshalb der Aufruf nach der Makro-Ersetzung. Doch damit rennt man natürlich in folgende zwei Probleme:

1. Der postMacroFilter arbeitet mit dem :postMacroText, und das ist der Text inklusive des vollständigen Templates, da in den Templates ja ebenfalls Makros vorkommen dürfen. Und was passiert, wenn man ordentlich eingerückte Templates geschrieben hat und man kramdown, das ja im Prinzip eine Erweiterung von Markdown ist, mit Tabstops eingerückten HTML-Quelltext vorsetzt? Richtig! kramdown behandelt dies als Code und legt einen <code><pre>-Block drumherum. (Es gibt Tricks, der Software dieses Verhalten abzugewöhnen — zum Beispiel auf Einrückungen verzichten —, aber schön ist es trotzdem nicht).
2. Schlimmer aber ist: kramdown schreibt den Text der Fußnoten ganz unten an den Fuß der Seite, also noch unterhalb des Footers mit den Copyright-Vermerk und den schönen Buttons, statt sie an das Ende des Content-Blocks zu schreiben. Dieses Verhalten ist nicht wirklich der Software anzulasten, denn woher soll sie wissen, wo der Content endet und das Template anfängt?

Markdown oder kramdown?

Daher habe ich mich nach vielen erfolglosen Experimenten, kramdown dieses unerwünschte Verhalten auszutreiben, entschlossen, auf kramdown — und damit auf Fußnoten — zu verzichten. Das, was kramdown mit dem Quelltext anstellt, ist nicht wirklich kompatibel zu dem, was ich unter sauberen Quelltext verstehe.

Dagegen ist Markdown — bei all seinen Schwächen — ein anerkannter (Quasi-) Standard, der auch von vielen anderen Werkzeugen gelesen und interpretiert werden kann. Und da ich — wie Sie im weiteren Verlauf des Buches noch sehen werden — die Idee habe, mit RubyFrontier erstellte Markdown-Seiten auf der einen Seite zu nutzen, meine »eigene« Website mit RubyFrontier herauszuschreibe, aber auf der anderen Seite diese Markdown-Dateien auch anderen Webdiensten zur Verfügung zu stellen, möchte ich natürlich die Vorzüge dieses (Quasi-) Standards auch nutzen.

Wenn Sie aus irgendwelchen Gründen dennoch kramdown nutzen wollen oder müssen, kann ich Ihnen nur zwei Empfehlungen mit auf den Weg geben:

1. Halten Sie das Template so einfach wie möglich und verzichten Sie auf Fußzeilen (bringen Sie die Informationen in einer Seitenleiste unter). Dann stehen die Fußnoten dort, wo Sie sie auch erwarten.
2. Verzichten Sie in ihrem Template auf Einrückungen. Das sieht dann zwar nicht schön aus, hält kramdown aber davon ab, mit Ihrem HTML-Code seltsame Dinge anzustellen.

Sie merken schon: Nach einer kurzen Phase der Euphorie bin ich mit kramdown nicht wirklich glücklich geworden.

Und Fußnoten? Fußnoten verwalte ich da, wo ich wirklich nicht darauf verzichten kann, mit der Hand. Das ist zwar umständlich, aber es funktioniert und hält mich als Autoren auch davon ab, mehr Fußnoten als unbedingt nötig zu produzieren. Das schadet sicher der Lesefreundlichkeit meiner Texte nicht.