You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

Initial notes from trying to migrate Ref Guide from Jekyll to Antora

Antora website: https://antora.org/

Docs: https://docs.antora.org/antora/2.3/

Cassandra's branch: https://github.com/ctargett/solr/tree/antora-migration/solr/solr-ref-guide

Antora Design Goals

  • Designed FOR multi-version technical documentation
  • Git-based

Gradle Integration

Antora is a Ruby gem which requires Node.

A Gradle-Antora plugin is available: https://github.com/rwinch/antora-gradle-plugin

  • Basic functionality, not sure if more is needed?
  • Downloads Node and Antora and all dependencies
  • This creates a node_modules directory and a package-lock.json 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

Antora Concepts

Helpful: https://matthewsetter.com/antora/three-core-concepts/ (but out of date in terms of requirements)

Playbook

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.

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

A sitemap is automatically built.

The playbook can reference repos that are local or in GitHub or GitLab, etc. Specific branches can be built or use HEAD for whatever branch is checked out at that time.

Component

All projects have at least one component, defined by an antora.yml 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 must include a name, but can also include a version.

The idea is there would be one of these for each version, so a different one on each branch.

For the Ref Guide, we really only have 1 application (Solr) so this isn't an intuitive concept for us. However, if we published several different Guides for different applications (perhaps like "Core Solr", "Solr Operator", etc.) they could each be different components and have different versions, content locations, etc.

Module

A module is an organizational unit within a component. The primary top-level sections of the new Ref Guide could be considered modules.

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 looks something like this (not necessarily final):

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 did manage it manually, we could probably get rid of a lot of nav-only pages.).

If we did decide to now manage this manually, we could likely remove many pages which are navigational only.

Examples

Because Antora is able to simply include files by name only (and doesn't require relative or absolute paths), it has a limitation where any files outside the defined family directory structure can not be included at all.

This poses a problem for the Ref Guide, as we have several code examples (particularly for SolrJ, but also others) that pull from real tests which are not located in the Ref Guide directory tree.

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, so something like Scaling Solr would be at this path: build/solr/9.0/deployment-guide/scaling-solr.html.

By design, all  versions that have been configured (and which contain an antora.yml file) are built every time.

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.

With Antora, these assets are shared via the UI bundle that's used, which provides the overall theme for the entire documentation site.

A UI bundle is not merely directories of CSS and JS files, it's a .zip archive which has been compiled and generated with Gulp.

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", .zip archives that include the files. During build, the files are extracted and stored in a directory named with a single underscore ( as in ./_/). 

It occurs to me that we could store the UI part in a different directory under solr/solr-ref-guide , like "ref-guide-ui", but we would still need to check in a .zip, unless we decided to try to compile it on the fly before we built the rest of the Ref Guide.

As of version 3 of Antora (TBD, in the works), we will be able to refer to an expanded directory of UI files instead of a .zip.

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

Examples of Docs Built with Antora



  • No labels