Asciidoc mit Docker bauen

Sie müssen nicht für jedes Output-Format des Asciidoctors ein Extra-Tool installieren. Sie brauchen eigentlich nur ein Docker-Image nutzen, egal welchen Output Sie aus Ihren adoc-Dateien generieren wollen.

Diese Quelle ermöglichte mir den Artikel: Asciidoctor Docker Container

Tip	Voraussetzung Sie haben Docker installiert.

Kontext

Da ich im Zusammenhang mit DITA XML bereits Docker installiert hatte, wußte ich, dass es für adoc-Dateien einen ähnlichen Weg des Bauens über ein Docker-Image geben müßte.

Das gibt es. Und das Schönes ist, dass der Build via Docker verschiedene Ausgabeformate abdeckt: HTML, PDF, EPUB3 und Confluence uvm.

Anleitung

Docker im Terminal starten: sudo systemctl start docker
Buildbefehl eingeben + ENTER
Im Output-Ordner das Ergebnis bestaunen

Buildbefehl anpassen

In der readme-Datei des Projekts heißt es:

Build-Befehl in der Dokumentation

docker run -it \
  -u $(id -u):$(id -g) \
  -v <your directory>:/documents/ asciidoctor/docker-asciidoctor

Diese Beispiel-Syntax gilt es anzupassen. Den Part -u $(id -u):$(id -g) sollten Sie in Ihrem Build-Befehl übernehmen. Er sorgt dafür, dass das Output-Verzeichnis editierbar ist. So können Sie z.B. einen Image-Ordner einfügen, wenn nötig.

Mein angepaßter Build-Befehl

docker run --rm \
  -u $(id -u):$(id -g) \
  -v ~/sync/asciidoc:/documents asciidoctor/docker-asciidoctor \ (1)
  asciidoctor -v -D /documents/homepage/output/ /documents/homepage/'**/*.adoc' (2)

Mein lokaler Ordner sync/asciidoc wird mit dem Ordner documents des Containers verbunden (mounted) und das Image asciidoctor/docker-asciidoctor wird benutzt.
Es wird HTML-Output erzeugt in meinem lokalen Ordner sync/asciidoc/homepage/output, denn documents ist ja gleichbedeutend mit sync/asciidoc. Da ich nicht nur eine, sondern mehrere adoc-Dateien hatte, musste ich bei der Quelldatei-Angabe am Ende mit der Wildcard-Syntax arbeiten.

Fazit

Ich habe mir die Installation sämtlicher Asciidoctor-Build-Tools erspart und brauche mich nicht um Updates zu kümmern. Einfach Docker starten, Buildbefehl eingeben und mehrere Output-Formate erhalten.