Add daily broken link checker with Slack reporting - #1562
Closed
eugenio-sanchez-sg wants to merge 1 commit into
Closed
Add daily broken link checker with Slack reporting#1562eugenio-sanchez-sg wants to merge 1 commit into
eugenio-sanchez-sg wants to merge 1 commit into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
eugenio-sanchez-sg
marked this pull request as draft
January 26, 2026 16:16
Contributor
|
I'd recommend we keep, improve, and reuse the existing https://github.com/sourcegraph/docs/blob/main/dev/check-links.mjs script, rather than duplicate it. It can be reused in a GitHub Actions cron job, to ping us in Slack with a list of broken links each day. |
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>
Contributor
|
Closing as part of the stale-branch cleanup (see #1950); the branch is being deleted. Reopen from a fresh branch if still needed. |
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.
Problem
We have internal links in our docs that point to pages that have been removed or renamed.
Solution
A GitHub Action that runs daily at 6am UTC, scans all docs for broken internal links, and reports the results to a Slack channel.
Implementation
New files:
scripts/check-internal-links.js— Node script that:[text](/path)and JSXhref="/path"patterns.github/workflows/check-links.yml— Cron workflow that runs daily and sends results to SlackUsage:
npm run check-internal-links # Run locally (prints to console)Setup required (after merge)
api.slack.com/appsSLACK_WEBHOOK_URLto GitHub repo Settings → Secrets → ActionsOpen questions
Feedback welcome — this is a proposal to see if this approach makes sense for the team.