Getting started with Antora by publishing the ARC42 template
This repo contains an example of how to build a multi repository architecture documentation based around the arc42 template.
Repository overview:
-
anoff/antora-arc42 base component containing all system wide information, split up into several modules
First get some prerequisites
-
Get the arc42 template as a git submodule
Then run the make command:
npm run distThe generated code is now available in dist/
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.
-
Antora expects all documentation to come in a component (there can be only one component in a build)
-
the playbook can define multiple content sources
-
each content source needs to point to a root directory of a git repo (local or remote)
-
you can use
start_pathin a playfile source to make the docs start relative to the git root -
the repo must have at least one commit
-
-
within this start path a module structure is expected
-
the antora.yml file defines to position of a component
-
there must be a
modules/ROOT(uppercase) module present -
all
.adocfiles must reside in themodules/XYZ/pagesdirectory
-
The following steps are necessary to get the arc42 template into an antora compatible format:
-
move the adoc files into the antora component structure
modules/ROOT/pages/ -
create
antora.ymlwith the component definition -
for having an overall file including all chapters the individual pages need to get the
:page-partial:attribute and have a document title= -
add all pages to the
nav.adocto create a navigation menu -
custom styles in
supplemental-ui/
-
the arc42 docs are MIT licensed
-
supplemental-ui/files are based on the Antora default UI MPL-2.0 licensed