Als Web-Entickler schreibt man oft auch Dokumentationen oder veröffentlicht wie ich eigene Fachbücher. Asciidoc eignet sich für dieses Vorhaben hervorragend und sticht Markdown um Längen, mit Seitenumbrüchen, einer komplexeren Handhabung von Bildern und so weiter. Mit Asciidoctor steht dafür ein exzellentes Werkzeug zur Verfügung. Eine kleine Einführung.

Mit der freien und stabilen Software Asciidoctor konvertierst Du Asciidoc-Dateien in perfekte HTML-Webseiten, PDF-Dokumente oder ePUB-eBooks. Ein großes Plus von Asciidoctor ist, dass Du eigene Designs erstellen kannst, die Themes.

Asciidoctor ist ein schnelles Textkonvertierungsprogramm und eine so genannte »Toolchain« (Werkzeugkette) für das Umwandeln von AsciiDoc-Inhalten nach HTML5, DocBook 5 (oder 4.5), PDF und zu weiteren Formaten. Asciidoctor ist in der Programmiersprache Ruby geschrieben, kommt daher als RubyGem und wird auf RubyGems.org veröffentlicht. Das Ruby Gem ist auch in mehreren Linux-Distributionen enthalten, darunter Fedora, Debian und Ubuntu. Asciidoctor ist Open Source und wird »gehostet« auf GitHub. Asciidoctor wird unter einer der MIT Lizenz veröffentlicht. Asciidoctor ist hervorragend dokumentiert – sofern Du Englisch sprichst.

Installation von Asciidoctor

Asciidoctor basiert auf Ruby, dass auf Deinem Computer laufen musst. Auf der Website von Asciidoctor erfährst Du welche Version notwendig ist. Um Asciidoctor genügt der folgende Befehl, der das Gem-Paket installiert.

Asciidoctor installieren

$ gem install asciidoctor

Um Asciidoctor zu aktualisieren, tippst Du folgendes in Dein Terminal:

Asciidoctor aktualisieren

$ gem update asciidoctor

Wenn Du eine neue Asciidoctor-Version mit gem install installierst, anstelle Asciidoctor mit gem update asciidoctor zu aktualisieren, kann es sein, dass auf Deinem Rechner mehrere Version installiert wurden. Sollte das der Fall sein, dann säuberst Du Dein System mit gem cleanup asciidoctor und alle alten Versionen werden entfernt.

Asciidoc-Dokumente in HTML-Dateien umwandeln

Um eine Asciidoc-Datei in eine HTML-Webseite zu verwandeln, genügt der folgende kurze Befehl:

$ asciidoctor textdatei.adoc

PDF-Dateien mit asciidoctor-pdf

Um asciidoctor-pdf zu installieren, tippst Du den folgenden Befehl in Dein Terminal:

$ gem install --pre asciidoctor-pdf

Um mit asciidoctor-pdf Asciidoc-Datein in PDF-Dateien umzuwandeln reicht der einfache Befehl…

$ asciidoctor-pdf beispiel.adoc

Und so sieht die ausführliche Version aus:

$ asciidoctor -r asciidoctor-pdf -b pdf example.adoc