Worknote: Erste Schritte mit AsciiDoc und Asciidoctor (und TextMate)

Nachdem ich am Donnerstag die leichtgewichtige Auszeichnungssprache AsciiDoc und das Tool Asciidoctor vorgestellt hatte, dachte ich, es müsse doch mit dem Teufel zugehen, wenn es für TextMate, dem Texteditor meines Vertrauens, nicht ein AsciiDoc-Bundle geben sollte. Schließlich ist Asciidoctor eine Ruby-Anwendung und TextMate ein Editor, der als interne Skriptsprache Ruby verwendet.

Natürlich gab es eins. Und der Autor ist kein geringerer als Matt Neuburg, der Mensch, der auch RubyFrontier geschrieben hat, das Tool, mit dem ich seit 2012 dieses Blog Kritzelheft und nahezu alle anderen statischen Seiten herausschreibe und das bisher als »Schweizer Messer« für meine Webaktivitäten dient.

Installation

Die Installation des Bundles verlief gewohnt einfach. Das gesamte Paket von GitHub herunterladen, entpacken und dann die Dateiendung auf .tmbundle reduzieren. Ein abschließender Doppelklick darauf und TextMate hat das Bundle installiert.

Das ist schön für TextMate, doch damit hatte ich aber Asciidoctor noch nicht auf meinem Rechner und das Bundle lief ins Leere. Mit Homebrew sollte das schnell gehen (dachte ich):

brew install asciidoctor

Im Prinzip war das nicht falsch gedacht, nur hatte ich Homebrew lange nicht mehr genutzt. Als erste installierte es sich erst einmal selber neu, dann fand es, daß meine Ruby-Version out of date wäre und installierte mir ein komplettes Ruby. Last but not least fehlten ihm auch noch ein paar Abhängigkeiten, die ebenfalls installiert wurden. Insgesamt dauerte die Installation so etwas länger als eine Stunde.

Dann lief es aber und erste Versuche zeigten, daß Asciidoctor mit TextMate arbeitet. Nur hatte ich noch keine CSS-Templates installiert und die Ergebnisse sahen daher nicht so schön aus. Hier half mir dann diese Seite weiter:

• Erst einmal habe ich die Asciidoctor Stylesheet Factory heruntergeladen und entpackt.
• Dann habe ich mich in das neue Verzeichnis navigiert.
• Bundler gehört zu meiner Ruby-Umgebung, so daß bundle install geügte, um Compass und Foundation zu installieren.
• Jetzt in diesem Verzeichnis nur noch compass compile aufrufen und alle sass-Dateien im sass-Verzeichnis wurden zu gleichnamigen css-Dateien ins stylesheet-Verzeichnis konvertiert und kopiert.

Es sind insgesamt dreizehn Stylesheets. Das dürfte für den Anfang erst einmal reichen.

Anwendung

Ich habe danach ein Projekt (ein Verzeichnis) angelegt und darin folgende AsciiDoc-Datei (Endung .adoc) erzeugt:

= Mein erster AsciiDoc-Test
Jörg Kantel <joerg@kantel.de>
:source-highlighter: prettify
:icons: font

Was ist eigentlich dieses http://cognitiones.kantel-chaos-team.de/produktivitaet/asciidoc.html[AsciiDoc] und was ist http://cognitiones.kantel-chaos-team.de/produktivitaet/asciidoctor.html[Asciidoctor]?

== Erste Zwischenüberschrift

* Punkt 1: `asciidoctor.css`
* Punkt 2

AsciiDoc kann Fußnoten.footnote:[Das ist eine Fußnote!]

[source, python]
----
print("Hallo Jörg") # <1>
a = 10
for i in range(a):
    print(i)
----
<1> Python-3-Stil

Und AsciiDoc kann Anmerkungen im Quellcode!

Zusätzlich habe ich die Datei asciidoctor.css aus der Template-Factory als myasciidoctor.css in das Projektverzeichnis hineinkopiert.

Die ersten vier Zeilen in der AsciiDoc-Datei sind so etwas wie der Frontmatter: Die erste Zeile legt den Titel fest, die zweite Zeile den Autor, dann folgen ein paar Direktiven. Die dritte Zeile definiert den Syntax-Highlighter und die vierte Zeile lädt einen zusätzlichen Icon-Font.

Dann folgt der eigentliche Text (es sind meine ersten Versuche mit AsciiDoc, darum seht mir gelegentliche Fehler oder Ungenauigkeiten nach). Die erste Überraschung: AsciiDoc kann von Haus aus Fußnoten. Wenn man weiß, wie schwer sich Markdown mit Fußnoten tut, eine angenehme Überraschung.

Die zweite, noch angenehmere Überraschung: AsciiDoc kann Anmerkungen im Quelltext. Seitdem ich das weiß, weiß ich gar nicht, wie ich solange ohne dieses Feature auskommen konnte. 🤓

Glitches

• Ich habe einige der Templates aus der Stylesheet Factory ausprobiert. Das TextMate-Bundle besteht aber darauf, daß sie alle myasciidoctor.css heißen. Die Stelle, an der man dies umkonfigurieren könnte, habe ich noch nicht gefunden.
• Außerdem werden die fertigen herausgeschriebenen HTML-Dateien in einem Verzeichnis asciidocOutput auf dem Desktop meines Macs abgelegt. Wo man dies ändern kann, habe ich auch noch nicht herausgefunden.
• Ich habe alle in der Dokumentation aufgeführten Syntax-Highlighter ausprobiert, bis auf hightlightjs habe ich sie auch alle zur Mitarbeit bewegen können.

Das sind alles keine Showstopper, vor allem deshalb, weil ich ja notfalls immer noch auf die Kommandozeile ausweichen kann.

Fazit

Ich habe zwar mehr Zeit damit verbracht, als ich ursprünglich geplant hatte, aber das Schreiben mit AsciiDoc macht wirklich Spaß. Ich habe dann auch noch 99 Cent geopfert und mir das Ebook »Making eBooks: How To Make and Publish your Books With Free Tools« von Michael Lynnmore heruntergeladen – so begeistert bin ich erst einmal. Und dann habe ich viel in der umfangreichen Documenation von Asciidoctor gestöbert. Zwar scheint die Konvertierung nach PDF noch einmal mit zusätzlichen Downloads verbunden zu sein, aber AsciiDoc kann eigentlich all das, was ich mir in Markdown schon immer gewünscht habe. Und das ist diesen zusätzlichen Aufwand sicher wert.

Ich werde sicher nicht dieses Blog Kritzelheft so ohne weiteres auf AsciiDoc umstellen, aber für die nächsten, fälligen Dokumentationen werde ich das Tool mal wieder hervorkramen. Still digging!

(Kommentieren)