AsciiDoc ist ein einfaches textuelles Dateiformat zum schreiben von Dokumentationen, Berichten, Artikeln und Büchern. Das Dateiformat kann genutzt werden um unterschiedlichste Ausgabeformate zu erzeugen, wie zB HTML, PDF oder EPUB. Das Format wird zB vom Verlag O'Reilly Media verwendet um Bücher zu schreiben. Dies kann man zB am freien Buch "Mastering Bitcoin" von Andreas Antonopoulos sehen.

AsciiDoc verwendet einfache textuelle Muster um Texteile auszuzeichnen. Um zB einen Textabschnitt fett zu formatieren, muss der Abschnitt mit einem Sternchen gestartet und beendet werden: *fett Schrift*. Ähnliches kann für Kursivschrift mit Unterstrichen _ ermöglich werden. Die Website AsciiDoctor bietet einen sehr übersichtlichen und guten Einstieg in die Funktionsweise von AsciiDoc.

Im Projekt Blocks wurde ein Bericht erstellt, welcher ebenfalls mit AsciiDoc geschrieben wurde. Dies ermöglichte uns eine Ausgabe als PDF und HTML zu erstellen. Das Programm asciidoctor kann als Kommandozeilen-Programm genutzt werden um AsciiDoc-Dokumente in unterschiedliche Ausgabeformate zu transferieren. Im folgenden sollen noch die wichtigsten Befehle des asciidoctor Programms erklärt werden.

Erstellung einer HTML Repräsentation

Im Allgemeinen kann das asciidoctor Kommando so verwendet werden:

asciidoctor input.asciidoc

Dies würde das AsciiDoc-Dokument mit dem Namen input.asciidoc aus dem aktuellen Ordner verwenden und daraus eine HTML Repräsentation im aktuellen Ordner erzeugen. HTML ist das Defaultformat für die Ausgabe. Es können jedoch unterschiedliche Flags verwendet werden um die Ausgabe zu bearbeiten.

asciidoctor -d book -a lang=de -D build input.asciidoc

Dabei kann die Formatvorlage mit -d gesetzt werden, welche in diesem Fall book ist. Ebenfalls kann die Sprache über -a gesetzt werden, dies setzt unterschiedliche Hilfstexte und ähnliches zB in Deutsch (de). Mit -D kann das Verzeichnis angegeben werden, welches das Ziel für die Ausgabe sein soll, in diesem Fall das Verzeichnis build.

Erstellung einer PDF Repräsentation

Neben HTML können auch PDF Dokumente erstellt werden. Dazu muss ein zusätzliches Programm asciidoctor-pdf installiert werden.

asciidoctor -r asciidoctor-pdf -b pdf -d book -a lang=de -D build input.asciidoc

Das Flag -r wird verwendet um einen externen Renderer zu setzen, dies ist in dem demonstrierten Fall asciidoctor-pdf. Zusätzlich muss noch das Ausgabeformat mit -b bestimmt werden, in diesem Fall pdf.

AsciiDoctor hat noch viele weitere Funktionen, welche der Dokumentation entnommen werden können.