Antora in einem Satz

Antora ist eine modulare Dokumentations-Pipeline, die AsciiDoc-Inhalte aus einem oder mehreren Git-Repositories sammelt, diese in Komponenten/Versionen organisiert und eine mehrseitige Website mit einem thematischen UI rendert.

Warum Teams es wählen

  • Von Tag eins für Multi-Repo-Dokumentation und Versionierung gebaut.
  • Verwendet AsciiDoc, das sich für große, strukturierte Dokumentation und Wiederverwendung über Includes/Partials eignet.
  • Saubere Trennung von Inhalt (in Git) und Website-UI (Theme-Bundle).

Wo adoc Studio hilft: Schneller schreiben mit AsciiDoc-fokussierter UX, Inhalte wiederverwendbar halten und HTML/PDF mit einem CSS stylen (siehe Einmal benutzerdefiniertes CSS erstellen, Templates & Stylesheets).

Antora Cheat Sheet

Setup
npx antora -v
CLI- und Generator-Version ausgeben. Installation pruefen.
npx antora --attribute key=value antora-playbook.yml
AsciiDoc-Attribute zur Build-Zeit setzen. Flag wiederholen fuer mehrere.
Build
npx antora antora-playbook.yml
Standard-Build. Generiert die Website im aktuellen Verzeichnis.
npx antora --fetch antora-playbook.yml
Updates aus Remote-Content-/UI-Repos abrufen, dann bauen.
npx antora --clean antora-playbook.yml
Loescht vorherige Ausgabe zuerst. Nach Reorganisation oder Theme-Wechsel verwenden.
npx antora --fetch --clean antora-playbook.yml
Neueste Quellen abrufen und sauber von Grund auf bauen. Typisch fuer CI-Pipelines.
UI & Inhalt anpassen
npx antora --ui-bundle-url ./ui-bundle.zip antora-playbook.yml
Lokales UI-Bundle testen, ohne es ins Remote-Repository zu pushen.
npx antora --start-page component:module:page.adoc antora-playbook.yml
Startseite der Website fuer lokale Vorschau temporaer ueberschreiben.
Ausgabe & Deployment
npx antora --to-dir public antora-playbook.yml
Ausgabe in ein benutzerdefiniertes Verzeichnis schreiben (z.B. public/ fuer Netlify/Vercel).
npx antora --html-url-extension-style indexify antora-playbook.yml
Saubere, index-basierte URLs statt .html-Dateiendungen verwenden.
npx antora --redirect-facility netlify antora-playbook.yml
Redirect-Regeln fuer Ihre Hosting-Plattform generieren (nginx, netlify, gitlab, httpd, static).
npx antora --to-dir public --clean antora-playbook.yml
Clean-Build direkt ins Deploy-Verzeichnis. Bereit zum Ausliefern.
Debugging
npx antora --log-level info antora-playbook.yml
Log-Detailgrad erhoehen. Stufen: fatal, error, warn, info, debug.
npx antora --stacktrace antora-playbook.yml
Vollstaendigen Stacktrace bei Fehlern anzeigen. Hilfreich bei Extension-/UI-Problemen.
npx antora --log-level debug --stacktrace antora-playbook.yml
Maximale Debug-Ausgabe. Beide Flags kombinieren bei Build-Problemen.
npx antora --ui-bundle-url ./ui.zip antora-playbook.yml
Lokales UI-Bundle testen, um Theme- von Inhaltsproblemen zu trennen.

Schritt-für-Schritt: Installieren und ausführen Ihrer ersten Antora-Website

Verwenden Sie eine lokale Installation + npx, definieren Sie ein minimales Playbook, fügen Sie eine Komponente hinzu, generieren Sie.

1. Voraussetzungen

Node.js (LTS)
Git erreichbar von Ihrer Shell

2. Erstellen Sie ein Playbook-Projekt und installieren Sie Antora lokal (empfohlen)

mkdir docs-site && cd docs-site
node -e "fs.writeFileSync('package.json','{}')"
npm i -D -E @antora/cli@3 @antora/site-generator@3
npx antora -v

3. Fügen Sie eine minimale antora-playbook.yml hinzu

site:
  title: "Meine Dokumentation"
  url: https://example.com/docs
content:
  sources:
    - url: ./
      branches: HEAD
      start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/main/raw/build/ui-bundle.zip?job=build
  supplemental_files: ./supplemental-ui
