Advanced docs validation script

[NWylynko]

This is a cut down version of #2041 doing purely the validation aspect. It covers the following things:

Standard docs validation

• Manifest contains correct format and schema
• Failure ❌

// Invalid: Missing required 'href' property
{
  "title": "Getting Started",
  "icon": "rocket"
}

• All guides referenced in manifest exist as files
• Failure ❌

// Invalid: References a non-existent file
{
  "title": "Payment Processing",
  "href": "/docs/payments" // "/docs/payments.mdx" doesn't exist
}

• Frontmatter in each markdown file contains required title
• Failure ❌

// Invalid frontmatter - missing title
---
description: How to get started with our product
---

• Frontmatter is valid yaml
• Failure ❌

// Invalid frontmatter - title starts with a backtick
---
title: `useClerk()`
---

• URLs don't contain characters that need encoding
• Failure ❌

// Invalid URL with spaces
[User Management](/docs/user management)

• Links between guides point to existing documents
• Warning ⚠️

// Invalid link to non-existent document
Learn about [API Rate Limits](/docs/rate-limits) here.

• Hash fragments (#) in links match actual headings
• Warning ⚠️

// Invalid: No "configuration" heading exists in the target document
Check the [Configuration Options](/docs/setup#configuration)

• Files referenced by <Include /> components exist
• Warning ⚠️

// Invalid: References a non-existent partial
<Include src="_partials/troubleshooting.mdx" />

• No nested partials (partials inside partials)
• Failure ❌

// Valid: Simple partial
// In _partials/header.mdx
# Welcome to our docs

// Invalid: Nested partial
// In _partials/page-template.mdx
<Include src="_partials/header.mdx" />
<p>Main content goes here</p>

• <Include /> src props start with "_partials/"
• Warning ⚠️

// Invalid: Incorrect path format
<Include src="code-sample.mdx" />

New SDK Validation

• All SDKs in manifest are valid
• Failure ❌

// Invalid: Contains unrecognized SDK
{
  "title": "React Integration",
  "href": "/docs/react-integration",
  "sdk": ["rreact"] // 'rreact' is not valid
}

• SDK values in frontmatter are valid
• Failure ❌

// Invalid SDK values
---
title: Angular Components
sdk: angular, svelte
---

• <If /> components reference valid SDKs for the guide
• Failure ❌

// Invalid: Guide's frontmatter doesn't include "python"
---
sdk: react, nextjs
---
<If sdk="python">
  Use the Python client: `import auth_client`
</If>

• <If /> components reference SDKs available in manifest
• Failure ❌

// Invalid: Manifest doesn't include this guide for "ruby"
// Manifest entry: { "sdk": ["javascript-frontend", "react"] }
<If sdk="ruby">
  Use Ruby gems
</If>

• Core document paths don't conflict with SDK-specific paths
• Failure ❌

// Invalid - Creates conflict
/docs/react.mdx  // Core document with same name as SDK
/docs/react/index.mdx  // SDK directory structure

[jescalan]

🔪

[jescalan]

Suggested change

	const VALID_SDKS = [
	'nextjs',
	'react',
	'javascript-frontend',
	'chrome-extension',
	'expo',
	'ios',
	'nodejs',
	'expressjs',
	'fastify',
	'react-router',
	'remix',
	'tanstack-start',
	'go',
	'astro',
	'nuxt',
	'vue',
	'ruby',
	'python',
	'javascript-backend',
	'sdk-development',
	'community-sdk',
	] as const
	const VALID_SDKS = [
	'nextjs',
	'react',
	'js-frontend',
	'chrome-extension',
	'expo',
	'ios',
	'nodejs',
	'expressjs',
	'fastify',
	'react-router',
	'remix',
	'tanstack-start',
	'go',
	'astro',
	'nuxt',
	'vue',
	'ruby',
	'python',
	'js-backend',
	'sdk-development',
	'community-sdk',
	] as const