Antora

Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).

Antora ist ein statischer Webseitengenerator für umfangreiche Software- und Systemdokumentationen auf Basis von AsciiDoc. Auf dem Entwicklungsrechner dient es dazu, strukturierte Dokumentationen aus einem oder mehreren Git-Repositories lokal zu einer durchsuchbaren Webseite zusammenzuführen und zu testen.

Installation

1. Paketlisten aktualisieren

Damit apt die aktuellen Paketdaten aus den Ubuntu-Paketquellen kennt.

sudo apt update

2. Node.js, npm und Git installieren

Antora basiert auf Node.js und setzt Git voraus, um Dokumentationsinhalte aus Repositories einzulesen.

sudo apt install -y nodejs npm git

Prüfen: Die installierte Version von Node.js wird angezeigt.

node -v

3. Antora CLI und Site Generator installieren

Installiert das Antora-Befehlszeilenwerkzeug (@antora/cli) und den Webseitengenerator (@antora/site-generator) global über den Node-Paketmanager npm.

sudo npm install -g @antora/cli @antora/site-generator

(Hinweis: Falls du Node.js über nvm im Benutzerverzeichnis verwendest, führe den Befehl ohne sudo aus).

Prüfen: Die installierten Versionsnummern von Antora werden angezeigt.

antora -v

Beispiel-Dokumentation erstellen und testen

4. Projektverzeichnis anlegen

Erstellt die von Antora erwartete Standard-Ordnerstruktur für ein Modul.

mkdir -p ~/antora-demo/docs/modules/ROOT/pages

5. Komponenten-Konfiguration anlegen

Definiert den Namen, die Versionsbezeichnung und den Titel der Dokumentationskomponente in docs/antora.yml.

nano ~/antora-demo/docs/antora.yml

Füge diesen Inhalt ein (im Terminal mit Strg+Umschalt+V), speichere mit Strg+O und Enter und beende nano mit Strg+X:

name: handbuch
title: Entwickler-Handbuch
version: '1.0'
start_page: index.adoc
nav:
  - modules/ROOT/nav.adoc

6. Navigationsdatei anlegen

Erstellt die Navigation für die linke Seitenleiste in docs/modules/ROOT/nav.adoc.

nano ~/antora-demo/docs/modules/ROOT/nav.adoc

Füge diesen Inhalt ein (im Terminal mit Strg+Umschalt+V), speichere mit Strg+O und Enter und beende nano mit Strg+X:

* xref:index.adoc[Startseite]

7. Startseite in AsciiDoc verfassen

Erstellt den eigentlichen Inhalt der Einstiegsseite in docs/modules/ROOT/pages/index.adoc.

nano ~/antora-demo/docs/modules/ROOT/pages/index.adoc

Füge diesen Inhalt ein (im Terminal mit Strg+Umschalt+V), speichere mit Strg+O und Enter und beende nano mit Strg+X:

= Willkommen im Entwickler-Handbuch

Dies ist eine lokale Dokumentationsseite, die mit Antora und AsciiDoc erstellt wurde.

== Erste Schritte

* Dokumentation im AsciiDoc-Format schreiben
* Änderungen mit Git versionieren
* Mit Antora zur fertigen Webseite bauen

8. Playbook-Konfiguration anlegen

Das Playbook antora-playbook.yml steuert den Bauprozess, bindet Inhaltsquellen ein und legt das Standard-Design fest.

nano ~/antora-demo/antora-playbook.yml

Füge diesen Inhalt ein (im Terminal mit Strg+Umschalt+V), speichere mit Strg+O und Enter und beende nano mit Strg+X:

site:
  title: Mein Dokumentationsportal
  start_page: handbuch::index.adoc
content:
  sources:
    - url: .
      branches: HEAD
      start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

9. Git-Repository initialisieren

Antora liest Dokumentationsstände standardmäßig aus Git-Zweigen (Branches).

git -C ~/antora-demo init

10. Dokumentationsdateien zum Git-Index hinzufügen

Nimmt alle erstellten Konfigurations- und Inhaltsdateien in die Versionsverwaltung auf.

git -C ~/antora-demo add .

11. Git-Commit erstellen

Erstellt den ersten Revisionsstand im Repository.

git -C ~/antora-demo commit -m "Initiale Dokumentation"

12. Dokumentationsseite bauen

Startet die Generierung der statischen HTML-Webseite über Antora. Die Ausgabe landet standardmäßig in build/site/.

antora ~/antora-demo/antora-playbook.yml

Prüfen: Die Startdatei build/site/index.html wurde erfolgreich erzeugt.

ls -lh ~/antora-demo/build/site/index.html

13. Dokumentation im Browser ansehen

Öffnet die generierte Dokumentationsseite direkt in deinem Standard-Webbrowser.

xdg-open ~/antora-demo/build/site/index.html

Deinstallieren

1. Antora-Pakete entfernen

Deinstalliert Antora CLI und den Site Generator aus npm.

sudo npm uninstall -g @antora/cli @antora/site-generator

2. Node.js und npm entfernen (optional)

Falls Node.js und npm über apt installiert wurden und nicht mehr benötigt werden.

sudo apt purge nodejs npm

3. Nicht mehr benötigte Abhängigkeiten entfernen

Entfernt verbliebene Hilfspakete aus dem System.

sudo apt autoremove

4. Testprojekt löschen (optional)

Entfernt das erstellte Testverzeichnis.

rm -rf ~/antora-demo

Prüfen: Der Befehl antora ist nicht mehr vorhanden.

antora -v

Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).

Open Knowledge (Freies Wissen): Alle Texte stehen unter der freien Lizenz Creative Commons Namensnennung – Weitergabe unter gleichen Bedingungen 4.0 International (CC BY-SA 4.0) und können frei gelesen, geteilt und weiterverarbeitet werden.