output:
  dir: ./build/site

4. Erstellen Sie Ihre erste Komponente

docs/                     # Content-Source-Root
  antora.yml              # Komponentenversions-Deskriptor
  modules/
    ROOT/
      pages/
        index.adoc

antora.yml:

name: mein-produkt
version: 1.0
title: Mein Produkt
nav:
  - modules/ROOT/nav.adoc

5. Verfassen Sie eine Seite (docs/modules/ROOT/pages/index.adoc)

= Willkommen in der Dokumentation meines Produkts
:page-nav_order: 1

Dies ist Ihre erste Antora-Seite. Siehe <<erste-schritte>> um fortzufahren.

Falls Sie neu bei AsciiDoc-Includes/Wiederverwendung sind, behalten Sie dies griffbereit: Include-Direktive Tipps.

6. Generieren und Vorschau anzeigen

npx antora antora-playbook.yml
# öffne build/site/index.html

Die einfachere Alternative: adoc Studios statischer Webseiten-Generator

Wenn Antoras Multi-Repo-Orchestrierung mehr ist, als Sie brauchen, bietet adoc Studio einen radikal einfacheren Weg von AsciiDoc zur Webseite.

Statt Playbooks, Komponentendeskriptoren, Nav-Dateien und einer Node.js-Build-Pipeline zu verwalten, arbeiten Sie direkt in Ihrem AsciiDoc-Dokument. Die Sektionsstruktur Ihres Dokuments wird zur Website-Navigation – kein nav.adoc, kein antora.yml, keine Konfigurationsdateien.

Was komplett entfällt:

  • Kein package.json, npm install oder npx antora
  • Kein Playbook-YAML, keine Komponentendeskriptoren
  • Keine separaten nav.adoc-Dateien, die synchron gehalten werden müssen
  • Keine Build-Pipeline oder CI-Konfiguration für die Seite selbst

Was Sie stattdessen bekommen:

  • Export mit einem Klick – Export klicken, Ordner wählen, fertig. Alle HTML-Dateien, Stile und die Navigation werden automatisch generiert.
  • Sektionsstruktur = Sitemap – Ihre Dokumentüberschriften definieren Seiten und Navigation. Wählen Sie, wie Sektionen erscheinen: Kopfzeile, Seitenleiste, Satellitennavigation oder beliebige Kombination.
  • Eingebaute Mehrsprachigkeit – wenn Ihr Projekt Übersetzungen enthält, baut adoc Studio automatisch eine mehrsprachige Seite mit Sprachumschalter, sprachspezifischer Navigation und lokalisiertem Suchindex.
  • Einheitliches Styling – dasselbe CSS steuert sowohl Ihre HTML-Webseite als auch PDF-Exporte. Einmal gestalten, überall nutzen.

adoc Studio liefert dieselben Ergebnisse – versionierte, navigierbare, mehrsprachige Dokumentations-Webseiten – ohne den Toolchain-Overhead. Keine Playbooks, keine Build-Pipeline, keine manuelle Konfiguration. Nur Ihr AsciiDoc-Inhalt und ein einziger Klick. Mehr über adoc Studios Statischen Webseiten-Generator erfahren.

Strukturieren Sie Ihren Inhalt auf die Antora-Art

  • Komponenten repräsentieren Produkte/Bereiche.
  • Versionen erfassen Releases oder Tracks.
  • Module teilen Inhalt nach Zweck auf (z.B. ROOT, user, admin).
  • Seiten, Partials, Bilder, Anhänge leben unter Modulen.

Antora kann eine Komponente aus mehreren Repositories zusammenfügen—verwenden Sie eine primäre antora.yml (mit nav, title) und minimale Deskriptoren in Satelliten-Repositories.

Playbook-Content-Sources

content:
  sources:
    - url: https://git.example.com/my/product.git
      branches: [ main, v1.* ]
      start_path: docs
    - url: https://git.example.com/my/shared-docs.git
      start_path: docs

Versionierung, die Sie später nicht beißt

  • Behalten Sie semantische Versionen oder benannte Tracks bei (1.0, 2.0, next).
  • Kontrollieren Sie, wie Benutzer Versionen mit display_version und Routing sehen.
  • Sie können Versionen aus Git-Refs ableiten oder in antora.yml setzen.

