Motivation:

1) Chunked (google search) vs in-document search
– A single page docs html is great because ctrl-f to find a keyword on it works well
– A single page docs html is terrible because google can't rank the "pinned entities" section for keywords like "optaplanner pin entities"
– A single page docs html analytics doesn't tell us which sections they are reading
– Antora induces a static-website-friendly search box across chunked pages. Basically it generates an index during the build and a client-side javascript script makes it work. That's better than ctrl-f.

2) Every release, we have a new url (including the version number) for the docs. They don't have a "canonical link" head meta html entry that points to the "latestFinal" symbolic link, because some google advise (matt cuffs) said that might not be a good idea (the answer was very unclear). Learn from Antora projects how they deal with that - I am sure that they figured this out already.

Requirements:

• Do not harm old versions on https://docs.optaplanner.org/ - those urls must still work
  Goal:
• Automate publishing antora build docs to docs.optaplanner.org as part of the release
• Minimize impact on www.optaplanner.org
• Make it clear in antora's docs website header that this is not the optaplanner website, but the optaplanner docs website (and link back of course).
  Unless they can share the nav bar? (I doubt it)

Suggestions how to tackle this issue:

Build these websites locally:

• RevApi: https://revapi.org/
  Potential source: https://github.com/revapi/revapi/tree/main/revapi-site-assembly
  RevApi only has the antora website - it doesn't have a real website like OptaPlanner does.

• JBang https://www.jbang.dev/documentation
  (talk to Max Anderson for more information)
  Potential source: https://github.com/jbangdev/jbang/blob/main/docs/antora.yml
  Jbang has a clear separation between the project website and the docs subwebsite (like we do have at OptaPlanner)

• Camel: https://camel.apache.org/manual/latest/
  Zoran Regvart is the go-to guy for this
  Potential source: https://github.com/apache/camel/blob/main/docs/user-manual/antora.yml
  and https://github.com/apache/camel-website/tree/main/antora-ui-camel
  Camel is probably a lot more advanced (= complex)

Ideally, the use of antora is just a maven plugin in the pom.xml like asciidoc is, part of the -Dfull build. I am not sure if that is possible.