Validate codeblock URLs during build and streamline CI lints

[manovotny]

Warning

These upstream changes will need to be merged before the build will pass (because they contain broken or out-od-date urls):

• https://github.com/clerk/clerk_go/pull/16481
• 🔜 Incoming/Automated chore: Update API Errors PR (like this one)

Summary

• Adds build-time validation for clerk.com/docs URLs found in code block comments
• Streamlines CI lint workflow to only run lints that don't require a build
• Fixes outdated documentation URLs

What changed?

Build-time codeblock URL validation

Updated scripts/lib/plugins/validateLinks.ts to validate clerk.com/docs URLs found in code block comments during the build process:

• Scans code blocks for URLs matching https://clerk.com/docs/*
• Validates URLs exist in the built docs directory
• Detects URLs that redirect and suggests the new path
• Preserves hash fragments when checking redirects
• Reports warnings during build if URLs are invalid or outdated

CI workflow changes

Updated .github/workflows/lint.yml to run all lints that don't require a build:

• lint:formatting - Prettier check
• lint:check-frontmatter - Frontmatter validation
• lint:check-duplicate-redirects - Duplicate redirect check
• lint:check-svgs - SVG optimization check
• lint:check-images - Image reference check

Lints requiring a build (lint:check-redirects) are now validated as part of the build process itself.

Fixed URLs

Fixed outdated clerk.com/docs URLs found in code blocks:

• /docs/quickstarts/nextjs → /docs/nextjs/getting-started/quickstart
• /docs/custom-flows/error-handling → /docs/guides/development/custom-flows/error-handling
• /docs/reference/tanstack-react-start/custom-sign-in-or-up-page → /docs/guides/development/custom-sign-in-or-up-page
• /docs/references/backend/types/auth-object → /docs/reference/backend/types/auth-object
• /docs/authentication/enterprise-connections/authentication-flows → /docs/guides/configure/auth-strategies/enterprise-connections/authentication-flows

Test plan

• Build passes locally with pnpm run build
• Lint passes locally with pnpm run lint
• Verified codeblock URL validation catches outdated URLs
• Verified redirect detection works correctly

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Error		Feb 4, 2026 9:53pm

[NWylynko]

In scripts/lib/plugins/validateLinks.ts we already validate standard links and then have a map of all available guides to check against if they exist. Could we just update that to also check in code blocks?

[manovotny]

In scripts/lib/plugins/validateLinks.ts we already validate standard links and then have a map of all available guides to check against if they exist. Could we just update that to also check in code blocks?

Done!