Github-README: R.I.P. Markdown – es lebe AsciiDoc!

Markdown – eine Auszeichnungssprache

Markdown ist eine textbasierte Auszeichnungssprache, in der  Texte mit Gestaltungselementen wie Kapiteln, Absätzen, Aufzählungslisten, Numerierungen u.ä. sehr einfach zu verfassen sind. Laut Wikipedia ist „ein Ziel von Markdown […], dass schon die Ausgangsform ohne weitere Konvertierung leicht lesbar ist“. Sinn und Zweck von Markdown ist allerdings die Konvertierung in schön formatiertes HTML. Um gestalterische Aspekte wie Layout, CSS usw. muss sich der Autor dabei nicht kümmern, das übernimmt die Konvertierungssoftware.

Auch auf Github werden die Inhalte der README.md schön HTML-formatiert dargestellt. Der folgende Quelltext…

# Mein Projekt

Hier steht die Beschreibung für mein tolles Projekt.

* Aufzählungspunkt 1
* Aufzählungspunkt 2
* Aufzählungspunkt 3
* ...

…wird auf GitHub so dargestellt:

Allerdings sind die Möglichkeiten von Markdown begrenzt. Sobald etwas komplexere Gestaltungselemente wie z.B. Tabellen, Querverweise, Fußnoten o.ä. benötigt werden, muss auf eingebettetes HTML oder Markdown-Erweiterungen zurückgegriffen werden. Selbst den Machern von GitHub ist Markdown nicht mächtig genug, weswegen auf GitHub ein Dialekt mit Erweiterungen namens GitHub Flavored Markdown  zum Einsatz kommt. Auch die Mitbewerber von GitHub setzen auf Markdown-Erweiterungen, wie z.B. Bitbucket mit CommonMark (einer Markdown-Spezifikation) mit ein paar Erweiterungen, oder GitLab mit GitLab Flavored Markdown.

AsciiDoc – die bessere Alternative

Was jedoch wahrscheinlich wenige wissen: Neben Markdown unterstützt GitHub für seine README-Dateien auch AsciiDoc. Statt einer README.md stellt man einfach eine README.adoc-Datei bereit, und kann so die genauso einfache und knappe, aber sehr viel mächtigere Auszeichnungssprache AsciiDoc verwenden. Auf „AsciiDoc vs Markdown“ werden die vielen Vorzüge von AsciiDoc gegenüber Markdown beschrieben. In Kürze – AsciiDoc hat alles was man benötigt, allerdings ohne dass man auf Spracherweiterungen oder eingebettetes HTML zurückgreifen muss.

AsciiDoc als Tool für Dokumentation von Software(Architektur)

Doch nicht nur für README-Dateien auf GitHub ist AsciiDoc eine gute Wahl. Die Formatierungssprache eignet sich auch sehr gut zur allgemeinen Dokumentation von Software und Softwarearchitektur. Auf jaxEnter ist diesem Thema eine ganze Kolumne gewidmet: Hitchhiker’s Guide to Docs as Code. Die Dokumentation ist dann dort wo sie hingehört, nämlich beim Quellcode der Software, die sie beschreibt. Und mit entsprechenden Tools können aus AsciiDoc Dateiformate wie PDF oder gar Microsoft Word generiert werden.

Übrigens: für gängige IDEs wie z.B. IntelliJ IDEA, Eclipse, oder auch Visual Studio Code, gibt es Plugins für AsciiDoc, die direkt beim Verfassen der Dokumentation das gerenderte Ergebnis in einer Live-Vorschau anzeigen.