Markdown, Textile, AsciiDoc und reStructuredText 4 freie Markup-Sprachen für die Dokumentation

Entwickler stehen nicht bloß vor der Wahl einer Programmiersprache. Auch für die Dokumentation müssen sie sich für eine Sprache entscheiden – reines HTML hat hier längst ausgedient.

Die Dokumentation von Softwareprojekten gliedert sich oft in zwei Teile: API- und Quellcode-Dokumentation auf der einen und Handbücher für Nutzer, Betreiber und gegebenenfalls Entwickler auf der anderen Seite. Der technische Part wird meist automatisiert umgesetzt und in irgendeine Form von HTML ausgegeben.

Hier geht es um die manuell geschriebenen Handbücher: Auch diese landen am Ende meist als HTML im Browser, jedoch auch in Formaten wie PDF oder LaTeX, um Print-Ausgaben herzustellen. Die heute wohl gebräuchlichste leichtgewichtige Markup-Sprache für Online-Content dürfte Markdown sein. Mit der sehr einfach gehaltenen Syntax ist es auch Laien schnell möglich, ordentlich formatierte Artikel zu schreiben.

Ein Großteil aller Wordpress-Artikel im Netz dürfte, wenn nicht mit dem internen WYSIWYG-Editor geschrieben, mit Markdown produziert worden sein; und auch GitHub unterstützt den freien Standard – in einer eigenen Variante mit zusätzlichen Features, was zum wohl größten Markdown-Problem hinführt, dazu gleich mehr.

Doch es gibt eben auch Alternativen, die hier ebenfalls kurz vorgestellt werden sollen: AsciiDoc als voraussichtlicher Nachfolger und mächtigste Sprache, reStructuredText, das auch die technische Dokumentation beherrscht, und letztlich Textile, das sich als minimalistische Variante anbieten könnte. Bei allen Sprachen handelt es sich um offene Formate.

Markdown

Markdown existiert bereits seit 2004 und zeichnet sich vor allem durch drei Dinge aus: Eine sehr simple Syntax, enorme Verbreitung und etliche Abspaltungen/Erweiterungen. Markdown-Code wird schlicht in HTML übersetzt und ist in seiner ursprünglichen Form darauf ausgelegt, die wichtigsten HTML-Elemente in vereinfachter Form zu verwenden.

Markdown macht es also möglich, Artikel ohne HTML-Kenntnisse oder WYSIWYG-Editoren in ganz normalen Textverarbeitungen, Content Management Systemen und so weiter zu schreiben. Die Idee setzte sich zunehmen durch und führte zu dem Problem, das Markdown heute anhaftet: Es gibt im Grunde nicht „das eine“ Markdown.

Zum einen gibt es Varianten wie GitHub Flavored Markdown, die zusätzliche Features einbringen. Zum anderen existieren Hunderte Tools, die Markdown für CMS implementieren, in andere Formate konvertieren, weitere Notationen erlauben und so weiter. Der Vorteil daran: Im Markdown-Universum lässt sich so ziemlich jeder Wunsch erfüllen. Der Nachteil: Es ist das berühmte Rabbit Hole, irgendwann hat man sich einen riesigen Tool Stack zusammengeschraubt, der an etliche Stellen gewartet werden will.

Ab und an gibt es zwar zaghafte Standardisierungsbemühungen, aber dies auch nur von Dritten, Ur-Entwickler John Gruber dazu: „Different sites (and people) have different needs. No one syntax would make all happy.“ Dazu passt auch die Lizenzierung im permissiven BSD-Stil, die die Weiterverwendung extrem einfach macht.

Hier zeigt sich wieder der Vorteil, dass es für alles eine Lösung gibt, und der Nachteil, dass Markdown-Code nach einem Tool-Wechsel, etwa einem CMS-Addon, nicht mehr funktioniert. Für große Dokumentationsprojekte hat Markdown durchaus seinen Reiz, möchte man Features außerhalb der Basis nutzen ist es aber mit Vorsicht zu genießen. Für Blog-Texte und dergleichen ist Markdown nach wie vor erste Wahl – und dafür wurde es auch ins Leben gerufen!

Textile

Textile taucht in Diskussionen um leichtgewichtige Markup-Sprachen immer wieder auf, so auch hier – aber nur ganz kurz: Im Vergleich mit Markdown sieht man schnell, dass Syntax und Scope so ähnlich sind, dass es zunächst austauschbar wirkt. Warum, wird schnell klar. Textile existiert bereits seit 2002, ist also älter als Markdown.

In seinem Beitrag zum ersten Release von Markdown bezieht sich Entwickler John Gruber auch direkt auf Textile und die Ähnlichkeit zu Markdown. Denn bei Textile lief ursprünglich alles über einen Online-Editor, über den man Textile-Markup schreiben, nach HTML konvertieren und dann via Copy&Paste in eigenen Projekten nutzen konnte.

