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

Auf Github gehört es zum guten Ton, im Wurzelverzeichnis des Projekts eine README-Datei abzulegen. Darin beschreibt man wozu das Projekt gut ist, wie man es baut,  nutzt, u.s.w. In der Regel heißt die Datei README.md . Die Dateiendung .md sagt aus dass es sich um eine Markdown-Datei handelt.

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…

…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: wer mit IntelliJ IDEA entwickelt, kann sich das Plugin für AsciiDoc installieren, und sieht so direkt beim Verfassen das formatierte Ergebnis.

 

 

 

Zurück zur Übersicht

Kommentar verfassen

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.

*Pflichtfelder

*