Fix broken relative links on release-notes index pages - #376
Merged
Conversation
added 2 commits
August 31, 2026 09:20
Every relative link authored on an index.md/index.mdx file under release-notes/ resolved to the wrong URL in production, since these pages serve at their folder's own bare path with no trailing slash and standard relative-URL resolution drops that last segment as if it were a filename. Converted all 333 affected links (across 47 files) to root-relative absolute paths, verified each target resolves to a real file on disk.
The guide previously claimed a relative link authored on an index page resolves against the folder containing that file. It actually resolves against that folder's parent, since the page's own URL has no trailing slash - the opposite of what was documented, and the root cause of the release-notes 404s fixed in the previous commit. Added a Warning callout and removed the now-incorrect "../index" example.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
digitaldiina
added
broken-link
github-project-automation
Bot
moved this from 📥 Ready for review
to ✔ Done
in Content Tasks
This was referenced Aug 31, 2026
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
1 participant
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.
Summary
index.md/index.mdxfiles underrelease-notes/, converting them to root-relative absolute paths.contribute/markdown-guide/links-in-docs.mdx's previously wrong guidance on how relative links resolve on index pages, and adds a<Warning>callout so this doesn't get reproduced.Closes #375
Root cause
A page built from a literal
index.md/index.mdxfile is served at its folder's own bare path with no trailing slash (for examplerelease-notes/12/index.mdxserves at/release-notes/12). Relative-URL resolution drops the last URL segment as if it were a filename, which is correct for a real leaf page but wrong here, since that segment is the folder itself. A link written as./12/indexonrelease-notes/index.mdxresolved to/12/indexinstead of/release-notes/12/index, a 404.Full detail in #375.
Verification
markdownlint-cli2on all 48 touched files: only pre-existing issues, confirmed identical tomain's baseline for the same files (3MD053inrelease-notes/11/index.mdx, 1MD053inrelease-notes/mobile/index.mdx, 1MD044inrelease-notes/integrations/index.md), plus one documentedMD053false positive in the new<Warning>block (markdownlint doesn't scan inside HTML/JSX tags, already noted elsewhere in the same file).mint validate: 13 warnings, all pre-existing and unrelated (generatedmdo-providers/archive-providersxref/tag issues plus a.scratch/file), none in the touched files.Test plan
/release-notesand confirm it lands on/release-notes/12, not/12/index./release-notes/11,/release-notes/mobile,/release-notes/integrations) resolve correctly.