javaThis project demonstrate how to build Antora docs from Maven. Antora is a Node.js utility so we can use the Front End Plugin and some npm configuration.

Building the Site

To see it working, clone this repository and then on the command line:

$ ./mvnw package antora

Then visit the generated site at target/antora/site/index.html.

You can rebuild using Maven ("antora" goal) or using the npm utility script and the "build" script configured in package.json:

$ ./npm run build

> docs@1.0.0 build /home/dsyer/dev/spring/docs-test/docs
> antora --stacktrace generate --url https://cloud.spring.io antora-playbook.yml

Site generation complete!
View the site by visiting file:///home/.../build/site in a browser.

What’s in the Box?

The build is configured in the antora-playbook.yml. It starts like this:

site:
  title: Spring Demo
  start_page: spring-demo::index.adoc

The start_page is optional, but useful - if you don’t have one the site has no "home page". The site home page is just a redirect to the home page of one of the components ("spring-cloud").

The components are defined in a directory with a conventional layout. It has to contain antora.yml and a modules directory. An example can be seen in the "main" branch of this project. Here is antora.yml:

name: spring-demo
title: Spring Demo
version: ~
display-version: x.x.y

The modules directory contains "packages", one of which is optionally "ROOT". The ROOT package goes in the "home" of the component. A package can have Asciidoctor sources in its "pages" directory. So this is a minimal component:

antora.yml
modules/
  ROOT/
    pages/
      index.adoc

Old Material

(No longer relevant - the "old" branch is now different content)

The repository has 4 branches, and each one is an Antora "component". Two of the branches (main and old) are displayed as versions "x.x.y" and "y.y.y" of the same component. The other branches are different components. For a "real" project it is likely that these would pull in content from other repositories. All 4 branches are pulled into the antora-playbook.yml in one section:

content:
  sources:
    - url: .
      branches: [main, old, function, stream]

The "ui" is what controls the page layout and user interactions, like version pickers, etc. This example uses a ui developed for https://spring.io:

ui:
  bundle:
    url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip
    snapshot: true

Navigation

Each component has a nav.adoc for navigation - it’s a list of cross references and links that show up in the nav section (on the left in the Spring UI layout). It can be composed from multiple modules, but all of them have to be in the same component. For the "main" branch we have in antora.yml:

nav:
- modules/nav.adoc

and in modules/nav.doc:

* [Spring Cloud](spring-cloud::index.adoc)
** [Spring Cloud Function](spring-cloud-function::index.adoc)
** [Spring Cloud Stream](spring-cloud-stream::index.adoc)

There is also a default navigation with all versions of all components which shows up at the bottom of the nav pane in the Spring UI. Custom navigations give the author the chance to control which versions link to which other components.

The demo site has been laid out as an umbrella - "spring-cloud" is a collection of other components (projects) with specified versions. Each component has its own internal navigation, but the UI always has breadcrumbs within the current component and a link back to the top level (the "home" icon).