Skip to content

Fixes some 404s and adds routable docs link validation#3197

Merged
manovotny merged 10 commits intomainfrom
manovotny/lizard-aftermath
Mar 23, 2026
Merged

Fixes some 404s and adds routable docs link validation#3197
manovotny merged 10 commits intomainfrom
manovotny/lizard-aftermath

Conversation

@manovotny
Copy link
Copy Markdown
Contributor

@manovotny manovotny commented Mar 9, 2026

🔎 Previews:

  • None

What does this solve? What changed?

  • A broken internal docs link in docs/getting-started/quickstart/overview.mdx was not being caught by the normal pnpm lint path.
  • The root problem was that internal link validation only ran inside the docs build, and it validated against the broad in-memory docsMap, which included synthetic SDK-scoped aliases that do not always correspond to real emitted routes.
  • This PR fixes the broken Chrome Extension JavaScript quickstart link and tightens validation so missing internal doc routes fail correctly.
  • Added lint:check-links so link validation runs as part of the existing lint surface without writing dist/.
  • Split validation to use routable doc URLs rather than synthetic source aliases by introducing a routable docs map during build.
  • Escalated missing internal doc links from warnings to errors so invalid doc links fail the check clearly in CI.
  • Added redirect for /docs/upgrade-guides/core-3/docs/guides/development/upgrading/upgrade-guides/core-3.

Deadline

  • No rush

Other resources

@manovotny manovotny requested a review from a team as a code owner March 9, 2026 22:02
@vercel
Copy link
Copy Markdown

vercel bot commented Mar 9, 2026

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

Project Deployment Actions Updated (UTC)
clerk-docs Ready Ready Preview Mar 23, 2026 4:09pm

Request Review

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@manovotny manovotny changed the title Add routable docs link validation Add routable docs link validation and core-3 redirect Mar 10, 2026
@manovotny manovotny changed the title Add routable docs link validation and core-3 redirect Fixes some 404s and adds routable docs link validation Mar 10, 2026
Comment thread scripts/lib/utils/getRoutableDocHref.ts
Comment thread scripts/lib/error-messages.ts
Comment thread scripts/build-docs.ts Outdated
Comment thread scripts/move-doc.test.ts
Comment thread package.json Outdated
Comment thread scripts/build-docs.ts
- Add JSDoc to getRoutableDocHref explaining its purpose
- Explain what vfileMessage.fatal = true does in safeError
- Document why skipWriteDist still needs temp dir cleanup
- Clarify why routableDocsMap and docsMap are separate maps

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Link validation already runs via pnpm dev and pnpm build, making
a separate lint step redundant.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Comment thread scripts/build-docs.test.ts Outdated
The build already fails on any reporter output (warnings included),
so the severity change was unnecessary. The actual fix that catches
broken links is validating against routableDocsMap instead of docsMap.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@manovotny manovotny merged commit 5293651 into main Mar 23, 2026
9 checks passed
@manovotny manovotny deleted the manovotny/lizard-aftermath branch March 23, 2026 16:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants