Skip to content

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

Merged
marcleblanc2 merged 20 commits into
mainfrom
check-links-pr-check
Sep 11, 2026
Merged

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

Conversation

@marcleblanc2

@marcleblanc2 marcleblanc2 commented Sep 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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

Screenshot 2026-09-09 at 20 05 31

Broken links fixed

Screenshot 2026-09-09 at 20 06 31

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)

Related

Amp threads

@vercel

vercel Bot commented Sep 6, 2026 •
edited
Loading

Copy link
Copy Markdown

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

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

Request Review

@marcleblanc2 marcleblanc2 changed the title ci: comment on PRs that break internal links or anchors Add check-links PR check Sep 6, 2026
@marcleblanc2 marcleblanc2 mentioned this pull request Sep 6, 2026
Merged
@marcleblanc2 marcleblanc2 mentioned this pull request Sep 6, 2026
Closed
@marcleblanc2 marcleblanc2 mentioned this pull request Sep 7, 2026
Merged
This was referenced Sep 7, 2026
Draft
Draft
Merged
Draft
Draft
Draft
Draft
Draft
@marcleblanc2 marcleblanc2 mentioned this pull request Sep 9, 2026
Merged
@marcleblanc2 marcleblanc2 changed the title Add check-links PR check ci/links: Add PR check for broken links Sep 9, 2026
@marcleblanc2 marcleblanc2 mentioned this pull request Sep 10, 2026
Closed
marcleblanc2 added a commit that referenced this pull request Sep 10, 2026
@marcleblanc2 @ampagent
Fix broken heading links (25 mechanical drifts) (#1864)
e5c8190 
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>
@marcleblanc2
marcleblanc2 enabled auto-merge (squash) September 11, 2026 01:21
pjlast
pjlast approved these changes Sep 11, 2026
View reviewed changes

@pjlast pjlast left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

marcleblanc2 commented Sep 11, 2026

Copy link
Copy Markdown
Contributor Author

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.

marcleblanc2 and others added 20 commits September 10, 2026 19:34
@marcleblanc2 @ampagent
ci: comment on PRs that break internal links or anchors
e170fc0 
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>
@marcleblanc2 @ampagent
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>
@marcleblanc2
Revert "test: rename a linked heading to exercise the PR comment (wil…
275d1ea 
…l be reverted)"

This reverts commit 1edcff8.
@marcleblanc2 @ampagent
check-links: accept <a name> and id= attributes as anchor targets
20f17d6 
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>
@marcleblanc2 @ampagent
check-links: detect case mismatches in public/ and docs/ asset links too
b3ce80e 
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>
@marcleblanc2 @ampagent
check-links workflow: never comment on a clean PR
721b21f 
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>
@marcleblanc2 @ampagent
check-links workflow: say what the resolved comment actually means
74a8f4c 
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>
@marcleblanc2 @ampagent
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>
@marcleblanc2 @ampagent
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
@marcleblanc2 @ampagent
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>
@marcleblanc2 @ampagent
check-links: state that redirects do not satisfy the PR check
90d9cb6 
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>
@marcleblanc2 @ampagent
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>
@marcleblanc2 @ampagent
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>
@marcleblanc2 @ampagent
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>
@marcleblanc2 @ampagent
check-links: install only github-slugger in CI, link line numbers to …
66cdca9 
…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>
@marcleblanc2
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.
@marcleblanc2 @ampagent
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>
@marcleblanc2 @ampagent
check-links: flag absolute self-links with a suggested relative link,…
602ba67 
… 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>
@marcleblanc2 @ampagent
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>
@marcleblanc2 @ampagent
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
marcleblanc2 merged commit 01c1baa into main Sep 11, 2026
3 checks passed
@marcleblanc2
marcleblanc2 deleted the check-links-pr-check branch September 11, 2026 01:37
marcleblanc2 added a commit that referenced this pull request Sep 11, 2026
@marcleblanc2 @ampagent
fix/links: Replace absolute self-links with relative links (67 links)
9ed531d 
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 added a commit that referenced this pull request Sep 11, 2026
@marcleblanc2 @ampagent
fix/links: Replace absolute self-links with relative links (67 links) (…
aa22ff4 
…#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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@pjlast pjlast pjlast approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@marcleblanc2 @pjlast