Menschenlesbare Auszeichnungssprache Arbeiten mit AsciiDoc-Markups

Anbieter zum Thema

Vertiv GmbH

DAXTEN GmbH

Kentix GmbH

AsciiDoc ist derzeit die interessanteste leichtgewichtige Markup-Sprache – mit mehr Features als Branchenprimus Markdown und einem sehr guten Tooling. Für technische Dokumentationen, aber auch schlichte Blogs hat das Format viel zu bieten.

AsciiDoc fällt unter die Kategorie der leichtgewichtigen Markup-Sprachen, sprich menschenlesbare Auszeichnungssprachen. Die Sprache existiert bereits seit 2002, dem Geburtsjahr gleich mehrerer ähnlicher Projekte. Die aktuelle Aufmerksamkeit für AsciiDoc ist immer im Zusammenhang mit dem Asciidoctor-Projekt zu betrachten, das mittlerweile die offizielle AsciiDoc-Spezifikation verwaltet, als Prozessor die Referenzimplementierung ist und eine komplette Toolchain anbietet.

Einen Vergleich mehrerer Auszeichnungssprachen haben wir Ihnen kürzlich präsentiert, daher hier nur ganz kurz zum Unterschied zu Markdown: Der Quasi-Standard konzentriert sich in seiner Reinform auf die wichtigsten Auszeichnungen und deren Umwandlung in HTML. Im Laufe der Zeit wurden die Ansprüche der Nutzer größer und es entwickelten sich Varianten von Markdown – so dass es heute keinen allgemeingültigen Markdown-Code mehr gibt.

AsciiDoc war hingegen von vornherein darauf ausgelegt, im Kern erweitert zu werden und bietet einige Features und Tags mehr. Das liegt vor allem daran, dass AsciiDoc eine reine Text-Alternative zu DocBook sein sollte – und über den zugehörigen Konverter lassen sich entsprechend DocBook-Tools nutzen. DocBook seinerseits wird bereits seit 1991 entwickelt und wird in großen Projekten wie KDE und Gnome verwendet.

Arbeiten mit AsciiDoc

Die eigentliche Arbeit mit Asciidoctor ist trivial: AsciiDoc-Inhalte können über die Kommandozeile konvertiert werden, außerdem steht eine API zur Verfügung. Die Standardversion ist eine Ruby-Anwendung, daneben werden bei GitHub allerlei AsciiDoc-Tools angeboten: Java-Bindings, ein JavaScript-Port, Konverter für PDF, Bespoke.js, EPUB und DocBook, Diagramm-Erweiterungen, Plugins für Visual Studio Code, IntelliJ IDEA, Maven, Gradle und Jekyll, ebenso für die Browser Chrome, Firefox, Edge und Opera, Docker-Images und ein Parser für AsciiMath.

Der wichtigste Aspekt ist aber natürlich das eigentliche AsciiDoc-Dokument. Und das unterscheidet sich nicht bloß in der Syntax von Markdown, sondern auch bezüglich der Features – es gibt hier nämlich auch Anklänge einer Skriptsprache. Im Folgenden die wichtigsten Möglichkeiten abseits der reinen Formatierung von Inhalten.

• Attribute und Header: Ganze Dokumente und einzelne Elemente können attributiert werden. So können Sie zum Beispiel Pfade für Bilder festlegen, Metainformationen als Header setzen, Features wie das automatische Inhaltsverzeichnis aktivieren oder dessen Ebenen konfigurieren.

• Ersetzungen: AsciiDoc kann mit Textbausteinen umgehen und das auf zwei Arten. Zum einen lassen sich simple Ersetzungen direkt im Dokument über Attribute verwenden, hier genügt eine simple Syntax wie “:ml: Mirco Lang”, um fortan die Initialen durch den Namen ersetzen zu lassen, sobald das Dokument durch den Prozessor läuft. Zum anderen können externe Inhalte per include-Anweisung eingeholt werden. Über solch einen Include lassen sich aber nicht bloß Inhalte wiederverwenden, sondern auch globale Attribute setzen – ein Feature, das allein schon deutlich über das Markdown-Konzept hinausgeht.

• Conditionals: Über simple if-Anweisungen lassen sich Attribute evaluieren und Inhaltsblöcke entsprechend ein- oder ausschließen.

Insbesondere für Markdown-Umsteiger gibt es auch bei der Syntax selbst ein paar interessante Features. Beispielsweise hat AsciiDoc spezielle Anweisungen für Auszeichnungen innerhalb von Wörtern, schlicht über doppelte Tags – etwa für kursiv:

