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

Compare with Current View Page History

« Previous Version 2 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/

Antora Design Goals

  • Designed FOR technical documentation
  • Versioned
  • 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) 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.

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 of the software, 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 a "family directory", such as pages or images .

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):

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

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.




  • No labels