Dokumentation: Static-Site-Generator Antora 3.0 führt neue API für Plug-ins ein

Inhaltsverzeichnis

Antora ist ein Static-Site-Generator für Dokumentations-Websites, den das Entwicklerteam nach rund dreijähriger Arbeit seit dem letzten Major Release nun in Version 3.0.0 vorgelegt hat. Antora liest Dokumentationen im AsciiDoc-Format aus einem oder mehreren Git-Repositorys ein und erzeugt daraus HTML-Dateien, die anschließend ein beliebiger Webserver ausliefern kann. Über Navigation, Querverweise und Suche finden Nutzerinnen und Nutzer der Site die gewünschten Inhalte. Wird eine Dokumentation gegliedert nach Softwareversion benötigt, so erstellt Antora aus verschiedenen Branches und Tags der Git-Repositorys einzelne Sub-Sites. In der nun vorliegenden Version 3 finden sich einige neue Funktionen, die die Arbeit mit dem Tool erleichtern sollen.

Neues für Autoren

Das neue Release setzt auf Asciidoctor 2 auf, wodurch neben kleineren Optimierungen und Fehlerbehebungen auch neue Features wie ausklappbare Textbereiche in Antora möglich sind. Diese können beispielsweise in Tutorials Tipps oder eine Lösung zunächst verbergen.

Wie schon in Version 2 folgt Antora dem Ansatz "convention over configuration", sodass sich alle Beispieldateien einer Komponente in einem Verzeichnis "examples" befinden. In der Vergangenheit führte dies regelmäßig zu dem Problem, dass Quellcodebeispiele je nach Build-Tool in anderen Verzeichnissen lagen, von Antora dort nicht gefunden wurden und deshalb als Kopie im Verzeichnis "examples" abgelegt werden mussten. Version 3 verarbeitet nun auch Git-Symlinks, sodass im Verzeichnis "examples" ein Link auf Dateien oder Verzeichnisse abgelegt werden kann. So stehen die Dateien für Antora zur Verfügung und können von den Autoren direkt verwendet werden.

Resource IDs, mit denen Autoren Links zwischen Komponenten und Versionen herstellen können, wurden in Antora 2 nur für Querverweise auf andere Seiten verwendet. Ab Version 3 lassen sie sich durchgängig auch für Verweise auf Anhänge und für verlinkte Bilder verwenden. Bei Querverweisen auf Seiten muss jetzt immer die Dateiendung ".adoc" angegeben werden, nachdem Querverweise ohne Endung bereits in Version 2 veraltet (deprecated) waren.

Alle wichtigen Änderungen für Antora 3 lassen sich auch in der aktuellen Version des AsciiDoc-Plug-ins für IntelliJ nutzen. Es steht sowohl für kostenpflichtige als auch kostenlose JetBrains-IDEs wie IntelliJ IDEA in der Community-Edition bereit. Damit können Autoren Querverweise bereits in ihrer Entwicklungsumgebung beim Schreiben vervollständigen und automatisch überprüfen lassen.

Neues für die Site-Generierung

Für die neueste Dokumentationsversion und das neueste Pre-Release lassen sich nun feste URLs hinterlegen. Nutzerinnen und Nutzer können dadurch einfacher Lesezeichen setzen und Links zeigen stets auf die neueste Version. Außerdem kann eine Komponente der Dokumentation als ROOT-Komponente benannt werden, die dann als Einstieg in die Dokumentations-Site dient.

Version 2 konnte bereits mit Erweiterungen für Asciidoctor umgehen, mit denen etwa die HTML-Generierung der Inhalte erweitert werden konnte. Eine beliebte Erweiterung stellt Beispiele für verschiedene Programmiersprachen in verschiedenen Tabs dar. Mit Version 3 steht jetzt erstmalig eine API zur Verfügung, um den Site-Generator zu erweitern. Entwicklerinnen und Entwickler erhalten damit die Möglichkeit, die Struktur der Seite anzupassen und Inhalte zu steuern oder auszublenden.

Dank der neuen API ist auch die Integration von Suchmöglichkeiten einfacher geworden: Das in Version 2 beliebte Antora-Lunr-Plug-in für eine Client-seitige Volltextsuche wurde auf Antora 3 migriert und ist im Standard-UI verfügbar. Eine Integration einer SaaS-Lösung wie der Algolia-Suche ist ebenfalls möglich, jedoch weiterhin nicht im Standard-UI enthalten.

Neues für Continuous Integration und Continuous Delivery

Antora 3 unterstützt für die Generierung der Site die Node.js-Versionen 12 bis 16. Für das Hosting der generierten Site ist weiterhin jeder beliebige Webserver geeignet – Node.js ist dazu nicht erforderlich.

Mit dem Update auf Asciidoctor 2 enthalten Warnungen und Fehlermeldungen während des Builds etwa bei fehlenden geschlossenen Blöcken nun Quelldatei und Zeilennummer, was die Fehlersuche erleichtert. Ebenso gibt der Site-Generator nun Fehlermeldungen aus, wenn ein Querverweis ins Leere führt. Bei entsprechender Konfiguration lassen sich die Meldungen im JSON-Format ausgeben, sodass sie sich automatisiert weiterverarbeiten lassen. Auf Wunsch lässt sich zudem der Build abbrechen, wenn eine Warnung oder ein Fehler auftritt, sodass stets nur fehlerfreie Dokumentations-Sites publiziert werden.

Ebenfalls neu ist Support für HTTP-Proxies während der Site-Generierung, wie sie immer wieder für Unternehmens-Setups benötigt wird. Damit lassen sich auch Git-Repositorys einbinden, die nur über einen Proxy erreichbar sind.

Tipps für Installation und Upgrade

Für das Update auf Version 3 liefert das Kapitel "What’s New in Antora 3.0" einen detaillierten Überblick und eine Upgrade-Checkliste. Für die Änderungen, die sich aus dem Update auf Asciidoctor 2 ergeben, gibt es ebenfalls eine Übersicht. Um alle neuen Antora-Features zu nutzen, sollte allerdings das Antora-UI-Theme aktualisiert werden.

Wer sich für weitergehende Informationen zum Einstieg in Antora interessiert, findet im Kapitel "Install and Run Antora Quickstart" geeignete Hilfestellung.

Die Community rund um Antora trifft sich online im Zulip-Chat, in der Nutzerinnen und Nutzer Fragen stellen können, die dann von den Autoren oder anderen Nutzern beantwortet werden.

Ausblick in die Zukunft

In das neue Major Release haben es zwar Funktionen wie eine PDF-Generierung nicht geschafft, im Community-Chat finden sich jedoch erste Beispiele, wie sich das mit Extensions lösen lässt. Noch fehlt eine Übersicht über die verschiedenen Extensions, die in der Community entstanden sind. Diese wird aber hoffentlich bald in der Antora-Dokumentation ergänzt.

Der Site-Generator kommt bei einer steigenden Zahl von Open-Source-Projekten für die Dokumentation zum Einsatz – darunter Eclipse Che, Debezium, Apache Camel und Couchbase. Die Unterstützung von Git-Symlinks, durch die sich Beispielcode unabhängig vom Ablageort in mit Antora erstellter Dokumentation verwenden lässt, macht Version 3.0 für noch mehr Open-Source-Projekte interessant.

Der Trend zu Documentation as Code ist weiterhin ungebrochen und ermöglicht Entwicklerinnen und Entwicklern sowie Technical Writers, effizient mit erprobten Werkzeugen zusammenzuarbeiten und Versionen der Dokumentation gleichzeitig mit der Software bereitzustellen.

(map)