Page History

...

A playbook is a YAML file (could also be JSON or CSON), 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 (attributes can also be per-module), etc.

The location of the playbook file is antora_home.

...

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 at least one "family directory", such as pages or images (more below).

If we chose to organize the Ref Guide into modules we'd come up with a directory structure that looked like this (not final, just an early example - see below for family directory info):

Image Added

A special module named ROOT module is optional, but used for pages which have no formal module - like primary navigation pages, index.html, etc. Pages placed under ROOT do not have any module name in the path.

Family Directories

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

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?).

If we chose to organize the Ref Guide into modules we'd come up with a directory structure that looked like this (not final, just an early example):

Image Removed

A special module named ROOT is optional, but used for pages which have no formal module - like primary navigation pages, index.html, etc.did decide to now manage this manually, we could likely remove many pages which are navigational only.

Build Options

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

...

The version of each doc is built into the output directory structure: build / component / version / module / page, so something like Scaling Solr would be at this path: build/solr/9.0/deploy/scaling-solr.html.

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.

...

A very important thing to note here is the assumption is that the UI bundle is maintained in a completely separate repo and compiled into "releases" - this won't work for us...

Misc Notes

• Source highlighting only available through highlight.js
• STEM support needs to be added to the UI (it's not OOTB) because it relies on MathJax