fix: add .mdx suffix to ~190 bare relative links that break on SPA click#1946
Merged
fix: add .mdx suffix to ~190 bare relative links that break on SPA click#1946
Conversation
…e links detects relative markdown links without .mdx/.md suffix that break on SPA navigation due to Docusaurus SSR-vs-CSR URL resolution mismatch. same bug class as DOC-1311. Closes DEVOPS-775
… SPA click docusaurus only resolves relative markdown links at build time when they end in .mdx/.md. without the suffix, the raw string survives into the compiled bundle and the browser resolves it against window.location at click time — producing 404s on SPA navigation. fixes all LIVE-BROKEN links and coincidental-match links found by the scanner in version-0.33.0 versioned docs. also fixes directory targets by appending README.mdx where appropriate.
same bug class as the v0.33.0 fix — bare relative links without .mdx suffix break on SPA click due to docusaurus SSR-vs-CSR URL resolution mismatch. mechanical fix: append .mdx to leaf files, README.mdx to directory targets.
… partials fragments are embedded via import into parent pages, so their relative links resolve from the embedding page's directory. same bug class — without .mdx suffix, docusaurus skips build-time resolution and browser click-time resolution diverges from file-path resolution. reviewed all 7 fragment files across both main and v0.33.0 — all 17 links confirmed broken from their embedding contexts.
without a CI gate, bare relative links regress faster than they land — AI-assisted doc authoring inconsistently applies .mdx suffix (PR #1889 got it right on 3 links and wrong on 9 in the same file). this workflow runs the scanner on PRs touching .mdx files and exits non-zero on any bare relative link missing the suffix.
✅ Deploy Preview for vcluster-docs-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
three categories of links can't take .mdx suffix: - fragment/partial links: docusaurus resolves from the fragment's own directory, not the embedding page, so .mdx suffix causes file-not-found - auto-generated targets: cli/ pages don't exist as source files - numbered-prefix files: self-assessment links to 1-control-plane-components but the link says control-plane-components (filename mismatch, pre-existing) these are left bare (no .mdx) to avoid regressing the build. they were already broken on SPA click before this PR — the scanner still flags them.
CLAUDE.md was modified by a linter, platform/monitoring.mdx was an artifact from a build comparison, settings.local.json is local-only. none belong in this PR.
some bare relative links cannot take .mdx suffix without breaking the docusaurus build: auto-generated CLI pages (no source file), numbered filename prefixes (1-control-plane-components vs control-plane-components), and removed directories (quick-start). the scanner now skips these known exceptions so CI passes while still catching new regressions.
djwfyi
approved these changes
Apr 16, 2026
Collaborator
djwfyi
left a comment
djwfyi
left a comment
There was a problem hiding this comment.
LGTM
Only lingering question is how do we remember to update this when we release the next version and need to be checking more than just 0.33 docs?
vale Loft.exclude-please flagged line 99. While editing, also fixed "follow this processes" grammar and added the missing period. Applied to main and v0.33.0 copies.
djwfyi asked how this workflow would handle v0.34.0 without manual edits. The answer: don't hardcode the version. Each release cut snapshots vcluster/ (already enforced) into a new version-X.Y.Z folder, so discovering the highest-numbered folder at runtime picks up new versions automatically. Pre-existing broken links in older versions (0.28-0.32) are out of scope for this gate — scanning them would fail CI on unrelated PRs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Content Description
Adds
.mdxsuffix to bare relative markdown links acrossvcluster/(main) andvcluster_versioned_docs/version-0.33.0/that break on SPA click due to the Docusaurus SSR-vs-CSR URL resolution mismatch documented in the DOC-1311 post-mortem. Also commits the detection scanner toscripts/find-spa-broken-links.pyand adds a CI linter workflow that blocks PRs introducing new bare relative links.Changes:
scripts/find-spa-broken-links.py): detects relative links without.mdx/.mdsuffix that would 404 on SPA click. Includes known-exceptions allowlist for links that cannot take.mdxwithout breaking the build (auto-generated CLI pages, numbered-prefix filenames, removed directories).vcluster/.github/workflows/validate-mdx-links.yml): runs scanner on PRs, exits non-zero on any new bare relative linkNot fixed in this PR (pre-existing issues that require separate work):
.mdxlinks from the fragment file location, not the embedding page — adding.mdxbreaks the build1-control-plane-components.mdx) but links reference bare names.mdxexistsPreview Link
Internal Reference
Closes DEVOPS-775
AI review: mention
@claudein a comment to request a review or changes. See CONTRIBUTING.md for available commands.@netlify /docs