Markdown hat eine solche Konvertierung dann als Stand-alone-Perl-Tool mit einer unter anderem an Textile angelehnten Syntax umgesetzt. Für die Textile-Spezifikation existieren PHP- und Python-Implementierungen. Für größere Projekte dürfte Textile nur in Ausnahmefällen relevant sein, Markdown ist in der Basis sehr ähnlich, letztlich aber wesentlich mächtiger und vor allem verbreiteter.

AsciiDoc

Auch AsciiDoc stammt aus dem Jahr 2002 und wurde ursprünglich in Python geschrieben, allerdings nicht nur für Webseiten oder als reiner HTML-Übersetzer, sondern als Dokumentenformat für alle Zwecke, übersetzbar in unter anderem HTML, PDF, EPUB und man page. Mittlerweile wird die AsciiDoc-Definition offiziell vom Projekt Asciidoctor betreut, das eine komplette Toolchain zur Konvertierung von AsciiDoc nach HTML, DocBook und weitere Formate zur Verfügung stellt.

Asciidoctor ist sich der prominenten Rolle von Markdown bewusst: „The defacto lightweight markup language is Markdown.“ Und hier bietet sich AsciiDoc als die bessere Alternative an: Auf syntaktischer Seite ist AsciiDoc simpel genug, um als 1:1-Ersatz für typische Markdown-Zwecke genutzt zu werden. Technisch bietet AsciiDoc, beziehungsweise die Asciidoctor-Toolchain, einige Möglichkeiten selbst, die bei Markdown über Drittwerkzeuge umgesetzt werden müssten (etwa importierbare Eigenschaften, Textersetzungen oder Plugins).

Auf konzeptioneller Ebene setzt AsciiDoc zudem auf erweiterbare Syntax und Features als Kernelemente – es gibt also Raum zum Wachstum, wo Markdown eher statisch bleibt und auf Varianten und Drittwerkzeuge setzt. Und seit 2019 gibt es zudem Standardisierungsbemühungen unter der Schirmherrschaft der Eclipse Foundation. Alle Punkte, insbesondere aber die Aussicht auf echte Standards, sprechen klar und deutlich für die Bevorzugung von AsciiDoc, wenn es um größere Dokumentationsprojekte geht.

Bezüglich der Syntax sind die Unterschiede nicht groß, aber im Detail kann AsciiDoc durchaus punkten. Beispielsweise sind viele Auszeichnungen kürzer gehalten, es gibt explizite Tags für Auszeichnungen innerhalb von Wörtern, Links sind deutlich lesbarer, die Nummerierung in Listen geschieht dynamisch und so weiter. Ein Feature, das allein schon enorme Vorteile bietet: Über das include-Tag können externe Inhalte einbezogen werden!

Was die Unterstützung in Entwicklungsumgebungen, Browsern und so weiter angeht, steht AsciiDoc ebenfalls gut da, prominente IDEs wie Microsoft Visual Studio werden unterstützt, es gibt Vorschau-Erweiterungen für alle großen Browser und auch Editoren wie Vi, Emacs oder Notepad++ werden mit Erweiterungen versorgt.

Nichtsdestoweniger ist Markdown hier im Zweifel noch im Vorteil – selbst in etlichen Kommentarfeldern von Webseiten funktioniert Markdown-Syntax standardmäßig. Aber AsciiDoc/Asciidoctor ist derzeit wohl das spannendste Projekt im Bereich einfacher Markup-Sprachen.

reStructuredText

reStructuredText, es wird Sie nicht wundern, stammt aus dem Markup-Wunderjahr 2002 und gehört zum Docutils-Projekt. reST, wie es oft kurz referenziert wird, wird ebenso wie Textile häufig in diesem Kontext genannt, wird dem Vergleich mit AsciiDoc und Markdown aber nicht wirklich gerecht.

Interessant ist es dennoch, da reStructuredText nicht bloß eine Spezifikation für manuell geschriebene Texte ist, auch wenn Sie sie etwa auf GitHub und Bitbucket nutzen könnten. Im Wesentlichen ist reST auf die technische Dokumentation ausgelegt, so wird zum Beispiel der Linux-Kernel automatisch über Sphinx im reST-Format dokumentiert – nachdem erst Markdown und dann AsciiDoc verworfen wurden.

Zusammenfassung

Für die manuelle Dokumentation ist Markdown nach wie vor Standard, AsciiDoc hat jedoch das Potenzial, dies in recht kurzer Zeit zu ändern – wobei die Akzeptanz und Verbreitung des Marktführers durch den Einsatz in Wordpress und auf GitHub nicht zu unterschätzen ist. Textile hingegen dürfte allenfalls in Ausnahmefällen relevant sein. reStructuredText ist eher bei der automatisierten technischen Dokumentation zu finden und für Handbücher daher wohl nur im Zusammenspiel mit dieser wirklich spannend – wobei die Syntax selbst sehr gut schreibbar ist.

Wofür auch immer Sie sich entscheiden: Alle großen Sprachen können im Grunde beliebig hin und her konvertiert werden, über viele spezialisierte Tools, aber auch den universellen Konverter Pandoc.

(ID:47324931)