Upstream-downstream process moves title from line 7-ish to line 1, breaking links

[rolfedh]

Overview: In the upstream-downstream process, the document title is moved from approximately line 7 to line 1. This causes the downstream AsciiDoc tooling to dynamically generate an ID based on the title, which overrides the predefined id= attribute value. Consequently, links using the ID attribute value become broken.

Explanation

For example, in the Quarkus repository:

/home/rdlugyhe/quarkus/docs/src/main/asciidoc/security-overview.adoc:
  33:  * xref:security-proactive-authentication.adoc[Proactive authentication]

/home/rdlugyhe/quarkus/docs/src/main/asciidoc/security-proactive-authentication.adoc:
  7:  [id="security-proactive-authentication"]
  8:  = Proactive authentication

After transformation and pipeline processing in the RHBQ repo:

/home/rdlugyhe/gitlab/rhbq-quarkus/asciidoc/security-overview.adoc:
  33:  * link:{default-url}/security_architecture/security-proactive-authentication[Proactive authentication]

/home/rdlugyhe/gitlab/rhbq-quarkus/asciidoc/security-proactive-authentication.adoc:
  1:  = Proactive authentication
  ...
  7:  [id="security-proactive-authentication"]

In the RHBQ repo, because the title is now on the first line and not immediately preceded by the ID attribute, AsciiDoc generates a new ID from the title: proactive-authentication-3, replacing the original security-proactive-authentication in the URL. For example: https://docs.redhat.com/en/documentation/red_hat_build_of_quarkus/3.8/html/security_architecture/proactive-authentication-3

As a result, links that still reference the old ID attribute value (security-proactive-authentication) are broken. For instance, line 33 now points to: https://docs.redhat.com/en/documentation/red_hat_build_of_quarkus/3.8/html/security_architecture/security-proactive-authentication[Proactive authentication].

Many links in the guides are therefore broken.

For additional background info, see https://gitlab.cee.redhat.com/quarkus-documentation/quarkus/-/merge_requests/1733

Implementation ideas

Can this be fixed by updating AssembleDownstreamDocumentation.java to preserve the title in its current location?

[gsmet]

You're right, there's something fishy. Having a closer look.

[gsmet]

#42039 will fix it. I'll merge when CI is green and backport it too.

[rolfedh]

Excellent! Thank you!

[gsmet]

Sorry about that, not sure how I missed this and how it went unnoticed for so long...

[rolfedh]

No worries. Thanks for fixing it.

[rolfedh]

Sorry about that, not sure how I missed this and how it went unnoticed for so long...

The insertion of the dynamically-generated ID only becomes obvious when one shadow-publishes the product guides and runs a tool to validate links between guides.