Antora & ARC42

Getting started with Antora by publishing the ARC42 template

Description

This repo contains an example of how to build a multi repository architecture documentation based around the arc42 template.

Repository overview:

1. anoff/antora-arc42 base component containing all system wide information, split up into several modules

Setup

First get some prerequisites

1. Get the arc42 template as a git submodule

2. install Antora

Then run the make command:

npm run dist

The generated code is now available in dist/

Notes on folder structure

Antora defines components and modules. A component can have multiple modules that are all located in a fixed directory structure adjacent to each other. Each component must have at least one module, the ROOT module. The playbook (overall config of the document) references one or more git repositories that contains a component with 1+ modules.

1. Antora expects all documentation to come in a component (there can be only one component in a build)

2. the playbook can define multiple content sources

   1. each content source needs to point to a root directory of a git repo (local or remote)

   2. you can use start_path in a playfile source to make the docs start relative to the git root

   3. the repo must have at least one commit

3. within this start path a module structure is expected

   1. the antora.yml file defines to position of a component

   2. there must be a modules/ROOT (uppercase) module present

   3. all .adoc files must reside in the modules/XYZ/pages directory

Antora-fying

The following steps are necessary to get the arc42 template into an antora compatible format:

1. move the adoc files into the antora component structure modules/ROOT/pages/

2. create antora.yml with the component definition

3. for having an overall file including all chapters the individual pages need to get the :page-partial: attribute and have a document title =

4. add all pages to the nav.adoc to create a navigation menu

5. custom styles in supplemental-ui/

Attribution

• the arc42 docs are MIT licensed

• supplemental-ui/ files are based on the Antora default UI MPL-2.0 licensed