antora-arc42

antora-arc42 copied to clipboard

= Antora & ARC42 Andreas Offenhaeuser https://blog.anoff.io

image::https://cloud.drone.io/api/badges/anoff/antora-arc42/status.svg[Drone build status, link=https://cloud.drone.io/anoff/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:

. link:https://github.com/anoff/antora-arc42[anoff/antora-arc42] base component containing all system wide information, split up into several modules

== Setup

First get some prerequisites

. Get the https://github.com/arc42/arc42-template[arc42 template] as a git submodule . https://docs.antora.org/antora/2.0/install/install-antora/[install Antora]

Then run the make command:

[source,bash]

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.

. 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_path in a https://docs.antora.org/antora/2.0/playbook/playbook-schema/#content-category[playfile source] to make the docs start relative to the git root .. the repo must have at least one commit . within this start path https://docs.antora.org/antora/2.0/modules/#module-overview[a module structure] is expected .. the https://docs.antora.org/antora/2.0/component-descriptor/#component-descriptor-requirements[antora.yml] file defines to position of a component .. there must be a modules/ROOT (uppercase) module present .. 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:

. move the adoc files into the antora component structure modules/ROOT/pages/ . create antora.yml with 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.adoc to create a navigation menu . custom styles in supplemental-ui/

== Attribution

• the arc42 docs are link:docs/modules/ROOT/LICENSE.txt[MIT licensed]
• supplemental-ui/ files are based on the link:https://gitlab.com/antora/antora-ui-default/blob/master/[Antora default UI] MPL-2.0 licensed