Branching-Strategie

  • Verfassen Sie auf main (Version next).
  • Erstellen Sie einen Release-Branch (release/2.1) und setzen Sie dort version: 2.1.
  • Portieren Sie Fixes per Cherry-Pick zurück.

UI, Navigation und Branding

Antora liefert eine Standard-UI; Sie können Ihr eigenes UI-Bundle oder ergänzende Dateien (Logos, JS, CSS, Partials) einstecken.

  • Behalten Sie die Navigation an einem Ort (nav.adoc), um Drift zu vermeiden.
  • Fügen Sie Analytics, Cookie-Banner oder Dark Mode über ergänzende Handlebars/JS in Ihrem UI-Projekt hinzu.
  • Wenn Sie einen einfacheren Pfad für PDF/HTML-Styling ohne eine benutzerdefinierte UI-Pipeline möchten, stylen Sie einmal in adoc Studio und exportieren Sie HTML & PDF konsistent: Design mit CSS, AsciiDoc zu PDF exportieren, ISO-bereite Admonitions.

CI/CD und Hosting

  • Antora erzeugt eine statische Website, die Sie überall hosten können (S3, GitHub/GitLab Pages, Netlify, Ihr Server).
  • In CI: npm ci && npx antora antora-playbook.yml && rsync zu Ihrem Host.
  • Erstellen Sie bei Merges in main, veröffentlichen Sie von Tags für Releases.

Antora vs. andere Tools (wählen Sie mit offenen Augen)

Antora vs. MkDocs

  • MkDocs ist Markdown-first, schnell und hat ein florierendes Plugin/Theme-Ökosystem (z.B. Material for MkDocs). Großartig für kleine bis mittlere Dokumentation und Python-zentrierte Teams.
  • Antora glänzt bei Multi-Repo + versionierten AsciiDoc-Websites und komponentenübergreifender Wiederverwendung. Wenn Sie Komponenten/Versionen im großen Maßstab benötigen, passt Antora besser.

Antora vs. Docusaurus

  • Docusaurus ist React/MDX-basiert, großartig für interaktive Dokumentation, Blogs und Marketing-Seiten; es bietet erstklassige Versionierungs-/i18n-Plugins.
  • Antora ist eine mehrseitige statische Website, die sich auf Dokumentationsstruktur und AsciiDoc-Tiefe konzentriert.

Antora vs. Sphinx

  • Sphinx (reStructuredText/MyST) ist mächtig für Python-Ökosysteme und API-Dokumentation, mit vielen Buildern und Erweiterungen.
  • Antoras Stärke ist die Komponenten-/Versionsorchestration über Repositories hinweg mit AsciiDoc.

Wenn Ihr Inhalt bereits in AsciiDoc ist oder Sie modulare, versionierte, Multi-Repo-Dokumentation benötigen, wählen Sie Antora. Wenn Sie MDX-Widgets oder eine React-SPA benötigen, ziehen Sie Docusaurus in Betracht. Wenn Ihr Stack Python/API-lastig ist, machen Sphinx/MkDocs Sinn.

Antora mit Übersetzungen verwenden (mehrsprachig)

Es gibt keinen schlüsselfertigen i18n-Umschalter; Sie implementieren Sprachen über Version-als-Sprache (z.B. version: en, version: de) plus UI-Anpassungen, oder führen separate Playbooks/Websites aus.

Muster A — “Version-als-Sprache”

  • Erstellen Sie parallele Komponentenversionen, die nach Sprachen benannt sind: version: en, version: de.
  • Duplizieren Sie die Struktur; übersetzen Sie Seiten unter jeder Locale.
  • Passen Sie die UI an, um <html lang> zu setzen und einen Sprachwechsler hinzuzufügen.

Muster B — Separate Websites / Playbooks

  • Pflegen Sie ein Playbook pro Sprache (docs-site-en, docs-site-de), jedes erstellt zu seiner eigenen Ausgabe/URL.
  • Fügen Sie einen Sprachwechsler im Header hinzu, der zwischen Websites verweist.

Vorbehalte & Tipps

  • Halten Sie Ressourcen-IDs ausgerichtet, damit Cross-Links über Locales hinweg deterministisch sind.
  • Entscheiden Sie, wie Sie mit Fallbacks umgehen: Wenn eine Seite nicht übersetzt ist, verlinken Sie auf Englisch.
  • Automatisieren Sie String-Abdeckung in CI (einfache Zählungen nach Verzeichnis).
  • Wenn Sie “batterieinklusive” i18n-Routing wollen, bieten Docusaurus oder Site-Frameworks wie Astro das—aber Sie tauschen Antoras Komponenten-/Versionsmodell ein.

