wishlist: Antora-ize docs

Bug #1848524 reported by Ted Peterson on 2019-10-17
This bug affects 2 people
Affects Status Importance Assigned to Milestone

Bug Description

As the Evergreen ILS docs are already in a Git repo and the excellent AsciiDoc format, we propose a wish list item to "Antora-ize" the docs directory tree. Hopefully this can start a discussion about Antora.

Antora, an OSS project of OpenDevise, helps manage docs as code, converting AsciiDoc documents to HTML with asciidoctor.js, and can maybe help target some of DIG's tasks on the Evergreen Documentation Needs page (improved automation, UI improvements, PDF generation with Antora 3.0, etc):


docs/wiki links can later be added within the staff and OPAC clients as has been requested:

Antora-ize TODO:
• Organize docs into section "modules": Antora docs are stored in a module structure:

• Configure different docs branches in git. See the MuleSoft and Antora docs for examples of how versions can be presented:

• Setup Lunr search:

• Update DIG workflow guide as appropriate
Antora can be installed locally to maintain your own offsite copy of documentation (in-progress version branches, etc).

Antora Roadmap: https://docs.antora.org/antora/2.1/project/roadmap/

Ted Peterson (devted) on 2019-10-17
tags: added: documentation wishlist
Remington Steed (rjs7) wrote :

A few quick observations, which I haven't heard Blake mention yet:

- Antora has a solution for our frequent broken page links (they call them "Page IDs").
- Antora requires a level of organization that I think would benefit us. Even if we don't choose to use Antora, we should consider adopting some of their practices.

- Antora doesn't seem to have a way to add "Previous / Next" links, which we currently have on every docs page. They do have a persistent left navigation / table of contents, which serves a similar purpose, but not identical. We should decide if this difference is important for us.

Blake GH (bmagic) wrote :

Collab branch now (deleted the user branch)



Blake GH (bmagic) wrote :

For those of you following at home: Remington and I have been pushing lots of changes to that collab branch. I just pushed the search feature to it. Also, making note of some of the AsciiDoc errors during the build process:

asciidoctor: ERROR: item_status.adoc: line 66: include target not found: ../admin/turn-off-print-headers-firefox.adoc
asciidoctor: ERROR: item_status.adoc: line 68: include target not found: ../admin/turn-off-print-headers-chrome.adoc
asciidoctor: ERROR: intro_opensrf.adoc: line 1351: include target not found: python_client.py
asciidoctor: ERROR: end_matter.adoc: line 23: level 0 sections can only be used when doctype is book
asciidoctor: ERROR: end_matter.adoc: line 34: level 0 sections can only be used when doctype is book

Blake GH (bmagic) wrote :

Here are my thoughts right now:

Antora will automatically set the "title" of the browser page when the document has a "title" which is translated from the main heading line in the document. I've noticed that some of our documents start out with level 2 headers (Example):

Parts Level Hold

Which is the "second" heading. The main heading needs to look like this:

Main Header

We have a small issue here. As-is, the Antora pages will have HTML in the <head> block that looks like this:

<title>Untitled :: Evergreen Documentation</title>

We could write a script to automatically change all of our docs to have the main header. While we are at it, I was thinking that it would be nice to convert all of the headings to the "other" syntax. Like this:


Parts Level Hold


=== Parts Level Hold ===


Placing Multiple Holds on Same Title
==== Placing Multiple Holds on Same Title ====


Holds Pull List


===== Holds Pull List =====

It seems that we have skipped "Level 1" sometimes? Lifted from https://powerman.name/doc/asciidoc

Level 1

Level 2

Level 3

Level 4

Looking at our wiki:

We direct people to https://powerman.name/doc/asciidoc for the correct syntax.

I assume in the cases where we don't have a main header we should? In those cases should we "upgrade" level 2 -> 1 and 3 -> 2 and 4 -> 3 ?

Also - a table of contents (per page) would be nice. The same script could also add the :toc: syntax directly below the main header.

In summary

1. Create a main header line for documents that don't have one (and upgrade the other headings up a level in those cases)
2. Convert the header style lines to moustache style (number of equal signs on each side)
3. Add a table of contents to each document where one doesn't appear.

Remington Steed (rjs7) wrote :

Blake, I agree with your suggestions. I've added a section to the DIG Style Guide wiki page so that DIG can discuss these Antora-related changes:


As for your point #1, I'd call that a "bug" rather than a style change. Our old/current docs approach relies on the root files to use "leveloffset" when including certain files to correct the heading level mismatch. Let's take this opportunity to fix that. Your suggestion of "upgrading" those headings sounds good; that's exactly what the "leveloffset" approach did.

Blake GH (bmagic) wrote :

