Migrate to Antora

[lzap]

Hey,

this is just a tracking ticket and starting point for discussion about Antora: https://antora.org

While I am currently working on a simple navigation bar with pure HTML/JS/CSS embedded into asciidoc documents so readers can seamlessly switch guides or go back to the welcome page, I think long-term we need to think big. Antora looks like a great fit, however, this needs to be done in coordination with Red Hat Documentation team as things will need to be drastically changed downstream, and of course ATIX who also uses the documentation for their products.

Just to calm expectations: I am thinking something like end of 2022 as the earliest chance of starting this process. I would be glad for all the feedback in the ticket. Cheers!

[maximiliankolb]

We are using Antora in our downstream documentation. It's quite a bit different compared to asciidoctor, esp. when including other files or referencing anchors in other files.

So huge +1 from my side! I already showed @stejskalleos a bit of our Antora usage and a small "behind the scenes". We also already have a solution in place to check xrefs and to add search functionality.

Feel free to message me with any questions etc.

[stejskalleos]

+1 for this. @maximiliankolb gave me intro about Antora and it looked awesome. With Antora we could have search (yay!) and use their plugins and extensions to make docs really great.

I'll be glad to help you with the work, feel free to ping me.

[ekohl]

I was thinking about a different repository layout.

First of all, there would be a branch with just the antora config. No guides whatsoever. We could call that master but antora may be more descriptive. Then we have the branches with just guides, no more web/*. I'd stop using master and instead name it nightly to match its contents. We can even move everything from guides/* to the top level.

[maximiliankolb]

Some notes on recovering from a broken state in a protected branch which results in failing PRs against that branch due to GHA creating a diff:

## Recovering from a broken build due to the comparison with the previous commit

If you open a PR on Github, your feature branch gets built and compared to the target branch into which you want to merge.
Therefore, the Github Action builds the target branch.
This implies that even if your change works on its own, it depends on a working state in the target branch.

If the target branch does not build, your PR fails due to the comparision.
To fix this, you have to manually set the reference from "merge base of the target branch and your feature branch" to a commit ID of a working state, for example the parent commit of the faulty yet merged commit on the target branch.

Example: [REVERT ME: Use last working state as base](https://github.com/theforeman/foreman-documentation/commit/0ea9e707b6850487e60753a40fc2b2791528d175)

See also https://github.com/theforeman/foreman-documentation/pull/1865#discussion_r1065669720

[Lennonka]

I was playing with Antora yesterday and I'm not sure if it's a good idea to implement it. But I've only started and I'm certainly not finished yet. Still getting to know the whole system. Stay tuned...

[maximiliankolb]

Sounds great. Let's talk on Monday @Lennonka

[Lennonka]

Update: The main disadvantage was that Antora uses a different file structure than master.adoc files to organize TOCs. It uses "pages" that are similar to our assemblies, but require different include paths. If we can create a PoC in which the Antora pages are symlinked to assemblies and the include paths are parametrized with attributes, we would probably be good to implement Antora in Foreman Docs.