Antora Leitfaden: Alles, was Sie wissen müssen (2025)

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

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

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

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.

adoc Studio für Mac, iPad & iPhone

Technische Dokumentation
in AsciiDoc erstellen

14 Tage gratis testen →

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.