Antora ist ein Static Site Generator für Technische Redakteure. Der Content wird in Asciidoc geschrieben und kann sich in verschiedenen Git-Repositorys befinden. Zum Testen sollen sich die Quelldateien jedoch lokal auf dem Rechner befinden.
Kontext
Antora ist in erster Linie dazu gedacht, Dokumentationen aus mehreren Repositorys unter einer Oberfläche zusammenzuführen (docs as code). Bevor ein Redakteur jedoch via Merge Request in eine übergreifende Gesamtdokumentation eincheckt, möchte er sichergehen und seine Texte testen. Antora sollte dazu auch lokal lauffähig sein.
1) Verzeichnisstruktur einrichten
Es gibt drei Quell-Bestandteile einer Antora-Dokumentation:
Die Playbook-Datei (z.B.
antora-test-playbook.yml)Die Components (Die Inhalte-Repositorys bzw. Inhalte-Verzeichnisse)
Das UI-Theme (
ui-bundle.zip)
Diese 3 Bestandteile werden lokal in ein Verzeichnis kopiert. Ich möchte es das Antora-Arbeitsverzeichnis nennen. Im Beispiel existieren im Antora-Arbeitsverzeichnis zwei Components sowie die Playbook-Datei und das UI-Theme.
com.petersell.example
├── com.petersell.example.api
├── com.petersell.example.impl
└── com.petersell.example.doc
├── modules
└── antora.yml
com.petersell.anotherexample
└── com.petersell.anotherexample.doc
├── modules
└── antora.yml
antora-test-playbook.yml
ui-bundle.zip2) Playbook-Datei erstellen
Da ich neben den o.g. zwei lokalen Components-Verzeichnisse noch ein Beispielprojekt von Antora integrieren möchte, dass sich in einem Git-Repository befindet, musste ich meine Playbook-Datei antora-test-playbook.yml folgendermaßen gestalten.
site:
title: Antora Test Site <!--(1)-->
url: http://localhost
start_page: Startseite::index.adoc <!--(2)-->
content:
sources:
- url: . <!--(3)-->
branches: HEAD <!--(4)-->
start_path: com.petersell.example/com.petersell.example.doc <!--(5)-->
- url: https://gitlab.com/antora/demo/demo-component-b.git <!--(6)-->
branches: [v2.0, v1.0]
start_path: docs
- url: . <!--(7)-->
branches: HEAD
start_path: com.petersell.anotherexample/com.petersell.anotherexample.doc
ui:
bundle:
#
url: ./ui-bundle.zip <!--(8)-->Der Titel erscheint im Output links oben in der Kopf-Navigationsleiste.
Der linke Teil (vor den zweifachen Doppelpunkten) gibt den Namen der Startseite wider. Sie finden diesen in der
antora.ymldes jeweiligen Ordners hinter dem Attributname. Der rechte Teil gibt den Pfad inklusive Dateiname der Startseiten-Datei aus. Hier ist die Startseite im ROOT-Verzeichnis.Ist die Component lokal auf Ihrem Rechner, setzen Sie den Punkt.
Ist die Component lokal auf Ihrem Rechner, schreiben Sie
HEAD.Der Pfad zum jeweiligen Component-Verzeichnis inklusive dem Verzeichnisnamen, hier
com.petersell.example.docDie Syntax für eine Component in einem Git-Repository. Hier ist es eine Beispieldokumentation von Antora.
Die zweite lokale Component. Gehen Sie analog der ersten Component vor.
Das lokale UI-Theme. Dies könnte auch die URL zu einem Git-Repository inklusive der ZIP-Datei sein.
3) Antora-Output generieren
Eröffnen Sie im Antora-Arbeitsverzeichnis eine PowerShell und setzen Sie folgenden Build-Befehl ab.
antora antora-test-playbook.yml --stacktrace
Höchstwahrscheinlich werden Sie eine Fehlermeldung erhalten.
Error: Local content source must be a git repository: C:\Users\Andreas\Dropbox\antora (resolved from url: .)
In diesem Fall öffnen Sie im Antora-Arbeitsverzeichnis ein Git-Bash-Fenster und geben die folgende Befehle auf einmal ein.
git init . touch .gitignore git add .gitignore git commit -m 'initialize repository'
Eröffnen Sie im Antora-Arbeitsverzeichnis eine PowerShell und setzen nochmals den Build-Befehl ab.
antora antora-test-playbook.yml --stacktrace
Der Befehl clont das externe Repository des Antora-Beispielprojekts. Im Ergebnis entsteht innerhalb des Antora-Arbeitsverzeichnisses ein neuer Ordner build mit dem HTML-Output der drei Components.