Ein weiteres Highlight ist die automatische Nummerierung in Listen: In Markdown werden diese mit „1. foo 2. bar 3. Foobar“ erstellt, in AsciiDoc genügt:

Der große Vorteil daran: Sie können nachträglich Elemente einfügen, ohne gleich alles Nummern manuell ändern zu müssen. Die genaue Syntax für all diese Features finden Sie in der grundsätzlich sehr guten AsciiDoc-Dokumentation, die allerdings noch an einigen Stellen Lücken aufweist.

Bei einigen Aspekten ist schlicht zu spüren, dass das wesentlich simpler gestrickte Markdown doch etwas reifer ist. Auf Wordpress.com ist beispielsweise nur ein noch dazu veraltetes Backend-Plug-in zu finden, dafür gibt es auf GitHub immerhin einige Konverter/Publisher für die Kommandozeile. Dennoch dürfte AsciiDoc hier in nächster Zeit kräftig aufholen, spätestens wenn die Standardisierungsbemühungen des AsciiDoc-Charter der Eclipse Foundation Früchte tragen.

AsciiDoc in VS Code und IntelliJ

Microsoft Visual Studio Code macht Ihnen die Sache einfach, Sie können einfach das Asciidoctor-Plug-in vom Visual-Studio-Marketplace installieren. Darüber bekommen Sie Syntax-Highlighting, Live-Preview und die Möglichkeit, Snippets zu verwenden. Öffnen Sie in VSC einfach die Eingabe mit „STRG+P“ und installieren Sie via

Auch für die IntelliJ-Entwicklungsumgebung gibt es ein AsciiDoc-Plug-in mit ähnlichem Funktionsumfang.

AsciiDoc in Notepad++

Für Notepad++ gibt es leider kein echtes Plugin, hier muss ein kleiner Umweg gemacht werden. Zunächst müssen Sie das Syntax-Highlighting einrichten, also schlicht die hier verlinkte XML-Datei über den Sprachenmanager in Notepad++ importieren.

Für die Vorschau im Browser können Sie wiederum eine der offiziellen Browser-Erweiterungen verwenden. Nach der Installation müssen Sie das Plug-in einmal aufrufen, um die nötigen Freigaben zu erteilen. Optional lassen sich hier auch eigene CSS-Dateien hinterlegen.

Die Vorschau ist natürlich nicht live, sondern wird in einem einstellbaren Turnus aktualisiert – das Dokument muss also in Notepad++ zunächst gespeichert werden. Die Arbeit mit den Browser-Plugins funktioniert an und für sich sehr gut, aber es gibt an einigen Stellen Probleme mit der korrekten Umsetzung von AsciiDoc-Features, etwa einigen Formatierungen von Tabellen.

AsciiDoc in Vim

In Vim wird es wieder einfach: Das Syntax-Highlighting ist bereits standardmäßig vorhanden und die Vorschau läuft natürlich über den Browser, so dass Sie lediglich die aktuelle Datei in einem solchen öffnen müssen, was aus Vim selbst etwa mit …

… funktioniert.

Im Gegensatz zu Notepad++ lässt sich aber auch das Folding, also das Ein- und Ausklappen hierarchischer Ebenen nutzen – ebenfalls ohne Plug-in. Sie können schlicht den Code aus dem Blog-Beitrag von Emmanuel Bernard in die „~/.vimrc“ kopieren und anschließend alle mit Gleichheitszeichen eingeleiteten Ebenen mit den üblichen Vim-Folding-Kommandos öffnen und schließen. Und falls Sie an diese nicht gewohnt sind: Die Kommandos beginnen immer mit „z“ (weil das Z nach etwas Gefaltetem aussehen soll …), gefolgt von etwa „o“ zum Öffnen der Ebene unter dem Curser oder „c“ zum Schließen – und das im Kommandomodus direkt im Text, nicht mit „:“ im Prompt!

Wenn Sie nun Blut geleckt haben und ein paar erste Schritte mit AsciiDoc und Asciidoctor unternehmen wollen, starten Sie doch einfach mit asciidocLIVE, einem Editor samt Vorschau direkt im Browser. Daheim im Terminal genügt für die Asciidoctor-Installation ein simples …

… und die Anweisung ...

… erstellt eine HTML5-Version der angegebenen AsciiDoc-Datei im selben Pfad. Noch einfacher geht es über das Browser-Plug-in, mit einem großen Vorteil: In dessen Einstellungen finden sich eine ganze Reihe vorgegebener Themes/Stylesheets, die Sie bequem durchprobieren können.

(ID:47330459)