ci/links: Add PR check for broken links by marcleblanc2 · Pull Request #1858 · sourcegraph/docs

marcleblanc2 · 2026-09-06T07:04:18Z

Linear 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

Broken links fixed

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
fix/links: Replace absolute self-links with relative links (67 links) #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)

Draft PR Add daily broken link checker with Slack reporting #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 fix/site: Return HTTP 404 instead of 200 for unknown pages #1860 enabled external link checkers to find broken links again

Amp threads

vercel · 2026-09-06T07:04:25Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
sourcegraph-docs	Ready	Preview	Sep 11, 2026 1:36am UTC

Linear [FE-499: Fix doc site issues](https://linear.app/sourcegraph/issue/FE-499/fix-doc-site-issues) 25 `#anchor` links whose target heading still exists with the same words, but the slug drifted: - `_` vs `-` - doubled `--` - a stray `"` - punctuation github-slugger strips (`ssl/https` → `sslhttps`, `merge/close` → `mergeclose`, `Sourcegraph's` → `sourcegraphs`, `kustomization.yaml` → `kustomizationyaml`) No page changes, no wording changes. Every new anchor matches a real heading on the target page, so review is a skim: the words on both sides of each `→` are the same. Checker findings (`npm run check-links -- --check-anchors`, from #1858): 280 on main → 255 on this branch. One to note: `#deploy-sourcegraph` → `#deploy-sourcegraph-` in `docs/self-hosted/deploy/machine-images/aws-oneclick.mdx` — the heading is `## Deploy Sourcegraph 🎉` and the slugger turns the emoji into a trailing `-`, so its slug has a trailing `-`. Fixing the heading instead would be cleaner but changes a URL; left as a slug fix here. ## Verification The docs site serves its not-found page with HTTP 200 (fix in progress), so status codes prove nothing. Instead, every changed link was fetched on this PR's Vercel preview and the rendered HTML checked for two `id`s: the target page's own first heading (taken from its MDX source — the 404 page never has it) and the link's `#fragment`. Script: `node dev/verify-links-live.mjs --site <preview-url>`, coming in #1858. Old links point at the current production site so you can see the breakage; new links point at the preview and land on the heading. Checked 25 changed links against https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app: 25 resolve, 0 fail. Page rendered = the target page's first heading id is present (the 404 page never has it); Anchor = the #fragment is an id on the page. Old links point at the current site. <details><summary>All 25 links</summary> | File containing the link | Old link (broken today) | New link (preview) | Page rendered | Anchor found | |------|-------------------------|--------------------|---------------|--------------| | `docs/admin/auth/index.mdx` | [`/admin/config/authorization-and-authentication#bitbucket-server-bitbucket-data-center-authorization`](https://sourcegraph.com/docs/admin/config/authorization-and-authentication#bitbucket-server-bitbucket-data-center-authorization) | [`/admin/config/authorization-and-authentication#bitbucket-server--bitbucket-data-center-authorization`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/admin/config/authorization-and-authentication#bitbucket-server--bitbucket-data-center-authorization) | ✅ | ✅ | | `docs/admin/auth/saml/microsoft-adfs.mdx` | [`/self-hosted/http-https-configuration#nginx-ssl-https-configuration`](https://sourcegraph.com/docs/self-hosted/http-https-configuration#nginx-ssl-https-configuration) | [`/self-hosted/http-https-configuration#nginx-sslhttps-configuration`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/self-hosted/http-https-configuration#nginx-sslhttps-configuration) | ✅ | ✅ | | `docs/admin/code-hosts/non-git.mdx` | [`#next-steps--advanced-configuration`](https://sourcegraph.com/docs/admin/code-hosts/non-git#next-steps--advanced-configuration) | [`#next-steps-advanced-configuration`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/admin/code-hosts/non-git#next-steps-advanced-configuration) | ✅ | ✅ | | `docs/admin/search.mdx` | [`/self-hosted/observability/alerts#zoekt-memory-map-areas-percentage-used`](https://sourcegraph.com/docs/self-hosted/observability/alerts#zoekt-memory-map-areas-percentage-used) | [`/self-hosted/observability/alerts#zoekt-memory_map_areas_percentage_used`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/self-hosted/observability/alerts#zoekt-memory_map_areas_percentage_used) | ✅ | ✅ | | `docs/batch-changes/batch-spec-yaml-reference.mdx` | [`#changesettemplate-branch`](https://sourcegraph.com/docs/batch-changes/batch-spec-yaml-reference#changesettemplate-branch) | [`#changesettemplatebranch`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/batch-changes/batch-spec-yaml-reference#changesettemplatebranch) | ✅ | ✅ | | `docs/batch-changes/batch-spec-yaml-reference.mdx` | [`#steps-run`](https://sourcegraph.com/docs/batch-changes/batch-spec-yaml-reference#steps-run) | [`#stepsrun`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/batch-changes/batch-spec-yaml-reference#stepsrun) | ✅ | ✅ | | `docs/batch-changes/batch-spec-yaml-reference.mdx` | [`#on-repository`](https://sourcegraph.com/docs/batch-changes/batch-spec-yaml-reference#on-repository) | [`#onrepository`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/batch-changes/batch-spec-yaml-reference#onrepository) | ✅ | ✅ | | `docs/batch-changes/batch-spec-yaml-reference.mdx` | [`#changesettemplate-branch`](https://sourcegraph.com/docs/batch-changes/batch-spec-yaml-reference#changesettemplate-branch) | [`#changesettemplatebranch`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/batch-changes/batch-spec-yaml-reference#changesettemplatebranch) | ✅ | ✅ | | `docs/batch-changes/batch-spec-yaml-reference.mdx` | [`#changesettemplate-branch`](https://sourcegraph.com/docs/batch-changes/batch-spec-yaml-reference#changesettemplate-branch) | [`#changesettemplatebranch`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/batch-changes/batch-spec-yaml-reference#changesettemplatebranch) | ✅ | ✅ | | `docs/batch-changes/batch-spec-yaml-reference.mdx` | [`#changesettemplate-title`](https://sourcegraph.com/docs/batch-changes/batch-spec-yaml-reference#changesettemplate-title) | [`#changesettemplatetitle`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/batch-changes/batch-spec-yaml-reference#changesettemplatetitle) | ✅ | ✅ | | `docs/batch-changes/batch-spec-yaml-reference.mdx` | [`#changesettemplate-title`](https://sourcegraph.com/docs/batch-changes/batch-spec-yaml-reference#changesettemplate-title) | [`#changesettemplatetitle`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/batch-changes/batch-spec-yaml-reference#changesettemplatetitle) | ✅ | ✅ | | `docs/batch-changes/batch-spec-yaml-reference.mdx` | [`#workspaces-in`](https://sourcegraph.com/docs/batch-changes/batch-spec-yaml-reference#workspaces-in) | [`#workspacesin`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/batch-changes/batch-spec-yaml-reference#workspacesin) | ✅ | ✅ | | `docs/batch-changes/batch-spec-yaml-reference.mdx` | [`#changesettemplate-branch`](https://sourcegraph.com/docs/batch-changes/batch-spec-yaml-reference#changesettemplate-branch) | [`#changesettemplatebranch`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/batch-changes/batch-spec-yaml-reference#changesettemplatebranch) | ✅ | ✅ | | `docs/batch-changes/batch-spec-yaml-reference.mdx` | [`#steps-outputs`](https://sourcegraph.com/docs/batch-changes/batch-spec-yaml-reference#steps-outputs) | [`#stepsoutputs`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/batch-changes/batch-spec-yaml-reference#stepsoutputs) | ✅ | ✅ | | `docs/batch-changes/site-admin-configuration.mdx` | [`/admin/config/batch-changes#automatically-delete-branches-on-merge-close`](https://sourcegraph.com/docs/admin/config/batch-changes#automatically-delete-branches-on-merge-close) | [`/admin/config/batch-changes#automatically-delete-branches-on-mergeclose`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/admin/config/batch-changes#automatically-delete-branches-on-mergeclose) | ✅ | ✅ | | `docs/code-insights/explanations/current-limitations-of-code-insights.mdx` | [`/admin/permissions/api#Setting-sub-repository-permissions-for-users`](https://sourcegraph.com/docs/admin/permissions/api#Setting-sub-repository-permissions-for-users) | [`/admin/permissions/api#setting-sub-repository-permissions-for-users`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/admin/permissions/api#setting-sub-repository-permissions-for-users) | ✅ | ✅ | | `docs/code-insights/references/requirements.mdx` | [`/admin/permissions/api#Setting-sub-repository-permissions-for-users`](https://sourcegraph.com/docs/admin/permissions/api#Setting-sub-repository-permissions-for-users) | [`/admin/permissions/api#setting-sub-repository-permissions-for-users`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/admin/permissions/api#setting-sub-repository-permissions-for-users) | ✅ | ✅ | | `docs/code-navigation/auto-indexing-configuration.mdx` | [`#index-jobs`](https://sourcegraph.com/docs/code-navigation/auto-indexing-configuration#index-jobs) | [`#index_jobs`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/code-navigation/auto-indexing-configuration#index_jobs) | ✅ | ✅ | | `docs/self-hosted/deploy/kubernetes/troubleshoot.mdx` | [`#symbols-sidebar-and-hovers-are-not-working"`](https://sourcegraph.com/docs/self-hosted/deploy/kubernetes/troubleshoot#symbols-sidebar-and-hovers-are-not-working") | [`#symbols-sidebar-and-hovers-are-not-working`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/self-hosted/deploy/kubernetes/troubleshoot#symbols-sidebar-and-hovers-are-not-working) | ✅ | ✅ | | `docs/self-hosted/deploy/machine-images/aws-oneclick.mdx` | [`#deploy-sourcegraph`](https://sourcegraph.com/docs/self-hosted/deploy/machine-images/aws-oneclick#deploy-sourcegraph) | [`#deploy-sourcegraph-`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/self-hosted/deploy/machine-images/aws-oneclick#deploy-sourcegraph-) | ✅ | ✅ | | `docs/self-hosted/faq.mdx` | [`/self-hosted/observability/dashboards#frontend-provisioning-container-cpu-usage-long-term`](https://sourcegraph.com/docs/self-hosted/observability/dashboards#frontend-provisioning-container-cpu-usage-long-term) | [`/self-hosted/observability/dashboards#frontend-provisioning_container_cpu_usage_long_term`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/self-hosted/observability/dashboards#frontend-provisioning_container_cpu_usage_long_term) | ✅ | ✅ | | `docs/self-hosted/faq.mdx` | [`/self-hosted/observability/alerts#frontend-container-cpu-usage`](https://sourcegraph.com/docs/self-hosted/observability/alerts#frontend-container-cpu-usage) | [`/self-hosted/observability/alerts#frontend-container_cpu_usage`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/self-hosted/observability/alerts#frontend-container_cpu_usage) | ✅ | ✅ | | `docs/self-hosted/faq.mdx` | [`#can-i-consume-sourcegraph-s-metrics-in-my-own-monitoring-system-datadog-new-relic-etc`](https://sourcegraph.com/docs/self-hosted/faq#can-i-consume-sourcegraph-s-metrics-in-my-own-monitoring-system-datadog-new-relic-etc) | [`#can-i-consume-sourcegraphs-metrics-in-my-own-monitoring-system-datadog-new-relic-etc`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/self-hosted/faq#can-i-consume-sourcegraphs-metrics-in-my-own-monitoring-system-datadog-new-relic-etc) | ✅ | ✅ | | `docs/self-hosted/http-https-configuration.mdx` | [`#nginx-ssl-https-configuration`](https://sourcegraph.com/docs/self-hosted/http-https-configuration#nginx-ssl-https-configuration) | [`#nginx-sslhttps-configuration`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/self-hosted/http-https-configuration#nginx-sslhttps-configuration) | ✅ | ✅ | | `docs/self-hosted/http-https-configuration.mdx` | [`#nginx-ssl-https-configuration`](https://sourcegraph.com/docs/self-hosted/http-https-configuration#nginx-ssl-https-configuration) | [`#nginx-sslhttps-configuration`](https://sourcegraph-docs-git-fix-anchor-slug-drift-sourcegraph-f8c71130.vercel.app/self-hosted/http-https-configuration#nginx-sslhttps-configuration) | ✅ | ✅ | </details> Dropped from this PR: 11 same-page anchors in `docs/self-hosted/deploy/kubernetes/kustomize/index.mdx`. That file is shadowed by `kustomize.mdx` at the same route and never renders, so its links cannot be verified (or clicked) on the site. They go with the shadowed-route cleanup instead. Co-authored-by: Amp <amp@ampcode.com>

pjlast

Approving as is (it's great!), but I do wonder if there are cases where we might link to an external page that requires some sort of authorization, which could return a 404 and trigger the check unnecessarily 🤔

marcleblanc2 · 2026-09-11T01:33:34Z

Approving as is (it's great!), but I do wonder if there are cases where we might link to an external page that requires some sort of authorization, which could return a 404 and trigger the check unnecessarily 🤔

Those should return a 401 / 403 unauthorized instead of 404? I guess we'll find out.

Add a pull_request workflow that runs dev/check-links.mjs --check-anchors on both the PR head and its merge base, and reports only the findings the PR introduces: outbound links from changed pages, and inbound links from other pages to a page or heading the PR removed or renamed. Pre-existing broken anchors on main are ignored. The job comments on the PR and fails when new breakage is found. dev/check-links.mjs gains --root, --format (text|json|markdown) and --baseline to support that diff, plus case-mismatch detection for routes (links that resolve on macOS but 404 on Linux) and scanning of *.md files. Only *.mdx files count as routes, matching contentlayer's filePathPattern. Amp-Thread-ID: https://ampcode.com/threads/T-01a0753f-0f4f-7478-b36c-87466e7c0261 Co-authored-by: Amp <amp@ampcode.com>

…erted) Amp-Thread-ID: https://ampcode.com/threads/T-01a0753f-0f4f-7478-b36c-87466e7c0261 Co-authored-by: Amp <amp@ampcode.com>

…l be reverted)" This reverts commit 1edcff8.

Generated pages such as admin/telemetry/protocol.mdx define anchors with <a name="..."> rather than headings. Drops 132 false positives on main (431 -> 299 with --check-anchors). Amp-Thread-ID: https://ampcode.com/threads/T-01a0753f-0f4f-7478-b36c-87466e7c0261 Co-authored-by: Amp <amp@ampcode.com>

Replace the fs.existsSync asset checks (case-insensitive on macOS, so they hid links that 404 on the Linux build) with an enumerated lowercase -> real path map of files under public/ and docs/, mirroring the route check. Also register docs/index.mdx as the / route. It was never in the path map (the /index strip needed a leading slash), and existsSync('public/') was masking that by accepting any '/' link. Six pre-existing broken /#anchor links on the homepage are now reported. Amp-Thread-ID: https://ampcode.com/threads/T-01a07597-43c0-751b-8c49-6e5809e714d2 Co-authored-by: Amp <amp@ampcode.com>

A green run posts nothing. If an earlier run left a report and the PR has since been fixed, delete that comment instead of editing it to a checkmark. Amp-Thread-ID: https://ampcode.com/threads/T-01a07597-43c0-751b-8c49-6e5809e714d2 Co-authored-by: Amp <amp@ampcode.com>

The checkmark comment only ever appears after an earlier run reported breakage, so word it that way instead of "introduces no broken links". Keeps the comment (reverts the delete from the previous commit). Amp-Thread-ID: https://ampcode.com/threads/T-01a07597-43c0-751b-8c49-6e5809e714d2 Co-authored-by: Amp <amp@ampcode.com>

…-page anchors use own headings Amp-Thread-ID: https://ampcode.com/threads/T-01a07623-9d65-7356-96b8-2bebb31ffa5a Co-authored-by: Amp <amp@ampcode.com>

…ployed site Co-authored-by: Amp <amp@ampcode.com> Amp-Thread-ID: https://ampcode.com/threads/T-01a07623-9d65-7356-96b8-2bebb31ffa5a

…k, matching rehype-slug Amp-Thread-ID: https://ampcode.com/threads/T-01a07623-9d65-7356-96b8-2bebb31ffa5a Co-authored-by: Amp <amp@ampcode.com>

The checker resolves links against docs/**/*.mdx routes only and never reads src/data/redirects.ts, so a redirect added alongside a page move still leaves inbound links reported. Say so in the PR comment and in AGENTS.md so contributors update the links instead. Amp-Thread-ID: https://ampcode.com/threads/T-01a085bf-fe07-77a1-a4e2-55bff4679bcc Co-authored-by: Amp <amp@ampcode.com>

Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3 Co-authored-by: Amp <amp@ampcode.com>

… not count Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3 Co-authored-by: Amp <amp@ampcode.com>

… PR branch Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3 Co-authored-by: Amp <amp@ampcode.com>

…the source view Drop glob in favour of fs.readdirSync(recursive) so the PR check needs one package instead of the whole site, and skip the pnpm/setup-node steps. Every finding now links to the file and line on the PR branch, in the ?plain=1 code view where #L anchors work. Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3 Co-authored-by: Amp <amp@ampcode.com>

Outbound findings are in files the PR changed (it added or edited a bad link); inbound ones are elsewhere (the PR renamed or removed a link target). The workflow passes git diff --name-only against the merge base.

…l superseded runs Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3 Co-authored-by: Amp <amp@ampcode.com>

… probe external links on added lines Absolute links to this site (https://sourcegraph.com/docs/..., the legacy docs.sourcegraph.com host, http://, //, www.) are findings even when the target exists: they leave preview deployments and local dev, and hide moved pages behind redirects. The finding proposes the relative link, following src/data/redirects.ts when the page moved. Version-pinned links (/@5.1/...) stay external. --diff replaces --changed-files and scopes two new features to added lines: --check-external requests each external link (HEAD, then GET on an error status, following redirects) and reports 404/410 only; --review writes a GitHub review with one suggested change per line, which the workflow posts, skipping suggestions already on the PR. Amp-Thread-ID: https://ampcode.com/threads/T-01a08a01-44c1-775b-84d0-d67ff9501905 Co-authored-by: Amp <amp@ampcode.com>

…he ones the suggestion leaves Amp-Thread-ID: https://ampcode.com/threads/T-01a08a01-44c1-775b-84d0-d67ff9501905 Co-authored-by: Amp <amp@ampcode.com>

… so next build fails on dead links alone Amp-Thread-ID: 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>

…#1899) ## 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. - 32 pointed at the current route: prefix dropped. - 31 pointed at a moved page and only worked through `src/data/redirects.ts`: now link straight to the destination. - 4 needed a hand fix: the `commands#commands-id-mode` and `features#shard-merging` anchors no longer exist, `github#github-com-rate-limits` became `#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.mjs` fail 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 against `main` (317 → 250 pre-existing findings; the 67 removed are all self-links). ## Notes for reviewers - Bare URLs in prose and code blocks (e.g. the `See https://docs.sourcegraph.com/admin/observability/tracing` cells in `docs/cli/references/*`) are not links and are untouched; #1851 covers those. - `docs/admin/repo/perforce.mdx`, `docs/self-hosted/observability/alerts.mdx` and `dashboards.mdx` are synced from sourcegraph/sourcegraph (#1883); the same links need the same fix upstream or the next sync reverts them. - `docs/technical-changelog.mdx` holds 31 of the links and is retired by #1888; if that lands first, take the deletion. Co-authored-by: Amp <amp@ampcode.com>

marcleblanc2 changed the title ~~ci: comment on PRs that break internal links or anchors~~ Add check-links PR check Sep 6, 2026

vercel Bot deployed to Preview September 6, 2026 07:09 View deployment

vercel Bot deployed to Preview September 6, 2026 07:16 View deployment

marcleblanc2 mentioned this pull request Sep 6, 2026

fix/site: Fix broken tables of contents #1859

Merged

vercel Bot deployed to Preview September 6, 2026 07:31 View deployment

vercel Bot deployed to Preview September 6, 2026 07:42 View deployment

vercel Bot deployed to Preview September 6, 2026 07:45 View deployment

marcleblanc2 mentioned this pull request Sep 6, 2026

Fix broken anchors and links found by check-links --check-anchors #1861

Closed

vercel Bot deployed to Preview September 6, 2026 19:06 View deployment

marcleblanc2 mentioned this pull request Sep 7, 2026

fix/links: Fix broken heading links (25 mechanical drifts + 3 line-mates) #1864

Merged

vercel Bot deployed to Preview September 7, 2026 23:03 View deployment

vercel Bot deployed to Preview September 7, 2026 23:42 View deployment

marcleblanc2 mentioned this pull request Sep 9, 2026

chore/spelling: Recommend Code Spell Checker VS Code extension #1882

Merged

marcleblanc2 changed the title ~~Add check-links PR check~~ ci/links: Add PR check for broken links Sep 9, 2026

vercel Bot deployed to Preview September 9, 2026 10:48 View deployment

marcleblanc2 mentioned this pull request Sep 10, 2026

test: deliberately break links (do not merge) #1895

Closed

vercel Bot deployed to Preview September 10, 2026 01:22 View deployment

vercel Bot deployed to Preview September 10, 2026 01:24 View deployment

vercel Bot deployed to Preview September 10, 2026 01:26 View deployment

vercel Bot deployed to Preview September 10, 2026 01:40 View deployment

pjlast approved these changes Sep 11, 2026

View reviewed changes

marcleblanc2 and others added 20 commits September 10, 2026 19:34

test: rename a linked heading to exercise the PR comment (will be rev…

8bfbc1a

…erted) Amp-Thread-ID: https://ampcode.com/threads/T-01a0753f-0f4f-7478-b36c-87466e7c0261 Co-authored-by: Amp <amp@ampcode.com>

Revert "test: rename a linked heading to exercise the PR comment (wil…

275d1ea

…l be reverted)" This reverts commit 1edcff8.

check-links: strip fences line by line, first file wins a route, same…

6391704

…-page anchors use own headings Amp-Thread-ID: https://ampcode.com/threads/T-01a07623-9d65-7356-96b8-2bebb31ffa5a Co-authored-by: Amp <amp@ampcode.com>

Add verify-links-live: prove a branch's changed links resolve on a de…

94c37b4

…ployed site Co-authored-by: Amp <amp@ampcode.com> Amp-Thread-ID: https://ampcode.com/threads/T-01a07623-9d65-7356-96b8-2bebb31ffa5a

check-links: slug the full heading text when a heading contains a lin…

0339b3a

…k, matching rehype-slug Amp-Thread-ID: https://ampcode.com/threads/T-01a07623-9d65-7356-96b8-2bebb31ffa5a Co-authored-by: Amp <amp@ampcode.com>

check-links: reword the inbound-link guidance in the PR comment

423608e

Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3 Co-authored-by: Amp <amp@ampcode.com>

check-links: split the inbound-link guidance and say why redirects do…

66dbee2

… not count Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3 Co-authored-by: Amp <amp@ampcode.com>

check-links: link each file path in the PR comment to the file on the…

55e4ee2

… PR branch Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3 Co-authored-by: Amp <amp@ampcode.com>

check-links: split the PR comment into outbound and inbound broken links

055ed86

Outbound findings are in files the PR changed (it added or edited a bad link); inbound ones are elsewhere (the PR renamed or removed a link target). The workflow passes git diff --name-only against the merge base.

check-links: export listFiles and routeFor for check-redirects, cance…

1cb89f3

…l superseded runs Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3 Co-authored-by: Amp <amp@ampcode.com>

check-links: review comment lists every finding on the line, naming t…

df94a94

…he ones the suggestion leaves Amp-Thread-ID: https://ampcode.com/threads/T-01a08a01-44c1-775b-84d0-d67ff9501905 Co-authored-by: Amp <amp@ampcode.com>

check-links: report absolute self-links only with --check-self-links,…

492b425

… so next build fails on dead links alone Amp-Thread-ID: https://ampcode.com/threads/T-01a08a01-44c1-775b-84d0-d67ff9501905 Co-authored-by: Amp <amp@ampcode.com>

marcleblanc2 force-pushed the check-links-pr-check branch from 953692f to 492b425 Compare September 11, 2026 01:34

vercel Bot deployed to Preview September 11, 2026 01:36 View deployment

marcleblanc2 merged commit 01c1baa into main Sep 11, 2026
3 checks passed

marcleblanc2 deleted the check-links-pr-check branch September 11, 2026 01:37

This was referenced Sep 11, 2026

check-links: don't fail the generated-docs sync PR over absolute self-links it can't fix #1910

Open

cspell: drop resolved allow-list entries, allow words that escaped the PR check #1911

Merged

Navigation Menu

Uh oh!

ci/links: Add PR check for broken links - #1858

ci/links: Add PR check for broken links#1858
marcleblanc2 merged 20 commits into
mainfrom
check-links-pr-check

marcleblanc2 commented Sep 6, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 6, 2026 •

edited

Loading

Uh oh!

pjlast left a comment

Uh oh!

marcleblanc2 commented Sep 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

marcleblanc2 commented Sep 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Verification

Broken links found

Broken links fixed

Absolute self-links and external links

Related

Amp threads

Uh oh!

vercel Bot commented Sep 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pjlast left a comment

Choose a reason for hiding this comment

Uh oh!

marcleblanc2 commented Sep 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

marcleblanc2 commented Sep 6, 2026 •

edited

Loading

vercel Bot commented Sep 6, 2026 •

edited

Loading