Skip to content

fix: point old-version banner to the matching page on latest - #1620

Open
neon60 wants to merge 6 commits into
developfrom
fix/banner-latest-page-link
Open

fix: point old-version banner to the matching page on latest#1620
neon60 wants to merge 6 commits into
developfrom
fix/banner-latest-page-link

Conversation

@neon60

@neon60 neon60 commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Motivation

The "old version" announcement banner linked to a fixed docs root (https://rocm.docs.amd.com/en/latest/), so clicking it dropped the reader at the top of the latest documentation instead of the latest version of the page they were reading. From, say, a HIP 6.2.2 reference page, the banner sent readers to the docs home rather than the same reference page on latest.

This PR makes the banner link resolve to the matching page on the latest version, preserving the project and page path, while keeping a sensible no-JavaScript fallback.

Technical Details

  • src/rocm_docs/rocm_docs_theme/static/bannerLatestLink.js (new) — a client-side script that, on load, finds links carrying the data-rocm-banner-latest-link attribute and rewrites their href from .../en// to the same under latest, preserving the project prefix and URL hash. If the current URL is not versioned (.../en//...), the link is left untouched.
    Missing pages fall back to Read the Docs' own 404 handling for the latest version.
  • src/rocm_docs/theme.py — the three built-in banner variants (old release, release candidate, development) now tag their link with data-rocm-banner-latest-link. The link keeps its fixed .../en/latest/ href as the no-JS fallback; the script upgrades it at runtime. Registers the new script via add_js_file.
  • Opt-in, decoupled from styling — the rewrite is triggered by the data- attribute, not by id="rocm-banner" (which remains the CSS styling hook only). This means a project that overrides announcement with its own link is left untouched unless it opts in by adding the attribute — so custom banner links are never silently hijacked.
  • docs/user_guide/banner.md + docs/sphinx/_toc.yml.in — new user-guide page documenting the automatic banner, the matching-page behavior, and how to author a custom announcement (including opting a custom link into the rewrite). Added to the user-guide TOC.
  • .wordlist.txt — adds focusable and href for the spellcheck gate.

Test Plan

  • Build the docs with the banner forced on (an old-release build via ROCM_DOCS_REMOTE_DETAILS) and confirm the banner renders, ships the fixed-href fallback, and loads bannerLatestLink.js.
  • Verify the URL-rewrite logic against representative URLs: a project page (.../projects/HIP/en/docs-6.2.2/reference/x.html), a hash fragment, an Instinct-subdomain page, and a non-versioned URL (must be left unchanged).
  • Confirm a custom announcement link without the attribute is not rewritten.
  • Pass the markdownlint and spellcheck CI gates on the new Markdown.

Test Result

  • Old-release build: banner renders ("This is not the latest version…"), the baked href is the .../en/latest/ fallback, and bannerLatestLink.js is present on the page.
  • Rewrite logic verified: .../HIP/en/docs-6.2.2/reference/cpp_language_extensions.html → .../HIP/en/latest/reference/cpp_language_extensions.html; project prefix and #hash preserved; non-versioned URLs return unchanged (left as-is).
  • Override safety confirmed: a link with only id="rocm-banner" (no data- attribute) is not selected, so custom announcements keep their authored target.
  • Spellcheck passes after adding focusable/href to the wordlist.

Submission Checklist

neon60 and others added 4 commits August 28, 2026 13:08
The "old version" announcement banner linked to a fixed docs root, so
clicking it dropped the reader at the top of the latest docs instead of
the page they were reading. Add a client-side script that rewrites the
banner link (id="rocm-banner") from `.../en/<version>/<page>` to the same
`<page>` under `latest`, preserving the project prefix and hash. Missing
pages fall back to Read the Docs' own 404 handling for the latest version;
non-versioned URLs are left untouched.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Rename fixBannerLatestLink.js to bannerLatestLink.js and drop the "fix"
framing. Instead of rewriting any element with id='rocm-banner' (which is
also the CSS styling hook), the script now only rewrites links carrying the
data-rocm-banner-latest-link attribute. This separates styling from
behavior and, crucially, leaves a project's custom `announcement` override
untouched unless it opts in by adding the attribute. The three built-in
banners carry the attribute, keeping the fixed href as a no-JS fallback.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Document the automatic version banner (old release, release candidate,
development), how its link resolves to the matching page on the latest
version via bannerLatestLink.js, and how to set a custom announcement -
including opting a custom link into the latest-page rewrite with the
data-rocm-banner-latest-link attribute. Add the page to the user guide TOC.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Explain that the href is required and chosen by the author: the script
rewrites an existing link rather than creating one, so an <a> without an
href is not a working link. The href doubles as the fallback when the
rewrite does not run, so it should point at a sensible per-project landing
page rather than the ROCm root.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
@neon60

neon60 commented Sep 2, 2026

Copy link
Copy Markdown
Contributor Author

Test PR: ROCm/rocm-systems#10878

neon60 and others added 2 commits September 2, 2026 12:21
Add 'focusable' and 'href' to .wordlist.txt so the spellcheck CI passes on
the version banner user guide, which uses both terms when explaining the
custom-link href requirement.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Place 'href' before 'hsa' to match the pre-commit file-contents-sorter's
LC_ALL=C byte ordering; it was previously after 'hsakmt'.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
@neon60
neon60 marked this pull request as ready for review September 2, 2026 10:28
@neon60
neon60 requested a review from a team as a code owner September 2, 2026 10:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant