Antora-Output aus lokalen Quellen generieren

Andreas Petersell am 10.06.2020

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:

  1. Die Playbook-Datei (z.B. antora-test-playbook.yml)

  2. Die Components (Die Inhalte-Repositorys bzw. Inhalte-Verzeichnisse)

  3. 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.zip

2) 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)
  1. Der Titel erscheint im Output links oben in der Kopf-Navigationsleiste.

  2. Der linke Teil (vor den zweifachen Doppelpunkten) gibt den Namen der Startseite wider. Sie finden diesen in der antora.yml des jeweiligen Ordners hinter dem Attribut name. Der rechte Teil gibt den Pfad inklusive Dateiname der Startseiten-Datei aus. Hier ist die Startseite im ROOT-Verzeichnis.

  3. Ist die Component lokal auf Ihrem Rechner, setzen Sie den Punkt.

  4. Ist die Component lokal auf Ihrem Rechner, schreiben Sie HEAD.

  5. Der Pfad zum jeweiligen Component-Verzeichnis inklusive dem Verzeichnisnamen, hier com.petersell.example.doc

  6. Die Syntax für eine Component in einem Git-Repository. Hier ist es eine Beispieldokumentation von Antora.

  7. Die zweite lokale Component. Gehen Sie analog der ersten Component vor.

  8. 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-Buildbefehl
antora antora-test-playbook.yml --stacktrace

Höchstwahrscheinlich werden Sie eine Fehlermeldung erhalten.

Fehlermeldung
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-Bash-Fenster im Arbeitsverzeichnis
Git-Befehle kopieren
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.

Ausführen in der PowerShell
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.