Skip to content

fix: point OpenShift documentation links at docs.redhat.com - #217

Open
arska wants to merge 1 commit into
masterfrom
fix/openshift-docs-links
Open

fix: point OpenShift documentation links at docs.redhat.com#217
arska wants to merge 1 commit into
masterfrom
fix/openshift-docs-links

Conversation

@arska

@arska arska commented Sep 3, 2026

Copy link
Copy Markdown
Member

docs.openshift.com is a legacy domain with a four-hop redirect chain

Every link to it now goes through four redirects, two of which downgrade to plain HTTP, before reaching Red Hat's current documentation site:

https://docs.openshift.com/container-platform/
  -> http://docs.openshift.com/container-platform/latest      (301, downgrade)
  -> http://docs.openshift.com/container-platform/4.18/        (301)
  -> https://docs.openshift.com/container-platform/4.18/       (301, back up)
  -> http://docs.openshift.com/.../welcome/index.html          (301, down again)
  -> https://docs.redhat.com/en/documentation/openshift_container_platform/...

Linking the destination removes the chain, the protocol downgrades, and a version pin nobody chose: the bare /container-platform/ URL resolves to whatever Red Hat currently points it at, which is 4.18 today and will silently change.

13 occurrences across 9 files. The pages still render the same; only the hrefs change.

Where the replacements come from

Each one is where Red Hat's own redirect resolves that exact URL today, so the mapping is theirs rather than mine. Three needed a judgment call instead, and each was checked in a browser rather than guessed:

case why resolution
bare /container-platform/ redirect lands on 4.18/html/about/welcome-index, but that book 404s at latest (checked on 4.22) product landing page, .../openshift_container_platform/latest
4.11 ServiceMonitor API that version of the page is gone; the redirect gives up at the 4.11 version root same page under latest, verified live
links that said latest docs.redhat.com honours the same alias still say latest, so nothing is newly pinned

I originally tried to verify all 13 targets with a script, using "does it redirect?" as the signal for a valid page. That check was worthless: docs.redhat.com answers 403 to every non-browser client regardless of user agent, and my known-dead control passed it exactly like the known-good one. The browser checks above are what the three judgment calls actually rest on.

Deliberately not changed

  • Version-pinned links keep their version (3.11, 4.8, 4.9, 4.11), except the one whose page no longer exists there. Whether those are still the right versions to document against is an editorial question for maintainers, not a link fix.
  • One anchor is dropped. accessing-the-registry.html#prerequisites has no corresponding fragment on the new page, so it lands at the top of the right chapter.

How it was found

The external link audit in vshn/landingpager#707 flagged the two occurrences on index.adoc as 403s. They are not dead links: docs.redhat.com blocks non-browser clients below the user-agent level, and the pages load fine in a browser. Excluding the domain from the link checker would have been the easy answer and would have left the redirect chain, the HTTP downgrades and the drifting version pin in place. The other 11 occurrences are the same problem on pages that audit does not reach.

docs.openshift.com is a legacy domain. Every link to it now takes four
redirects, two of which downgrade to plain HTTP, before landing on Red Hat's
current documentation site:

    https://docs.openshift.com/container-platform/
      -> http://docs.openshift.com/container-platform/latest      (301, downgrade)
      -> http://docs.openshift.com/container-platform/4.18/        (301)
      -> https://docs.openshift.com/container-platform/4.18/       (301, back up)
      -> http://docs.openshift.com/.../welcome/index.html          (301, down again)
      -> https://docs.redhat.com/en/documentation/openshift_container_platform/...

Linking the destination removes the chain, the protocol downgrades, and a
version pin nobody chose: the bare /container-platform/ URL resolves to
whichever version Red Hat currently redirects to, which is 4.18 today.

13 occurrences across 9 files. Each replacement is where Red Hat's own redirect
resolves that exact URL today, so the mapping is theirs rather than mine, with
three exceptions checked in a browser instead:

- The bare /container-platform/ link resolves to 4.18/html/about/welcome-index,
  but that book no longer exists at `latest` (404 on 4.22). It now points at the
  product landing page, which stays current.
- The 4.11 ServiceMonitor API page is gone; Red Hat's redirect gives up at the
  4.11 version root. It now points at the same page under `latest`.
- Links that said `latest` still say `latest`. docs.redhat.com honours the same
  alias, so nothing is newly pinned.

Version-pinned links keep their version (3.11, 4.8, 4.9, 4.11), except the one
above whose page no longer exists at that version. Whether those versions are
still the right ones to document against is a separate editorial question and is
deliberately not touched here.

One anchor is dropped: accessing-the-registry.html#prerequisites has no
corresponding fragment on the new page.

Found by the external link audit in vshn/landingpager#707, which reported the
two occurrences on index.adoc. The other 11 are the same problem on pages that
audit does not reach.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant