Page History

...

• Basic functionality, not sure if more is needed?
• Downloads Node and Antora and all dependencies
• This creates a node_modules  directory  directory and a package-lock.json  file  file - do these need to be committed, or aded to .gitignore ?
• There is an open issue for Antora to make it "official" (which states the plugin still needs hardening): https://gitlab.com/antora/antora/-/issues/632

...

A playbook is a YAML file (could also be JSON or CSON) which , usually playbook.yml, which defines global attributes of the documentation site. Examples: site title, URL, starting page, sources of content (Git repo & branches), overall UI theme, output directories. Asciidoc attribute settings, etc.

The location of the playbook file is antora_home .

By default build output is put in a build  directory in antora_home, organized under component, version, module directories.

A sitemap is automatically built.

Component

All projects have at least one component, defined by an antora.yml  file  file stored at the "content root". Its presence indicates to Antora that it should find content files in this location (organized under a modules  directory). The antora.yml  file  file must include a name, but can also include a version.

...

There must be a modules directory where content is organized, and at least one directory under that for a named module. Each named module must include a at least one "family directory", such as pages or images.

Asciidoc files are always stored in the pages  family directory. Images should be in the images  family directory.

One interesting thing about the family directory structure is that paths do not need to be included when referencing an item in another family directory. For example, to include an image that's in the images  family, one would only need to reference the module & filename, as in image::module:filename.png[], and not worry about determining the full path.

Navigation files can be located anywhere (defined in the playbook), but a custom is to make a nav file for each module (how could we automate this? Maybe we don't...how often do we really move stuff?)

...

A special module named ROOT is optional, but used for pages which have no formal module - like primary navigation pages, index.html, etc.

Build Options

By default build output is in antora_home, which is the location of the playbook.yml  file.

Antora is designed for documentation sites which cover multiple versions.

The version of each doc is built into the output directory structure: build / component / version / module / page

Recursively cleaning the build area is an option that can be added to the playbook so it doesn't need to be defined at Gradle runtime.

UI Bundle

Today with Jekyll we create each version of the Ref Guide with all pages, and in the directory structure that's created, each version has its own CSS directory, font directory, javascript directory, etc.

...