Remington: I think that #1 could have been on purpose. Reason is, the current documentation compile/html presentation will take pages as fragments and insert them "under" other pages. In those cases, the document starting with Level 2 was on purpose because the editor knew that it was going to be integrated into another document that already had the Level 1? Purely speculation.

Jane Sandberg (sandbej) wrote :

One issue with the install instructions in the README:

  30 $ cd ui
  31 $ npm install
  32 $ gulp --tasks-simple
  33 $ gulp bundle

The two gulp commands usually fail with "bash: gulp: command not found" for me. We could have users specify the file to node_modules/gulp/bin/gulp.js when running these commands, but that seems like it could easily break, and is a lot of typing. :-)

Maybe we could add something like this to package.json:

"scripts": {
      "gulp-bundle": "gulp bundle"

And then users could run `npm run gulp-bundle` and not have to worry about what binaries happen to be in their PATH.

And is there any purpose to the `gulp --tasks-simple` line, other than to confirm gulp installed correctly?

Jane Sandberg (sandbej) wrote :

Also, I like the permalinks available for specific sections. I don't think we should require users to hover over the heading to be able to see that it's available though -- this will be inaccessible to some users, and will just be missed by a lot of readers who might need it. Maybe something we can resolve once the ui is broken out into its own git repo?

Blake GH (bmagic) wrote :

Just documenting it here in LP. The Evergreen UI repository has been created and all of the code from the Evergreen repo has been moved to this repo: https://git.evergreen-ils.org/?p=eg-antora.git;a=summary

As per Jane's suggestions, I added that "scripts" clause to the package.json file allowing a shortcut for gulp bundle. The README on the Evergreen repo was also updated to reflect this feature. That came in with commit 13bbc80e7d7

A note on the "Shared" folder. This is a bit of a mess. I believe it's "correct" when integrated into the old documentation build process but in Antora, I'm not sure. The first thing that threw me was "end_matter.adoc" having two level 0 headings:

= Licensing =
= Index =

In order for Antora to build properly, I had to relegate "Index" to level 1. No big deal, but I would like to know the implications of this file and these files:


Also - I just committed the work for the Acq module. Like we talked about, the heading levels were upgraded and the Table of Contents was added. I've built the result set and you can view them here:


Jane Sandberg (sandbej) wrote :

We can definitely get rid of the shared folder and move their contents to a different module. The idea was that we could use the same licensing statement and index-generating directives throughout all of the re-organized manuals. So the shared folder was meant to save us from copy/pasting and content drifting out of date. It doesn't really fit the antora model, so we should redistribute that content where it makes more sense.

BTW, I updated the branch with a few recent docs changes, so the antora branch doesn't get out of date

Remington Steed (rjs7) wrote :

I'll start working on the Cataloging nav file. Here are the steps that we seem to need for each section (using Blake's commit "Navigation: Acq is done" as an example):

- Add chapter labels to nav file items
- To match existing docs "chapter" level headings, combine adoc files as needed so that each "chapter" from the old docs structure has a single file linked from the nav
- Upgrade all heading levels in each adoc file so that the top-most heading is a "Level 1" heading (example: "= Chapter Name =")
- Add ":toc:" below top heading of each file

Remington Steed (rjs7) wrote :

I'm done with cataloging and now I'm working on the nav section called "System Configuration and Customization".

Jane Sandberg (sandbej) wrote :

Some UI feedback from colleagues in my consortium:

* We're missing a section on command-line administration. One of my colleagues suggested that we have an antora module that corresponds to the current command line admin manual.

* They liked the link to the tabular release notes.

* A suggestion that we have some common left-side menus pre-expanded, so that there would be less clicking.

Remington Steed (rjs7) wrote :

Jane, I've been wondering how we would setup the topic manuals (such as Command Line Admin). That seems like the next problem to solve. After some basic research, it seems like we could keep them all in the same Antora "site" as separate "components". We would need a new layer of directories for those, like this:


Does anyone see a better way? Are there reasons to have separate Antora sites for the topic manuals?

Remington Steed (rjs7) wrote :

I'm working on the nav section "Using the Public Access Catalog".

Remington Steed (rjs7) wrote :

I'll also do the "Developer Resources" and "Getting Data from Evergreen" sections.

Blake GH (bmagic) wrote :

Taking "reports"

Remington Steed (rjs7) wrote :

I'm working on the "Serials" section.

Remington Steed (rjs7) wrote :

I'll do the "Circ" section. I think that's the last of the nav sections needing work.

We still need to figure out the topic manuals. And we could use lots of general review to look for broken things.

Remington Steed (rjs7) wrote :

I finished the "Circulation" section, so I think the nav related updates are done.

Next, we need lots of general review of the whole docs, looking for broken things.

We also need to setup the topic manuals. I'll give that a try using my suggestion in comment #15 above.

To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers