Fix broken and degraded links found by full-content link audit#415
Merged
Conversation
An audit of all 1,264 unique external URLs in published pages found ~45 clickable links that 404 or land on generic pages. mint broken-links cannot catch these (it only validates internal links), so they rotted silently. Fixes: - Own-site links to moved/renamed pages now use relative paths so the linter guards them: reduce-mttd (moved to learn/incidents), synthetic-transaction-monitoring -> transaction-monitoring, guides/setup-scripts -> setup-scripts-for-apis, private-locations, check-results anchors -> /concepts/results, cicd/triggers -> /cli/checkly-trigger, and the mangled cli/overview* slugs in three guides (-> /constructs/* pages) - signup CTA now points at app.checklyhq.com/signup; www.checklyhq.com/signup currently 404s (marketing-site regression, flagged separately) - llms.txt sample in ai/llms-txt.mdx: replaced five .md entries whose pages no longer exist with the three current admin/team-management entries from the live llms.txt - Stale third-party URLs updated: six old-structure playwright.dev paths, OpenTelemetry quickstart, OpenAPI spec guide (learn.openapis.org), OpenAPI membership page, FireHydrant support article (site moved), dead Zoom webinar replaced with a link to Playwright learn resources - Dead example targets in copy-pasteable code: danube-store.herokuapp.com -> danube-web.shop (Heroku app is gone), expired filebin.net bin -> httpbin.org/post (both file-system pages), dead using-pw-test-command URL in the bulk-monitor example arrays; de-linkified the CSV sample table rows that had stray-comma link targets - docs.json: route /monitoring/check-results and /detect/synthetic-monitoring/browser-checks/results to /concepts/results — the existing external redirect chain landed on a page that no longer exists Not fixed here: the Google Sheets template link in platform/reporting/analytics-api.mdx (the shared sheet returns 410 — needs the content owner to restore or replace the asset), and guides/developer-fixtures.mdx which is already fixed in PR #414. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
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
1 participant
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.
Why
An audit of every external URL in the published docs (2,788 occurrences, 1,264 unique, all probed live) found ~45 clickable links that 404 or silently land on generic pages.
mint broken-linksonly validates internal links, so absolute URLs — including absolute links to our own site — rot invisibly.What
Own-site links converted to relative paths (now guarded by
mint broken-linksin CI):learn/monitoring/reduce-mttd→/learn/incidents/reduce-mttd(page moved sections; 3 links)synthetic-transaction-monitoring→/learn/monitoring/transaction-monitoring(3 links)guides/setup-scripts→/guides/setup-scripts-for-apiscli/overviewconstructs-reference/overviewproject-structureslugs already fixed indeveloper-fixtures.mdx(PR Add redirects for legacy ReadMe /reference/* API links #414), found in three more guides →/constructs/*pagescheck-resultsanchors →/concepts/results;/docs/cicd/triggers/(landed on the marketing homepage) →/cli/checkly-trigger; private-locations path →/platform/private-locations/overview; leaked Vercel preview URL →/integrations/iac/terraform/overview;/integrations/→/communicate/alerts/channelsBroken external URLs updated (all replacements verified 200): six old-structure
playwright.devpaths, OpenTelemetry quickstart, OpenAPI spec guide →learn.openapis.org, OpenAPI membership page, FireHydrant support article (site moved domains), dead Zoom webinar registration → Playwright learn resources.Dead targets in copy-pasteable code examples:
danube-store.herokuapp.com→danube-web.shop(Heroku app gone), expiredfilebin.netbin →httpbin.org/post(both file-system pages), dead example URL in the bulk-monitor arrays, de-linkified CSV sample table rows that had stray-comma link targets.ai/llms-txt.mdx: the sample listed five.mdentries whose pages no longer exist (okta,rbac,removing-team-members,saml-sso,scim-provisioning) — replaced with the three current entries from the livellms.txt.docs.json(+2 redirects, inserted mid-array to avoid conflicting with PR #414's appended entries):/monitoring/check-resultsand/detect/synthetic-monitoring/browser-checks/results→/concepts/results. An existing external redirect chain currently lands on the latter path, which no longer exists.Verified
npx mint broken-links: no broken links (validates all new relative links)python3 -m json.tool docs.json: valid; 24 → 26 redirects, no duplicate sourcesKnown issues NOT fixed here
www.checklyhq.com/signupreturns 404 — marketing-site regression; this PR repoints the docs CTA toapp.checklyhq.com/signup, but anyone else linking the old URL is broken. Needs the marketing-site owner.platform/reporting/analytics-api.mdxreturns 410 (sheet deleted) — needs the content owner to restore/replace the asset; a link swap can't fix it.guides/developer-fixtures.mdxstill has its mangled links onmain— fixed in Add redirects for legacy ReadMe /reference/* API links #414, intentionally untouched here.Full audit data (per-URL status + final URL after redirects) available on request.
🤖 Generated with Claude Code