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-of-date URLs):

• https://github.com/clerk/clerk_go/pull/16481 ✅
• chore: Update API Errors #3216 ✅

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
• Reports warnings during build if URLs are invalid
• Auto-generated API error docs (backend-api.mdx, frontend-api.mdx) are excluded from link-doc-not-found warnings since their URLs come from upstream

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
• lint:check-description-backticks - Description backtick check
• lint:check-prompt-deeplink-length - Prompt deeplink length 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
• /docs/guides/development/custom-flows/overview#session-tasks → /docs/guides/development/custom-flows/authentication/session-tasks

Unit tests

Added integration tests for codeblock URL validation in scripts/build-docs.test.ts:

• Warns on non-existent codeblock URLs
• No warning for valid codeblock URLs
• Warns on invalid hash fragments in codeblock URLs
• Validates multiple URLs in a single code block
• Accepts valid hash fragments

Test plan

• Build passes locally with pnpm run build
• Lint passes locally with pnpm run lint:formatting
• Tests pass locally with pnpm run test (excluding pre-existing move-doc.test.ts failures on main)
• Verified codeblock URL validation catches outdated URLs
• API error docs are excluded from codeblock link-not-found warnings

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Ready	Preview	Mar 19, 2026 8:11pm

[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!