Wo adoc Studio hilft: Source-AsciiDoc sauber verwalten, Includes und Partials DRY über Sprachen hinweg halten und konsistente Überschriften/Terminologie durchsetzen.

Team-Best-Practices, die skalieren

  • Entscheiden Sie Ihre Koordinaten früh. Komponentennamen/Versionen werden zu URLs und Cross-Refs. Schreiben Sie sie auf.
  • Eine Quelle der Wahrheit für Navigation. Behalten Sie nav.adoc im primären Repository; andere Repositories haben minimale antora.yml.
  • Automatisieren Sie Builds. CI führt npx antora … bei Merges aus; veröffentlichen Sie auf einem statischen Host.
  • Einmal linten und stylen. adoc Studio lässt Sie schreiben, linten und ein CSS für HTML/PDF anwenden, damit Ihre Antora-Ausgabe von Tag eins an markenkonform aussieht.
  • Wiederverwendbare Inhalte. Bevorzugen Sie include::[] und Partials für wiederholte Abschnitte (Include-Direktive-Guide).
  • Halten Sie das Lernen leichtgewichtig. Neue Autoren steigen schneller ein mit adoc Coach und einem kurzen Produkt-Tutorial.

Fehlerbehebung & häufige Fallstricke

  • “Es wurde erstellt, aber die Seite fehlt.” Prüfen Sie Repository/Branch/Start-Pfad und dass ein Content-Source-Root mit antora.yml existiert.
  • “Versionen sind in einer seltsamen Reihenfolge.” Setzen Sie title/display_version konsistent in antora.yml.
  • “Globale Installation Berechtigungsfehler.” Bevorzugen Sie lokale Installation + npx (funktioniert über Maschinen/CI hinweg).
  • “Wie kann ich ein benutzerdefiniertes Theme in der Vorschau anzeigen?” Erstellen/servieren Sie das UI-Projekt und zeigen Sie die ui.bundle.url Ihres Playbooks auf die erstellte Zip (oder verwenden Sie --ui-bundle-url lokal).

Schnellreferenz: Zum Kopieren und Einfügen bereit

Minimale antora.yml

name: mein-produkt
version: 1.0
title: Mein Produkt
nav:
  - modules/ROOT/nav.adoc

Minimales Playbook mit einer lokalen Quelle

site:
  title: "Meine Dokumentation"
content:
  sources:
    - url: ./
      branches: HEAD
      start_path: docs
output:
  dir: ./build/site

Generieren

npx antora antora-playbook.yml

Mini-Debug-Checkliste

Seite nach Build fehlt?

Bestätigen Sie Repository/Branch/Start-Pfad und dass antora.yml neben modules/ liegt.

Theme-Änderungen nicht sichtbar?

Verwenden Sie ui.bundle.snapshot: true oder führen Sie mit --ui-bundle-url aus, das auf Ihr lokales Bundle zeigt.

Seltsame URLs?

Versuchen Sie --html-url-extension-style indexify oder setzen Sie es unter urls im Playbook.

Versions-Anzeige/Routing-Eigenarten?

Prüfen Sie display_version und prerelease.

Keine offensichtliche Fehlerausgabe?

Führen Sie erneut mit --log-level debug --stacktrace aus.

Fazit: Wann Antora das richtige Tool ist

Wählen Sie Antora, wenn Sie ernsthafte Struktur benötigen—Komponenten, Versionen, Multi-Repo-Inhalte und Team-Workflows, bei denen sich Dokumentation wie Code verhält. Kombinieren Sie es mit einer disziplinierten AsciiDoc-Praxis und einem kleinen CI-Job und Sie haben einen widerstandsfähigen Dokumentations-Stack, der mit Ihrem Produkt wächst.

Wenn Sie einen schnelleren Start auf der Verfassungs-/Styling-Seite möchten, paaren Sie Antora mit adoc Studio: Schreiben Sie in AsciiDoc, verwenden Sie Inhalte wieder und stylen Sie HTML/PDF einmal. Siehe: Export zu PDF, AsciiDoc Guide, und unser kurzes Produkt-Tutorial.