Alexander Schwartz

For a project of a reasonable size, there's usually more than one source for the website that needs to be published. For several years, Antora is known as a site generator which pulls AsciiDoc content from multiple Git repositories at once. It publishes a static website where users find a navigation, online search and linked pages, with the option to group everything by component versions.

In 2022, Antora made the leap to open its publishing process to plugins: They allow pulling information dynamically during the build process and forward the content not only to a static HTML site, but other targets like PDF as well. This talk outlines what is possible today with these extensions, and how it can be extended for custom needs.

Several open-source software projects like Fedora, Eclipse Che, Camel, Debezium and Couchbase use Antora. For developers it is normal to develop software in collaboration using their IDE and a version control system like Git. The same type of collaboration is possible when all documentation is versioned in a markup-format like AsciiDoc.

Several examples will be from the Eclipse Che project which leveraged the Antora extensions in 2022. Additional examples show how to enrich the content with metadata and to use the information when building the site, and how to get feedback from the users of the site.

Other people: Fabrice Flore-Thebault

Zuhause Brot backen ohne Anstehen beim Bäcker. Aber wird das dann auch so schön knusprig? Die gute Nachricht: Wenn du etwas Zeit mitbringst und etwas planst, dann ja! Wenn du weniger Zeit hast, dann wird es genauso lecker, aber bekommt halt keine so schöne Kruste. Dieser Vortrag zeigt dir wie das gehen kann.

Antora erstellt Dokumentations-Websites für Nutzer. Gemäß des Docs-as-Code-Ansatzes werden alle Inhalte in AsciiDoc-Dateien in Git-Repositories versioniert und über CI/CD publiziert. Die Nutzer erhalten eine übersichtliche Darstellung der Dokumentation im Browser mit Navigationsleiste, Suche und Querverweisen. Sie können zwischen verschiedenen Versionen der Dokumentation hin- und herschalten, um die für sie passenden Informationen zu finden. Open-Source-Projekte wie Camel, Debezium und Couchbase nutzen diese Lösung bereits. Entwickler und Autoren der Dokumentation bearbeiten die Inhalte wie gewohnt in ihrer IDE und versionieren die Inhalte in der Versionsverwaltung mit Git. Alle Änderungen durchlaufen die bestehenden Code-Review- und Build-Prozesse des Projekts. Dieser Vortrag stellt die Grundlagen eines Antora-Setups vor und zeigt alle Schritte von einer Dokumentationsänderung in der IDE bis hin zur aktualisierten Dokumentations-Website mit Continuous Integration und Delivery.

The tool Antora creates documentation websites from AsciiDoc sources stored in Git repositories. Users can browse the generated website and select the version matching the software they use. Navigation outlines, search and cross-references between pages allow users to find answers to their questions. Several open-source software projects like Camel, Debezium and Couchbase use this solution.

For developers it is normal to develop software in collaboration using their IDE and a version control system like Git. The same type of collaboration is possible when all documentation is versioned in a markup-format like AsciiDoc.

This talk presents the basics of an Antora setup and walks through all the steps from editing content in the IDE to updating the documentation site using continuous integration and delivery.

Links:

• https://antora.org/

Sample Documentation created with Antora:

• https://docs.antora.org/
• https://debezium.io/documentation/reference/index.html
• https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/index.html