lint-404 fails for develop-docs builds with false-positive docs.sentry.io links

[sentry-junior]

Problem

The lint-404 check consistently fails on PRs that modify develop-docs/**, even when the changed file contains none of the reported links.

Example: #19509
Failed run: https://github.com/getsentry/sentry-docs/actions/runs/35340990882/job/105586605547

What happens

1. CI builds developer docs and starts the local server.
2. The checker requests /api/source-map.
3. The endpoint returns HTML instead of JSON:
   Unexpected token '<', "<!DOCTYPE "... is not valid JSON
4. The checker falls back to checking all 12 sitemap pages.
5. It reports 20 existing docs.sentry.io links as 404s.

These links are external from the perspective of develop.sentry.dev and are unrelated to the PR.

Expected behavior

• /api/source-map returns valid JSON for developer-docs builds.
• Links to docs.sentry.io are treated as external when checking developer docs.
• Unrelated existing links do not block developer-docs PRs.

Possible fix

Run the checker with an explicit developer-docs base/site mode, and avoid rewriting docs.sentry.io URLs to the local developer-docs server.

Related issue

A search found the older, closed issue #10747 about fixing individual developer-docs 404s. This report covers the current checker/source-map failure rather than those historical broken links.

via Ogi.

--

View Junior Session [Sentry]

[linear-code]

DOCS-2955