Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
rolfedh opened this issue Jul 22, 2024 · 6 comments · Fixed by #42039
Closed

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

rolfedh opened this issue Jul 22, 2024 · 6 comments · Fixed by #42039
Assignees
Labels
area/housekeeping Issue type for generalized tasks not related to bugs or enhancements
Milestone

Comments

@rolfedh
Copy link
Contributor

rolfedh commented Jul 22, 2024

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?

@rolfedh rolfedh added the area/housekeeping Issue type for generalized tasks not related to bugs or enhancements label Jul 22, 2024
@gsmet
Copy link
Member

gsmet commented Jul 22, 2024

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

gsmet added a commit to gsmet/quarkus that referenced this issue Jul 22, 2024
The title ended up being added first, which was definitely not what we
wanted.

Fixes quarkusio#42036
@gsmet
Copy link
Member

gsmet commented Jul 22, 2024

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

@rolfedh
Copy link
Contributor Author

rolfedh commented Jul 22, 2024

Excellent! Thank you!

@gsmet
Copy link
Member

gsmet commented Jul 22, 2024

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

@rolfedh
Copy link
Contributor Author

rolfedh commented Jul 22, 2024

No worries. Thanks for fixing it.

@rolfedh
Copy link
Contributor Author

rolfedh commented Jul 22, 2024

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.

@quarkus-bot quarkus-bot bot added this to the 3.14 - main milestone Jul 22, 2024
gsmet added a commit to gsmet/quarkus that referenced this issue Jul 22, 2024
The title ended up being added first, which was definitely not what we
wanted.

Fixes quarkusio#42036

(cherry picked from commit 6dc20b6)
@gsmet gsmet modified the milestones: 3.14 - main, 3.8.6 Jul 22, 2024
gsmet added a commit to gsmet/quarkus that referenced this issue Jul 23, 2024
The title ended up being added first, which was definitely not what we
wanted.

Fixes quarkusio#42036

(cherry picked from commit 6dc20b6)
barreiro pushed a commit to barreiro/quarkus that referenced this issue Jul 25, 2024
The title ended up being added first, which was definitely not what we
wanted.

Fixes quarkusio#42036
holly-cummins pushed a commit to holly-cummins/quarkus that referenced this issue Jul 31, 2024
The title ended up being added first, which was definitely not what we
wanted.

Fixes quarkusio#42036
danielsoro pushed a commit to danielsoro/quarkus that referenced this issue Sep 20, 2024
The title ended up being added first, which was definitely not what we
wanted.

Fixes quarkusio#42036
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/housekeeping Issue type for generalized tasks not related to bugs or enhancements
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants