fix/links: Replace absolute self-links with relative links (67 links) - #1899
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
pjlast
approved these changes
Sep 11, 2026
marcleblanc2
added a commit
that referenced
this pull request
Sep 11, 2026
Linear [FE-499: Fix doc site issues](https://linear.app/sourcegraph/issue/FE-499/fix-doc-site-issues) ## Problem - Our docs site has hundreds of broken links - `dev/check-links.mjs` finds broken internal links and anchors, but it isn't run automatically, so PRs can easily break links (renaming a heading, moving or deleting a page) without anyone noticing ## Solution - Updated the script to also work as a PR check, with additional functions beyond what's run when used as a CI test in Vercel builds - PR check to run the script and report if the PR breaks links - It runs the script (with `--check-anchors`) on both the PR head and its merge base, and diffs the findings - This catches both directions: - **Outbound**: a changed page links to a page or `#heading` that doesn't exist - **Inbound**: the PR renames a heading or removes/moves a page that other, unchanged pages link to — those show up as findings in files the PR didn't touch - Pre-existing broken links are ignored by the PR check - The comment is created / updated in place, and once the PR is fixed, the PR check passes and the comment is updated to say so - A PR that never broke anything gets no comment ## Verification PR check comment in test PR: #1895 (comment) ### Broken links found <img width="1826" height="1628" alt="Screenshot 2026-09-09 at 20 05 31" src="https://github.com/user-attachments/assets/930cde1f-50b1-46c0-9421-bd75a257c17d" /> ### Broken links fixed <img width="910" height="168" alt="Screenshot 2026-09-09 at 20 06 31" src="https://github.com/user-attachments/assets/1cc26276-5cba-4595-85fc-8e10955aabab" /> ## Absolute self-links and external links - Absolute links to this site (`https://sourcegraph.com/docs/…`, `http://…`, `//…`, `www.`, the legacy `https://docs.sourcegraph.com/…`) fail the check even when the target exists: they leave the Vercel preview and local dev, and hide moved pages behind redirects. The finding names the relative link, following `src/data/redirects.ts` when the page moved. Version-pinned links (`/@5.1/…`) stay external - External links on lines this PR added are requested (HEAD, then GET on an error status, following redirects); only 404 and 410 are findings, so rate limits, bot blocks, 5xx and network errors never fail a PR. Placeholder hosts (`*.example.com`, `localhost`, templated `<host>`) are skipped - Findings with a fix become one suggested-change review comment per line, which the author can apply from the PR. Suggestions already on the PR are not posted again - #1899 clears the 67 existing absolute self-links so this check starts from zero Test PR: #1900 (report comment + one review suggestion; the `#sampling` anchor deliberately does not exist, so that link gets no suggestion; a second run posted nothing new) ## Related - Draft PR #1562 proposes a daily Slack digest with a separate reimplementation of this script - Instead, this PR improves on the existing script, and gates PRs - PR #1860 enabled external link checkers to find broken links again ## Amp threads - [Broken link PR check](https://ampcode.com/threads/T-01a0753f-0f4f-7478-b36c-87466e7c0261) - [Asset case mismatch](https://ampcode.com/threads/T-01a07597-43c0-751b-8c49-6e5809e714d2) - [Docs - Fix broken heading links](https://ampcode.com/threads/T-01a07623-9d65-7356-96b8-2bebb31ffa5a) - [Self-links and external links](https://ampcode.com/threads/T-01a08a01-44c1-775b-84d0-d67ff9501905) --------- Co-authored-by: Amp <amp@ampcode.com>
Links to this site written as https://sourcegraph.com/docs/..., http://, or https://docs.sourcegraph.com/... leave the preview deployment and local dev server, and 31 of them pointed at moved pages that only worked through src/data/redirects.ts. Found and resolved by dev/check-links.mjs on #1858; four links needed a hand fix because their anchor or page is gone. Amp-Thread-ID: https://ampcode.com/threads/T-01a08a01-44c1-775b-84d0-d67ff9501905 Co-authored-by: Amp <amp@ampcode.com>
marcleblanc2
force-pushed
the
fix-absolute-self-links
branch
from
September 11, 2026 01:37
70c04cd to
9ed531d
Compare
Contributor
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.
What
Rewrites every link to this site that was written as an absolute URL (
https://sourcegraph.com/docs/…,http://sourcegraph.com/docs/…,https://docs.sourcegraph.com/…) as a relative link (/admin/config/site-config), in 15 files.src/data/redirects.ts: now link straight to the destination.commands#commands-id-modeandfeatures#shard-merginganchors no longer exist,github#github-com-rate-limitsbecame#rate-limits, and the deleted gRPC guide now links to its archived 5.3 page.Why
Absolute links leave the Vercel preview and the local dev server, and hide moved pages behind redirects. #1858 makes
dev/check-links.mjsfail PRs that add them; this PR clears the backlog so that check starts from zero.Verification
node dev/check-links.mjs --check-anchors --root <this branch>with the checker from #1858: 0 absolute self-links left, and no new findings againstmain(317 → 250 pre-existing findings; the 67 removed are all self-links).Notes for reviewers
See https://docs.sourcegraph.com/admin/observability/tracingcells indocs/cli/references/*) are not links and are untouched; Point stale docs.sourcegraph.com links at sourcegraph.com/docs #1851 covers those.docs/admin/repo/perforce.mdx,docs/self-hosted/observability/alerts.mdxanddashboards.mdxare synced from sourcegraph/sourcegraph (🤖 Sync generated docs from sourcegraph/sourcegraph #1883); the same links need the same fix upstream or the next sync reverts them.docs/technical-changelog.mdxholds 31 of the links and is retired by docs/changelog: Deduplicate old technical changelog page, redirect releases to their records of truth #1888; if that lands first, take the deletion.