docs: repair 7 broken internal links - #580
Merged
Merged
Conversation
Relative MDX hrefs are emitted raw into the HTML and resolved by the browser against a URL with no trailing slash, so `./x` is a sibling and `../` climbs one level higher than expected. Materialize (introduced in #574): - overview: `../../concepts/permission-sets` and `../../concepts/permission-set-lifecycle` resolved to `/docs/concepts/*`, which redirects to the SpiceDB FAQ. - download-permission-sets: two `./concepts/permission-set-lifecycle` links resolved to `/docs/materialize/api/concepts/*` (404). The `../concepts/ snapshots` link in the same file was already correct. SpiceDB (pre-existing): - protecting-a-blog: `[running instance]` pointed at the removed `getting-started/installing-spicedb`. - ops/data/migrations: `../getting-started/installing-zed` resolved to `/spicedb/ops/getting-started/installing-zed` (404); made absolute. - tutorials/federated-authorization: `/spicedb/getting-started/install` has no index page, only per-OS children. Points at `install/docker`, matching the first-steps card. Verified against the live site and with a full sweep of all 93 pages; the only remaining relative-link report is a false positive on a footnote.
Contributor
|
Preview deployment status for this pull request.
|
The Materialize pages referenced SpiceDB and AuthZed concepts with fully-qualified https://authzed.com/docs/... URLs, carried over from the original authzed/concepts/authzed-materialize page. Nextra's anchor component treats any http(s) href as external, so those links rendered with target="_blank" and an external-link arrow — while links within the Materialize section stayed in-tab. Rewrites the 10 affected link definitions to root-relative paths, matching how app/spicedb already links across sections. Also fixes preview deploys, where the absolute URLs navigated away to production.
authzed-catherine
approved these changes
Aug 13, 2026
authzed-catherine
left a comment
authzed-catherine
left a comment
Contributor
There was a problem hiding this comment.
Thanks for catching these!
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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.
Corey spotted dead links on
/materialize/getting-started/overview— under Event Streams, both "permission set" and "The Permission Set Lifecycle" land on the SpiceDB FAQ. Confirmed, plus five more found in a full sweep.Root cause
Relative MDX hrefs are emitted raw into the HTML (
href="../../concepts/x") and resolved by the browser against a URL with no trailing slash. So./xis a sibling, not a child, and../climbs one level higher than it looks like it should.Introduced by #574 (materialize-feature-badges)
materialize/getting-started/overview../../concepts/permission-sets/docs/concepts/permission-sets../../concepts/permission-set-lifecycle/docs/concepts/permission-set-lifecyclematerialize/api/download-permission-sets×2./concepts/permission-set-lifecycle/docs/materialize/api/concepts/…All four become
../concepts/…. The../concepts/snapshots#…link already indownload-permission-setswas correct and is the reference form.Pre-existing
spicedb/getting-started/protecting-a-blog— the[running instance]reference definition pointed atgetting-started/installing-spicedb, which no longer exists (same dead path docs: fix broken doc links (redirects + dead card link) #569 fixed onfirst-steps; this file was missed). →install/dockerspicedb/ops/data/migrations—../getting-started/installing-zedresolved to/spicedb/ops/getting-started/installing-zed(404). Made absolute; the absolute path returns 200.spicedb/tutorials/federated-authorization—/spicedb/getting-started/install404s: that directory has_meta.tsand six per-OS children but nopage.*. →install/docker, matching the "Install the SpiceDB server binary" card onfirst-steps.If an
installindex page is wanted later, that link can point back at the folder.Verification
next.config.mjsredirects. After this change the only remaining report is a false positive — a[^1]: SpiceDB …footnote matching the reference-definition pattern./images/*references verified present inpublic/.pnpm format:checkandpnpm buildboth green.Non-issue, for the record
Sidebar folder headings emit basePath-less hrefs (
/spicedb/getting-started/install) that 404 if opened directly. This is Nextra's collapsible-group markup —/spicedb/api,/spicedb/concepts, and/spicedb/getting-startedall behave the same way — and the anchors are intercepted client-side. Not touched here.