Composing navigation files in Antora using the include macro

This third post in the series of Antora posts quickly addresses a feature I only recently discovered. It will show you some techniques you can use to compose the navigation menu in a multi-repository, multi-module setup. This is especially interesting if you have content spread across repositories that you want to present hierarchically in the navigation tree.

<!–more–>

Using multiple navigation files

Let us start with the basics: How to combine navigation files?

Advanced customization for Antora - PlantUML support & custom UI

This post will cover some slightly advanced steps for building a multi-repository Asciidoc documentation using Antora. My previous post blog.anoff.io/2019-02-15-antora-first-steps covered basics of Antora and how to migrate existing AsciiDoc files. In this post I will go through the steps of including content from another repository, building a custom UI and adding plantUML support to the (automated, dockerized) build.

plantUML support

One of the most important things for me when it comes to software docs is the ability to show relationships and interactions using diagrams. As you might know from my previous posts I am a huge plantUML fan. So plantUML support is important both for rendering the Antora website and the local development.

Converting existing AsciiDoc into an Antora project

After 2 years of working with the arc42 template in markdown, I spent the last few weeks learning about an asciidoc based site generator named Antora. The main reason for the interest in AsciiDoc was the fact that the limited feature set in markdown often impairs you while writing down complex things. But I had one problem; most of our documentation is scattered across multiple repositories as we try to keep the docs as close to the code as possible. That is why this series will cover how to get a multi repository (software) architecture template up and running using Antora.