Add external link checking with lychee #15893
Open
Conversation
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
Configures lychee link checker with: - Rate limiting and retry settings - Custom user agent to avoid bot blocking - Cache settings to reduce load on external sites - Ignore patterns for placeholder URLs, localhost, and sites that block automated checkers (Twitter, LinkedIn, etc.) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Uses lychee to validate external links in documentation. Triggers: - Weekly cron (Sunday 2 AM UTC): Creates/updates GitHub issue - Manual dispatch: Optionally fails on broken links - Pull requests: Adds non-blocking comment with report The workflow caches results to reduce load on external sites and does not block PRs (external link failures are often transient or false positives). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Add section explaining the relationship between internal link checking (this script) and external link checking (lychee). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Adds a warn-only pre-commit hook that checks external links in changed markdown files using lychee. The hook: - Only runs on docs/ and develop-docs/ markdown files - Shows warnings but doesn't block commits - Gracefully handles missing lychee installation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Add instructions for running lychee locally and document the pre-commit hook behavior. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Remove separate shell script and use inline bash command with || true to achieve warn-only behavior. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Replace bash one-liner with TypeScript script for Windows compatibility. Uses bun like other scripts in the repo. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Use git diff to get list of changed markdown files for PRs, making the check faster. Full scans still run on schedule and manual dispatch. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
- Add scheme filter to only check http/https (skip root-relative links) - Accept 403/418 status codes (bot blocking, freedesktop teapot) - Add ignore patterns for: - Bot-blocking sites (npmjs, maven, medium, gitlab, epicgames) - Private resources (Notion, private GitHub repos, Zendesk) - Unstable docs (freedesktop) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Set base_url to docs.sentry.io so lychee can resolve root-relative links, then exclude docs.sentry.io from checking (internal links are already covered by lint-404s). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
After manually testing ERROR entries from lychee.log: - bottlepy.org: TLS 1.3 only, incompatible with lychee's native-tls - help.revise.dev: Cloudflare ECH required, fails even with curl - dev.getsentry.net: Internal development URLs - sentry-content-dashboard: Internal dashboard (401) - godoc.org/pkg.go.dev: Rate-limited (429) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Changed from separate entries to using regex optional group (.+@)? to match private IPs with or without credentials (e.g., [email protected]). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Split into two jobs for clarity: - check-pr: PRs only, changed files, adds comment - check-full: Schedule/manual, all files, creates issue Removed caching (wasn't working with per-commit keys). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Rename .lychee.toml to lychee.toml (default config name) - Remove --config args since lychee.toml is auto-detected - Simplify workflow: use '.' instead of listing directories - Split workflow into separate PR and full-scan jobs - Update PR job to update existing comment instead of creating new ones - Update full-scan job to update existing issue instead of creating duplicates - Add file existence checks before reading reports - Use appropriate GitHub labels (Bug, Team: Docs, Product Area: Docs) - Add proper permissions scoping per job 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
6 tasks
Change from types_or: [markdown] to files pattern so both .md and .mdx files are checked locally, matching the CI workflow behavior. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
vaind
added a commit
that referenced
this pull request
Jan 2, 2026
<!-- Use this checklist to make sure your PR is ready for merge. You may delete any sections you don't need. --> ## DESCRIBE YOUR PR Follow up from #15893 Updates various broken external links found by the link checker: - Fix Django REST Framework serializer docs URL - Update Sentry options.py path (master→main, correct directory) - Fix Transifex translation project URL - Replace deprecated Flux docs link with GitHub archive - Fix OpenTelemetry semantic conventions URLs - Update Mailgun documentation URL - Fix Ping Identity documentation URL - Update Flagsmith integration documentation URL - Fix Apple SDK troubleshooting Swift issue reference - Fix Xamarin SSL certificate issue reference - Update Remix meta function documentation links (v1→main) - Fix Next.js custom server documentation URL 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]> ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE --> - [ ] Other deadline: <!-- ENTER DATE HERE --> - [x] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE <!-- Sentry employees and contractors can delete or ignore this section. --> Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) Co-authored-by: Claude Opus 4.5 <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Summary
I've randomely found a broken link in the docs so I went ahead and checked all of them with lychee. There were 54 of them - I've fixed some straightforward ones right away in #15894 and left some ambiguous ones for SDK maintainers who would know better (the summary is part of a weekly or manual workflow run)
This PR adds automated external link checking to catch broken links in documentation using lychee.
What's included
GitHub workflow (
.github/workflows/lint-external-links.yml)Pre-commit hook for local validation (warn-only, doesn't block commits)
Configuration files
lychee.toml- Link checker settings (timeouts, retries, accepted status codes, caching).lycheeignore- URL patterns to ignore (examples, bot-blocking sites, TLS-incompatible sites)Caching strategy
Weekly scheduled runs populate the cache, PR checks consume it:
Current state
There are broken external links in the docs that will need to be fixed separately - this PR just adds the tooling to detect them.
IS YOUR CHANGE URGENT?
PRE-MERGE CHECKLIST