As part of the Tool the Docs Devroom at FOSDEM, I presented the basics of an Antora setup.
A big thank you to the organizers at FOSDEM for making this online edition possible. Also to Chris Ward, Mark Meyer, Kristof Van Tomme and Katalin Fogas for organizing the DevRoom!
Abstract
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 kind 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
Sample Documentation created with Antora:
- Antora’s own documentation site
- https://docs.antora.org/
- Debezium Project
- https://debezium.io/documentation/reference/index.html
- IntelliJ AsciiDoc Plugin
- https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/index.html
Recorded video and slides
For FOSDEM 2021 all talks in the DevRoom were pre-recorded. After the talk there was a 10 minutes live Q&A.
This is the first video where I added captions, please let me know if they are useful.
Once the recoding of the Q&A session is available online, I’ll add it to this page as well.