Fix Antora cross-references that lead to other pages.

[ahus1]

Also using AsciiDoc style listings instead of Markdown style listings, and using explicit section IDs on all cross-references.

Background: I'm maintaining the IntelliJ AsciiDoc plugin that also supports Antora. When I publish new releases, I sometimes pick some public AsciiDoc/Antora documentation and run the plugin's validations.
Some minor left-overs of the conversion showed up, and I submitted a PR.

Thanks for providing this this project including its docs!

[jzheaux]

Hi, @ahus1, thanks for the improvements!

If I understand correctly, it would make sense to backport the section id and AsciiDoc style listing changes.

Since Antora is not used on earlier versions, I don't think it makes sense to backport those changes. Would you agree? If so, will you please separate those into two commits so that we can more easily backport the other improvements?

[ahus1]

@jzheaux - TL;DR: I don't think anything in this PR should backported as the two changes about ID and listing style are only a refactoring that produces the same output as before:

1. Asciidoctor understands both the AsciiDoc and Markdown syntax for listings, and it generates the same output.
2. the section IDs work with implicit section IDs in 5.5.x (and they would work with Antora as well). Again, it is just a refactoring towards AsciiDoc best practices, as it guards you from broken references when headings change. It generates the output as before.

Still, if you insist, I'm happy to split this PR, or (preferred) submit another PR for 5.5.x with only the ID and listing changes.

[jzheaux]

Perfect, thanks for the clarification, @ahus1. This is now merged into main.