Antora should use the document ID on the top level h1
It would be useful if Antora used the document ID on the top level h1. For example, in the following document:
[[intro]]
= Intro to My Project
... lots of content ...
This assumes you have read <<intro, the introduction>>.
Currently there is no id added to the Antora output named intro
. This is surprising and inconsistent with how I've ever used asciidoc.
A link to the same page could work, but it would force the page to reload instead of just scrolling.
Pointing to #
might work, but this depends on the antora ui that is used. If the ui has a lot of content above the article, #
might be in the incorrect spot.
Another option is to perhaps edit the default-ui to have a constant id for the header. However, that makes my documentation less portable. If the ui is changed, then it would break my documentation. It also feels strange for the asciidoc files to be aware of the antora UI (which it would need to be if it was relying on the constant id). I'm guessing using a constant id that is not present in the asciidoc (only in the antora ui) could cause warnings within asciidoc generation as well.
To me the right solution feels like antora placing the document ID on the h1.
Related discussion on zulipchat