radiant-docs 0.1.56 → 0.1.57

package/template/src/lib/validation.ts

@@ -1,2829 +1,8 @@
-import fs from "node:fs";
 import path from "node:path";
-import pkg from "@stoplight/spectral-core";
-const { Spectral } = pkg;
-import { oas } from "@stoplight/spectral-rulesets";
-import { compile } from "@mdx-js/mdx";
-import yaml from "yaml";
-import { docsSchema } from "./frontmatter-schema";
-import {
-  DEFAULT_SHIKI_DARK_THEME,
-  DEFAULT_SHIKI_LIGHT_THEME,
-  SHIKI_BUNDLED_THEME_NAMES,
-  isBundledShikiThemeName,
-} from "./code/shiki-theme-config";
+import { configureDocsValidator } from "radiant-docs-validator";
 
-// --- Configuration Constants ---
-const CWD = process.cwd();
-const DOCS_DIR = path.join(CWD, "src/content/docs");
-const CONFIG_PATH = path.join(DOCS_DIR, "docs.json");
+configureDocsValidator({
+  docsRoot: path.join(process.cwd(), "src/content/docs"),
+});
 
-// Cache for icon sets (key: prefix, value: Set of icon names)
-const iconSets = new Map<string, Set<string>>();
-
-// Helper function to check if a string is a URL
-function isUrl(str: string): boolean {
-  try {
-    const url = new URL(str);
-    return url.protocol === "http:" || url.protocol === "https:";
-  } catch {
-    return false;
-  }
-}
-
-function getIconSet(prefix: string): Set<string> | null {
-  if (iconSets.has(prefix)) return iconSets.get(prefix)!;
-
-  try {
-    const iconsPath = path.join(
-      CWD,
-      `node_modules/@iconify-json/${prefix}/icons.json`,
-    );
-    if (!fs.existsSync(iconsPath)) {
-      return null;
-    }
-    const iconsData = JSON.parse(fs.readFileSync(iconsPath, "utf-8"));
-    const set = new Set(Object.keys(iconsData.icons));
-    iconSets.set(prefix, set);
-    return set;
-  } catch (error) {
-    console.error(`Failed to load icon set for prefix "${prefix}":`, error);
-    return null;
-  }
-}
-
-function validateIcon(icon: any, currentPath: Path): void {
-  if (icon === undefined || icon === null) return;
-
-  if (typeof icon !== "string") {
-    throwConfigError("Icon must be a string.", currentPath);
-  }
-
-  // 1. Handle remote URLs
-  if (isUrl(icon)) {
-    return;
-  }
-
-  // 2. Handle Iconify icons (prefix:name)
-  if (icon.includes(":")) {
-    const parts = icon.split(":");
-
-    if (parts.length !== 2 || !parts[0] || !parts[1]) {
-      throwConfigError(
-        `Invalid library icon format: "${icon}". Icons must follow the "library-prefix:name" format (e.g., "lucide:home") or be a local path.`,
-        currentPath,
-      );
-    }
-
-    const [prefix, name] = parts;
-    const icons = getIconSet(prefix);
-
-    if (icons) {
-      if (!icons.has(name)) {
-        throwConfigError(
-          `Invalid icon name: "${name}" for library "${prefix}". Is this a typo?`,
-          currentPath,
-        );
-      }
-    } else {
-      throwConfigError(
-        `Invalid icon library: "${prefix}". Is this package installed in @iconify-json?`,
-        currentPath,
-      );
-    }
-    return;
-  }
-
-  // 3. Handle local icons
-  // Check if it's a file path (must exist in DOCS_DIR)
-  const localRelativePath = icon.startsWith("/") ? icon.slice(1) : icon;
-  const localPath = path.join(DOCS_DIR, localRelativePath);
-
-  if (!fs.existsSync(localPath)) {
-    throwConfigError(
-      `Icon not found: "${icon}". Local icons must exist in your repository. Did you mean to use an library icon like "lucide:home"?`,
-      currentPath,
-    );
-  }
-}
-
-// Define the list of available user components for MDX
-const AVAILABLE_COMPONENTS = [
-  "Callout",
-  "Tabs",
-  "Tab",
-  "Steps",
-  "Step",
-  "Accordion",
-  "AccordionGroup",
-  "Card",
-  "Column",
-  "Columns",
-  "Image",
-  "CodeGroup",
-  "ComponentPreview",
-];
-
-// Internal components can be valid in MDX while remaining hidden from
-// user-facing error guidance.
-const INTERNAL_ONLY_COMPONENTS = new Set(["ComponentPreview"]);
-
-export type NavPage = {
-  page: string;
-  icon?: string | null;
-  tag?: NavTag;
-  title?: string;
-};
-export type NavOpenApiPageRef = {
-  source: string;
-  endpoint: string;
-};
-export type NavOpenApiPage = {
-  openapi: NavOpenApiPageRef;
-  title?: string;
-  tag?: NavTag;
-};
-export type NavGroup = {
-  group: string;
-  pages: (string | NavPage | NavGroup | NavOpenApiPage)[];
-  icon?: string | null;
-  expanded?: boolean; // need to add this logic
-  tag?: NavTag;
-};
-export type NavOpenApi = {
-  source: string;
-  include?: string[];
-  exclude?: string[];
-};
-export type NavigationItem = {
-  pages?: (string | NavPage | NavGroup | NavOpenApiPage)[];
-  menu?: NavMenu;
-  openapi?: string | NavOpenApi;
-};
-
-export type NavMenuItem = {
-  label: string;
-  submenu: Omit<NavigationItem, "menu">;
-  icon?: string | null;
-};
-export type NavMenu = {
-  type?: "dropdown" | "segmented";
-  label?: string;
-  items: NavMenuItem[];
-};
-export type NavbarItem = {
-  text: string;
-  href: string;
-  icon?: string | null;
-  color?: string | ThemeColorByMode;
-};
-export type HiddenPageRoute = {
-  filePath: string;
-  href: string;
-};
-type InternalPageHrefResolution = HiddenPageRoute & {
-  linkHref: string;
-};
-export type LogoVariant =
-  | string
-  | {
-      image: string;
-      padding?: {
-        top?: number;
-        bottom?: number;
-      };
-    };
-export type Logo = {
-  light?: LogoVariant;
-  dark?: LogoVariant;
-  href?: string;
-  pill?: string | false;
-};
-export type ThemeColorByMode = {
-  light?: string;
-  dark?: string;
-};
-export type NavTag =
-  | string
-  | {
-      text: string;
-      color?: string | ThemeColorByMode;
-    };
-export const BASE_COLOR_OPTIONS = [
-  "slate",
-  "gray",
-  "zinc",
-  "neutral",
-  "stone",
-  "taupe",
-  "mauve",
-  "mist",
-  "olive",
-] as const;
-export type BaseColorOption = (typeof BASE_COLOR_OPTIONS)[number];
-export type BaseColorByMode = {
-  light: BaseColorOption;
-  dark: BaseColorOption;
-};
-export const DEFAULT_THEME_COLOR_LIGHT = "#171717";
-export const DEFAULT_THEME_COLOR_DARK = "#f5f5f5";
-export type CardCoverTheme = {
-  colors?: string[];
-  colorSeed?: string;
-};
-export type CardButtonTheme = {
-  color?: string | ThemeColorByMode;
-};
-export type CardTheme = {
-  cover?: CardCoverTheme;
-  button?: CardButtonTheme;
-};
-export type CodeSyntaxThemeConfig =
-  | string
-  | {
-      light?: string;
-      dark?: string;
-    };
-export type CodeTheme = {
-  syntaxTheme?: CodeSyntaxThemeConfig;
-};
-export type TagTheme = {
-  color?: string | ThemeColorByMode;
-};
-export type DocsTheme = {
-  baseColor?: BaseColorOption | BaseColorByMode;
-  themeColor?: string | ThemeColorByMode;
-  card?: CardTheme;
-  code?: CodeTheme;
-  tag?: TagTheme;
-};
-export type AssistantIcon = {
-  src?: string;
-};
-export type AssistantButtonSize = "small" | "default";
-export type AssistantButtonConfig = {
-  size?: AssistantButtonSize;
-  color?: string | ThemeColorByMode;
-};
-export type AssistantNavbarButtonConfig = {
-  enabled?: boolean;
-  text?: string;
-  color?: string | ThemeColorByMode;
-};
-export type AssistantConfig = {
-  button?: AssistantButtonConfig;
-  navbarButton?: AssistantNavbarButtonConfig;
-  heading?: string;
-  questions?: string[];
-  icon?: AssistantIcon;
-};
-export type DocsConfig = {
-  title: string;
-  logo?: Logo;
-  theme?: DocsTheme;
-  assistant?: AssistantConfig;
-  home?: string;
-  navigation: NavigationItem;
-  navbar?: {
-    blur?: boolean;
-    primary?: NavbarItem;
-    secondary?: NavbarItem;
-    links?: NavbarItem[];
-  };
-  playground?: {
-    proxy?: boolean;
-  };
-  footer?: Footer;
-  hiddenPageRoutes?: HiddenPageRoute[];
-};
-
-export type SocialPlatform =
-  | "x"
-  | "website"
-  | "facebook"
-  | "youtube"
-  | "discord"
-  | "slack"
-  | "github"
-  | "linkedin"
-  | "instagram"
-  | "hacker-news"
-  | "medium"
-  | "telegram"
-  | "bluesky"
-  | "threads"
-  | "reddit"
-  | "podcast";
-export type FooterLink = {
-  text: string;
-  href: string;
-};
-export type Footer = {
-  socials?: Partial<Record<SocialPlatform, string>>;
-  links?: FooterLink[];
-};
-type Path = (string | number)[];
-
-// --- 1. Error Utility ---
-
-const throwConfigError = (message: string, currentPath: Path): never => {
-  const location =
-    currentPath.length > 0 ? ` (at: ${currentPath.join(".")})` : "";
-  throw new Error(`${message}${location}\n`);
-};
-
-// --- 2. Core Validation Logic (Recursive and Structural) ---
-
-// Helper for basic type checks, allowing undefined for optional keys
-function checkType(
-  value: any,
-  type: "string" | "boolean" | "array" | "object",
-  currentPath: Path,
-  label: string,
-): void {
-  if (value === undefined || value === null) return;
-
-  if (type === "array") {
-    if (!Array.isArray(value))
-      throwConfigError(`${label} must be an array.`, currentPath);
-  } else if (type === "object") {
-    if (typeof value !== "object" || value === null)
-      throwConfigError(`${label} must be an object.`, currentPath);
-  } else {
-    if (typeof value !== type)
-      throwConfigError(`${label} must be a ${type}.`, currentPath);
-  }
-}
-
-function normalizeHexColor(
-  value: unknown,
-  currentPath: Path,
-  label: string,
-): string {
-  checkType(value, "string", currentPath, label);
-  if (typeof value !== "string") {
-    throwConfigError(`${label} must be a string.`, currentPath);
-  }
-
-  const trimmedValue = value.trim();
-  if (trimmedValue.length === 0) {
-    throwConfigError(`${label} cannot be empty.`, currentPath);
-  }
-
-  const normalizedValue = trimmedValue.startsWith("#")
-    ? trimmedValue
-    : `#${trimmedValue}`;
-  if (
-    !/^#(?:[A-Fa-f0-9]{3}|[A-Fa-f0-9]{4}|[A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$/.test(
-      normalizedValue,
-    )
-  ) {
-    throwConfigError(
-      `${label} must be a valid hex color (for example: #1d4ed8).`,
-      currentPath,
-    );
-  }
-
-  return normalizedValue.toLowerCase();
-}
-
-function normalizeThemeColorConfig(
-  value: unknown,
-  currentPath: Path,
-  label: string,
-): string | ThemeColorByMode {
-  if (typeof value === "string") {
-    return normalizeHexColor(value, currentPath, label);
-  }
-
-  checkType(value, "object", currentPath, label);
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throwConfigError(
-      `${label} must be a string or an object with light/dark values.`,
-      currentPath,
-    );
-  }
-
-  const colorByMode = value as Record<string, unknown>;
-  const allowedKeys = new Set(["light", "dark"]);
-  for (const key of Object.keys(colorByMode)) {
-    if (!allowedKeys.has(key)) {
-      throwConfigError(`${label} object only supports 'light' and 'dark'.`, [
-        ...currentPath,
-        key,
-      ]);
-    }
-  }
-
-  const light =
-    colorByMode.light !== undefined
-      ? normalizeHexColor(colorByMode.light, [...currentPath, "light"], label)
-      : undefined;
-  const dark =
-    colorByMode.dark !== undefined
-      ? normalizeHexColor(colorByMode.dark, [...currentPath, "dark"], label)
-      : undefined;
-
-  if (light === undefined && dark === undefined) {
-    throwConfigError(
-      `${label} object must include 'light', 'dark', or both.`,
-      currentPath,
-    );
-  }
-
-  return {
-    ...(light !== undefined ? { light } : {}),
-    ...(dark !== undefined ? { dark } : {}),
-  };
-}
-
-function normalizeNavTagConfig(
-  value: unknown,
-  currentPath: Path,
-  label: string,
-): NavTag | undefined {
-  if (value === undefined || value === null) return undefined;
-
-  if (typeof value === "string") {
-    const trimmedText = value.trim();
-    if (trimmedText.length === 0) {
-      throwConfigError(`${label} cannot be empty.`, currentPath);
-    }
-    return trimmedText;
-  }
-
-  checkType(value, "object", currentPath, label);
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throwConfigError(
-      `${label} must be a string or an object with text and optional color.`,
-      currentPath,
-    );
-  }
-
-  const tagConfig = value as Record<string, unknown>;
-  const allowedKeys = new Set(["text", "color"]);
-  for (const key of Object.keys(tagConfig)) {
-    if (!allowedKeys.has(key)) {
-      throwConfigError(`${label} object only supports 'text' and 'color'.`, [
-        ...currentPath,
-        key,
-      ]);
-    }
-  }
-
-  checkType(tagConfig.text, "string", [...currentPath, "text"], `${label} text`);
-  if (typeof tagConfig.text !== "string") {
-    throwConfigError(`${label} text must be a string.`, [
-      ...currentPath,
-      "text",
-    ]);
-  }
-
-  const trimmedText = tagConfig.text.trim();
-  if (trimmedText.length === 0) {
-    throwConfigError(`${label} text cannot be empty.`, [
-      ...currentPath,
-      "text",
-    ]);
-  }
-
-  const color =
-    tagConfig.color !== undefined
-      ? normalizeThemeColorConfig(
-          tagConfig.color,
-          [...currentPath, "color"],
-          `${label} color`,
-        )
-      : undefined;
-
-  return {
-    text: trimmedText,
-    ...(color !== undefined ? { color } : {}),
-  };
-}
-
-function normalizeHexColorArray(
-  value: unknown,
-  currentPath: Path,
-  label: string,
-): string[] {
-  checkType(value, "array", currentPath, label);
-  if (!Array.isArray(value)) {
-    throwConfigError(`${label} must be an array.`, currentPath);
-  }
-
-  if (value.length < 1 || value.length > 4) {
-    throwConfigError(`${label} must include 1 to 4 colors.`, currentPath);
-  }
-
-  return value.map((color, index) =>
-    normalizeHexColor(color, [...currentPath, index], `${label} ${index + 1}`),
-  );
-}
-
-function normalizeSeedValue(
-  value: unknown,
-  currentPath: Path,
-  label: string,
-): string {
-  checkType(value, "string", currentPath, label);
-  if (typeof value !== "string") {
-    throwConfigError(`${label} must be a string.`, currentPath);
-  }
-
-  const trimmedValue = value.trim();
-  if (trimmedValue.length === 0) {
-    throwConfigError(`${label} cannot be empty.`, currentPath);
-  }
-
-  return trimmedValue;
-}
-
-function validateFileExistence(filePath: string, currentPath: Path): void {
-  // Assuming relative path from DOCS_DIR and .mdx extension
-  const fullPath = path.join(DOCS_DIR, `${filePath}.mdx`);
-
-  if (!fs.existsSync(fullPath)) {
-    throwConfigError(
-      `Referenced file not found. Expected: ${filePath}`,
-      currentPath,
-    );
-  }
-}
-
-function normalizeDocsPagePath(
-  value: string,
-  currentPath: Path,
-  label: string = "Page path",
-): string {
-  checkType(value, "string", currentPath, label);
-
-  const trimmedPath = value.trim();
-  if (trimmedPath === "") {
-    throwConfigError(`${label} cannot be an empty string`, currentPath);
-  }
-
-  if (isUrl(trimmedPath)) {
-    throwConfigError(
-      `${label} must reference a documentation page path, not a URL`,
-      currentPath,
-    );
-  }
-
-  const normalizedPath = trimmedPath.replace(/^\/+/, "").replace(/\/+$/, "");
-
-  if (normalizedPath === "") {
-    throwConfigError(`${label} cannot be '/'`, currentPath);
-  }
-
-  return normalizedPath;
-}
-
-function splitHrefPathAndSuffix(href: string): {
-  pathname: string;
-  suffix: string;
-} {
-  const match = href.match(/^([^?#]*)(.*)$/);
-  return {
-    pathname: match?.[1] ?? href,
-    suffix: match?.[2] ?? "",
-  };
-}
-
-function normalizeInternalPageHref(
-  href: string,
-  currentPath: Path,
-  label: string,
-): InternalPageHrefResolution | null {
-  const trimmedHref = href.trim();
-  if (trimmedHref === "") {
-    throwConfigError(`${label} cannot be an empty string`, currentPath);
-  }
-
-  if (isUrl(trimmedHref)) {
-    return null;
-  }
-
-  if (!trimmedHref.startsWith("/")) {
-    throwConfigError(
-      `${label} must be either a valid URL (http:// or https://) or an internal path (starting with /)`,
-      currentPath,
-    );
-  }
-
-  const { pathname, suffix } = splitHrefPathAndSuffix(trimmedHref);
-  const normalizedPathname = pathname.replace(/\/{2,}/g, "/");
-  if (normalizedPathname === "/" || normalizedPathname === "") {
-    return null;
-  }
-
-  const filePath = normalizeDocsPagePath(
-    normalizedPathname,
-    currentPath,
-    label,
-  );
-  validateFileExistence(filePath, currentPath);
-
-  return {
-    filePath,
-    href: `/${filePath}`,
-    linkHref: `/${filePath}${suffix}`,
-  };
-}
-
-// Cache for OpenAPI specs (key: filePathOrUrl, value: parsed spec)
-const openApiSpecCache = new Map<string, any>();
-
-// Helper function to load and parse OpenAPI spec
-export async function loadOpenApiSpec(filePathOrUrl: string): Promise<any> {
-  // Check cache first
-  if (openApiSpecCache.has(filePathOrUrl)) {
-    return openApiSpecCache.get(filePathOrUrl);
-  }
-
-  const isUrlPath = isUrl(filePathOrUrl);
-
-  let fileContent: string;
-
-  if (isUrlPath) {
-    // Fetch from URL
-    try {
-      const response = await fetch(filePathOrUrl);
-      if (!response.ok) {
-        throw new Error(
-          `Failed to fetch OpenAPI spec: ${response.status} ${response.statusText}`,
-        );
-      }
-      fileContent = await response.text();
-    } catch (error) {
-      throw new Error(
-        `Failed to fetch OpenAPI spec from URL: ${
-          error instanceof Error ? error.message : String(error)
-        }`,
-      );
-    }
-  } else {
-    // Read from local file
-    const fullPath = path.join(DOCS_DIR, filePathOrUrl);
-    fileContent = fs.readFileSync(fullPath, "utf-8");
-  }
-
-  // Detect HTML content (common mistake: URL returns HTML page instead of spec)
-  const trimmedContent = fileContent.trim();
-  if (
-    trimmedContent.startsWith("<!DOCTYPE") ||
-    trimmedContent.startsWith("<html")
-  ) {
-    throw new Error(
-      "The URL does not return a valid OpenAPI specification. The URL appears to return HTML instead of JSON or YAML.",
-    );
-  }
-
-  // Determine format and parse
-  let parsedSpec: any;
-  try {
-    if (
-      filePathOrUrl.endsWith(".json") ||
-      (isUrlPath && filePathOrUrl.includes(".json"))
-    ) {
-      parsedSpec = JSON.parse(fileContent);
-    } else {
-      const yaml = await import("yaml");
-      parsedSpec = yaml.parse(fileContent);
-    }
-  } catch (parseError) {
-    if (parseError instanceof SyntaxError) {
-      throw new Error(
-        `The URL does not return a valid OpenAPI specification. Failed to parse as JSON or YAML: ${parseError.message}`,
-      );
-    }
-    throw parseError;
-  }
-
-  // Cache the parsed spec
-  openApiSpecCache.set(filePathOrUrl, parsedSpec);
-
-  return parsedSpec;
-}
-
-async function validateOpenApiFile(filePathOrUrl: string, currentPath: Path) {
-  const isUrlPath = isUrl(filePathOrUrl);
-
-  if (!isUrlPath) {
-    // For local files, validate extension and existence
-    const validExtensions = [".json", ".yaml", ".yml"];
-    const hasValidExtension = validExtensions.some((ext) =>
-      filePathOrUrl.toLowerCase().endsWith(ext),
-    );
-
-    if (!hasValidExtension) {
-      throwConfigError(
-        `OpenAPI file must have a valid extension (.json, .yaml, or .yml). Found: ${filePathOrUrl}`,
-        currentPath,
-      );
-    }
-
-    const fullPath = path.join(DOCS_DIR, filePathOrUrl);
-
-    if (!fs.existsSync(fullPath)) {
-      throwConfigError(
-        `Referenced OpenAPI file not found. Expected: ${filePathOrUrl}`,
-        currentPath,
-      );
-    }
-  } else {
-    // For URLs, validate that it's a valid HTTP/HTTPS URL
-    try {
-      const url = new URL(filePathOrUrl);
-      if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throwConfigError(
-          `OpenAPI URL must use http:// or https:// protocol. Found: ${filePathOrUrl}`,
-          currentPath,
-        );
-      }
-    } catch (error) {
-      throwConfigError(
-        `Invalid OpenAPI URL format: ${filePathOrUrl}`,
-        currentPath,
-      );
-    }
-  }
-
-  // Validate the OpenAPI spec using Spectral (works for both files and URLs)
-  try {
-    const document = await loadOpenApiSpec(filePathOrUrl);
-    const tolerantRuleset = {
-      ...oas,
-      rules: {
-        ...oas.rules,
-        "oas3-schema": {
-          ...oas.rules["oas3-schema"],
-          severity: 1,
-        },
-        "oas2-schema": {
-          ...oas.rules["oas2-schema"],
-          severity: 1,
-        },
-      },
-    };
-
-    const spectral = new Spectral();
-
-    spectral.setRuleset(tolerantRuleset);
-
-    let results = await spectral.run(document);
-    const blockingResults = results.filter(
-      (result) => result.code === "unrecognized-format",
-    );
-
-    if (blockingResults.length > 0) {
-      const errorMessages = blockingResults.slice(0, 5).map((result) => {
-        const pathStr = result.path.length > 0 ? result.path.join(".") : "root";
-        return `${result.message} (at ${pathStr})`;
-      });
-
-      const errorText = errorMessages.join("; ");
-      const moreErrors =
-        blockingResults.length > 5
-          ? ` (and ${blockingResults.length - 5} more errors)`
-          : "";
-
-      throwConfigError(
-        `Invalid OpenAPI specification: ${errorText}${moreErrors}`,
-        currentPath,
-      );
-    }
-
-    const nonBlockingResults = results.filter(
-      (result) => result.severity !== 0,
-    );
-
-    if (nonBlockingResults.length > 0) {
-      const warningMessages = nonBlockingResults.slice(0, 5).map((result) => {
-        const pathStr = result.path.length > 0 ? result.path.join(".") : "root";
-        return `${result.message} (at ${pathStr})`;
-      });
-
-      const warningText = warningMessages.join("; ");
-      const moreWarnings =
-        nonBlockingResults.length > warningMessages.length
-          ? ` (and ${
-              nonBlockingResults.length - warningMessages.length
-            } more warnings)`
-          : "";
-      const sourcePath =
-        currentPath.length > 0 ? ` (at: ${currentPath.join(".")})` : "";
-
-      console.warn(
-        `[OPENAPI_VALIDATION_WARNING] ${warningText}${moreWarnings}${sourcePath}`,
-      );
-    }
-  } catch (error) {
-    // Handle parsing errors separately from validation errors
-    if (error instanceof SyntaxError) {
-      throwConfigError(
-        `Failed to parse OpenAPI file: ${error.message}`,
-        currentPath,
-      );
-    } else if (error instanceof Error) {
-      const baseMessage = error.message || String(error);
-      const prefixedMessage = baseMessage.startsWith(
-        "Invalid OpenAPI specification:",
-      )
-        ? baseMessage
-        : `Invalid OpenAPI specification: ${baseMessage}`;
-      throwConfigError(prefixedMessage, currentPath);
-    } else {
-      throwConfigError(
-        `Invalid OpenAPI specification: ${String(error)}`,
-        currentPath,
-      );
-    }
-  }
-}
-
-function extractAvailableEndpoints(openApiDoc: any): Set<string> {
-  const endpoints = new Set<string>();
-  const paths = openApiDoc.paths || {};
-  const httpMethods = [
-    "get",
-    "post",
-    "put",
-    "delete",
-    "patch",
-    "head",
-    "options",
-    "trace",
-  ];
-
-  for (const [pathStr, pathItem] of Object.entries(paths)) {
-    if (!pathItem || typeof pathItem !== "object") continue;
-
-    for (const method of httpMethods) {
-      const operation = (pathItem as any)[method];
-      if (operation) {
-        // Store as "METHOD /path" (uppercase method, lowercase path)
-        const normalizedMethod = method.toUpperCase();
-        const normalizedPath = pathStr.toLowerCase();
-        endpoints.add(`${normalizedMethod} ${normalizedPath}`);
-      }
-    }
-  }
-
-  return endpoints;
-}
-
-// Helper function to parse endpoint string (e.g., "get /burgers" or "POST /burgers")
-function parseEndpointString(
-  endpointStr: string,
-): { method: string; path: string } | null {
-  const trimmed = endpointStr.trim();
-  const parts = trimmed.split(/\s+/);
-
-  if (parts.length !== 2) {
-    return null;
-  }
-
-  const method = parts[0].toUpperCase();
-  let path = parts[1];
-
-  // Ensure path starts with /
-  if (!path.startsWith("/")) {
-    path = "/" + path;
-  }
-
-  // Normalize path to lowercase for comparison
-  const normalizedPath = path.toLowerCase();
-
-  return { method, path: normalizedPath };
-}
-
-async function validateNavOpenApiPage(
-  navOpenApiPage: any,
-  currentPath: Path,
-): Promise<void> {
-  checkType(navOpenApiPage, "object", currentPath, "Open API page");
-
-  if (typeof navOpenApiPage.source !== "string") {
-    throwConfigError(
-      "Open API page must include a 'source' property that is a string.",
-      [...currentPath, "source"],
-    );
-  }
-
-  if (typeof navOpenApiPage.endpoint !== "string") {
-    throwConfigError(
-      "Open API page must include an 'endpoint' property that is a string in the format \"METHOD /path\".",
-      [...currentPath, "endpoint"],
-    );
-  }
-
-  const parsedEndpoint = parseEndpointString(navOpenApiPage.endpoint);
-  if (!parsedEndpoint) {
-    throwConfigError(
-      `Open API page endpoint must be in the format "METHOD /path". Found: ${navOpenApiPage.endpoint}`,
-      [...currentPath, "endpoint"],
-    );
-  }
-
-  await validateOpenApiFile(navOpenApiPage.source, [...currentPath, "source"]);
-
-  const openApiDoc = await loadOpenApiSpec(navOpenApiPage.source);
-  const availableEndpoints = extractAvailableEndpoints(openApiDoc);
-  const endpointKey = `${parsedEndpoint!.method} ${parsedEndpoint!.path}`;
-
-  if (!availableEndpoints.has(endpointKey)) {
-    throwConfigError(
-      `Open API page endpoint does not match any endpoint in the OpenAPI spec. Found: ${navOpenApiPage.endpoint}. Expected format: "METHOD /path".`,
-      [...currentPath, "endpoint"],
-    );
-  }
-}
-
-async function validateNavigationNode(
-  item: any,
-  currentPath: Path,
-  groupDepth: number = 0,
-): Promise<void> {
-  // A) Base Case: Simple string path
-  if (typeof item === "string") {
-    const normalizedPath = normalizeDocsPagePath(item, currentPath);
-    validateFileExistence(normalizedPath, currentPath);
-    return;
-  }
-
-  // B) Must be an object
-  checkType(item, "object", currentPath, "Navigation item");
-
-  // Determine item type by key presence (Strict XOR enforcement)
-  const isGroup = "group" in item;
-  const isPage = "page" in item;
-  const isOpenApiPage = "openapi" in item;
-
-  const typeCount = [isGroup, isPage, isOpenApiPage].filter(Boolean).length;
-  if (typeCount !== 1) {
-    throwConfigError(
-      "Object must contain exactly one key: 'page', 'group', or 'openapi'.",
-      currentPath,
-    );
-  }
-
-  // --- Validate Group (Recursive) ---
-  if (isGroup) {
-    const path = [...currentPath];
-
-    // Enforce max group nesting depth of 2
-    if (groupDepth >= 2) {
-      throwConfigError("Groups can only be nested up to 2 levels deep.", path);
-    }
-
-    checkType(item.group, "string", [...path, "group"], "Group name");
-
-    // C.2: THE EXPANDED CHECK (Kept clean)
-    checkType(item.expanded, "boolean", [...path, "expanded"], "Expanded");
-
-    validateIcon(item.icon, [...path, "icon"]);
-    item.tag = normalizeNavTagConfig(item.tag, [...path, "tag"], "Group tag");
-
-    // Check if pages array exists and validate children
-    if (!item.pages)
-      throwConfigError("Group must have a 'pages' array.", [...path, "pages"]);
-    checkType(item.pages, "array", [...path, "pages"], "Group pages");
-
-    for (const [i, child] of item.pages.entries()) {
-      if (typeof child === "string") {
-        const childPath = [...path, "pages", i];
-        const normalizedPagePath = normalizeDocsPagePath(child, childPath);
-        item.pages[i] = normalizedPagePath;
-        validateFileExistence(normalizedPagePath, childPath);
-        continue;
-      }
-
-      await validateNavigationNode(
-        child,
-        [...path, "pages", i],
-        groupDepth + 1,
-      );
-    }
-    return;
-  }
-
-  // --- Validate Page ---
-  if (isPage) {
-    const path = [...currentPath];
-    const normalizedPagePath = normalizeDocsPagePath(item.page, [
-      ...path,
-      "page",
-    ]);
-    item.page = normalizedPagePath;
-    validateFileExistence(normalizedPagePath, [...path, "page"]);
-
-    validateIcon(item.icon, [...path, "icon"]);
-
-    // Validate optional title
-    checkType(item.title, "string", [...path, "title"], "Page title");
-    item.tag = normalizeNavTagConfig(item.tag, [...path, "tag"], "Page tag");
-
-    // Check D.2/D.3: Page cannot have group properties
-    if ("expanded" in item)
-      throwConfigError("Page items cannot have 'expanded'.", [
-        ...path,
-        "expanded",
-      ]);
-    if ("pages" in item)
-      throwConfigError("Page items cannot have children.", [...path, "pages"]);
-    return;
-  }
-
-  if (isOpenApiPage) {
-    const path = [...currentPath];
-
-    if ("icon" in item) {
-      throwConfigError(
-        "Open API page items cannot have an 'icon'. Method badges are displayed automatically.",
-        [...path, "icon"],
-      );
-    }
-
-    await validateNavOpenApiPage(item.openapi, [...path, "openapi"]);
-    checkType(item.title, "string", [...path, "title"], "Open API page title");
-    item.tag = normalizeNavTagConfig(
-      item.tag,
-      [...path, "tag"],
-      "Open API page tag",
-    );
-
-    if ("expanded" in item)
-      throwConfigError("Open API page items cannot have 'expanded'.", [
-        ...path,
-        "expanded",
-      ]);
-    if ("pages" in item)
-      throwConfigError("Open API page items cannot have children.", [
-        ...path,
-        "pages",
-      ]);
-    if ("group" in item)
-      throwConfigError("Open API page items cannot have 'group'.", [
-        ...path,
-        "group",
-      ]);
-    if ("page" in item)
-      throwConfigError("Open API page items cannot have 'page'.", [
-        ...path,
-        "page",
-      ]);
-    return;
-  }
-}
-
-function getFirstPagePathFromPageItems(
-  items: (string | NavPage | NavGroup | NavOpenApiPage)[],
-): string | undefined {
-  for (const item of items) {
-    if (typeof item === "string") {
-      return item;
-    }
-
-    if ("page" in item) {
-      return item.page;
-    }
-
-    if ("group" in item) {
-      const nestedPath = getFirstPagePathFromPageItems(item.pages);
-      if (nestedPath) {
-        return nestedPath;
-      }
-    }
-  }
-
-  return undefined;
-}
-
-function getFirstPagePathFromNavigation(
-  navigation: DocsConfig["navigation"],
-): string | undefined {
-  if (navigation.pages) {
-    return getFirstPagePathFromPageItems(navigation.pages);
-  }
-
-  if (navigation.menu) {
-    for (const menuItem of navigation.menu.items) {
-      const submenuPages = menuItem.submenu.pages;
-      if (!submenuPages) {
-        continue;
-      }
-
-      const firstPath = getFirstPagePathFromPageItems(submenuPages);
-      if (firstPath) {
-        return firstPath;
-      }
-    }
-  }
-
-  return undefined;
-}
-
-async function validateNavOpenApi(
-  navOpenApi: any,
-  currentPath: Path,
-): Promise<void> {
-  checkType(navOpenApi, "object", currentPath, "Open API object");
-
-  // Required: source (must be a string)
-  if (typeof navOpenApi.source !== "string") {
-    throwConfigError(
-      "Open API object must have an 'source' property that is a string.",
-      [...currentPath, "source"],
-    );
-  }
-
-  // Validate the OpenAPI file exists and is valid
-  await validateOpenApiFile(navOpenApi.source, [...currentPath, "source"]);
-
-  // Check mutual exclusivity of include and exclude
-  const hasInclude = "include" in navOpenApi;
-  const hasExclude = "exclude" in navOpenApi;
-
-  if (hasInclude && hasExclude) {
-    throwConfigError(
-      "Open API object cannot have both 'include' and 'exclude' properties. They are mutually exclusive.",
-      currentPath,
-    );
-  }
-
-  // If neither include nor exclude is present, that's valid (all endpoints will be included)
-  if (!hasInclude && !hasExclude) {
-    return;
-  }
-
-  // Load the OpenAPI spec to validate against
-  const openApiDoc = await loadOpenApiSpec(navOpenApi.source);
-  const availableEndpoints = extractAvailableEndpoints(openApiDoc);
-
-  // Validate include array
-  if (hasInclude) {
-    checkType(
-      navOpenApi.include,
-      "array",
-      [...currentPath, "include"],
-      "Include array",
-    );
-
-    if (navOpenApi.include.length === 0) {
-      throwConfigError("Include array cannot be empty.", [
-        ...currentPath,
-        "include",
-      ]);
-    }
-
-    // Validate each entry
-    for (const [i, entry] of navOpenApi.include.entries()) {
-      if (typeof entry !== "string") {
-        throwConfigError(
-          `Include entry at index ${i} must be a string in the format "METHOD /path".`,
-          [...currentPath, "include", i],
-        );
-      }
-
-      const parsed = parseEndpointString(entry);
-      if (!parsed) {
-        throwConfigError(
-          `Include entry at index ${i} must be in the format "METHOD /path". Found: ${entry}`,
-          [...currentPath, "include", i],
-        );
-      }
-
-      // Check if endpoint exists in the OpenAPI spec
-      const endpointKey = `${parsed?.method} ${parsed?.path}`;
-      if (!availableEndpoints.has(endpointKey)) {
-        throwConfigError(
-          `Include entry at index ${i} does not match any endpoint in the OpenAPI spec. Found: ${entry}. Expected format: "METHOD /path".`,
-          [...currentPath, "include", i],
-        );
-      }
-    }
-  }
-
-  // Validate exclude array
-  if (hasExclude) {
-    checkType(
-      navOpenApi.exclude,
-      "array",
-      [...currentPath, "exclude"],
-      "Exclude array",
-    );
-
-    if (navOpenApi.exclude.length === 0) {
-      throwConfigError("Exclude array cannot be empty.", [
-        ...currentPath,
-        "exclude",
-      ]);
-    }
-
-    // Validate each entry
-    for (const [i, entry] of navOpenApi.exclude.entries()) {
-      if (typeof entry !== "string") {
-        throwConfigError(
-          `Exclude entry at index ${i} must be a string in the format "METHOD /path".`,
-          [...currentPath, "exclude", i],
-        );
-      }
-
-      const parsed = parseEndpointString(entry);
-      if (!parsed) {
-        throwConfigError(
-          `Exclude entry at index ${i} must be in the format "METHOD /path" (e.g., "get /burgers"). Found: ${entry}`,
-          [...currentPath, "exclude", i],
-        );
-      }
-
-      // Check if endpoint exists in the OpenAPI spec
-      const endpointKey = `${parsed?.method} ${parsed?.path}`;
-      if (!availableEndpoints.has(endpointKey)) {
-        throwConfigError(
-          `Exclude entry at index ${i} does not match any endpoint in the OpenAPI spec. Found: ${entry}. Expected format: "METHOD /path" (case-insensitive).`,
-          [...currentPath, "exclude", i],
-        );
-      }
-    }
-  }
-}
-
-async function validateNavMenuItem(item: NavMenuItem, currentPath: Path) {
-  checkType(item, "object", currentPath, "Menu item");
-
-  validateIcon(item.icon, [...currentPath, "icon"]);
-
-  // Required: label
-  if (!item.label) {
-    throwConfigError("Menu item must have a 'label' property.", [
-      ...currentPath,
-      "label",
-    ]);
-  }
-  checkType(item.label, "string", [...currentPath, "label"], "Label");
-
-  // Required: submenu
-  if (!item.submenu) {
-    throwConfigError("Menu item must have a 'submenu' property.", [
-      ...currentPath,
-      "submenu",
-    ]);
-  }
-  checkType(item.submenu, "object", [...currentPath, "submenu"], "Submenu");
-
-  const submenu = item.submenu;
-  const submenuKeys = Object.keys(submenu);
-  const validSubmenuKeys = ["pages", "openapi"];
-  const presentSubmenuKeys = submenuKeys.filter((key) =>
-    validSubmenuKeys.includes(key),
-  );
-  const invalidSubmenuKeys = submenuKeys.filter(
-    (key) => !validSubmenuKeys.includes(key),
-  );
-
-  // Submenu must have exactly one key total
-  if (submenuKeys.length !== 1) {
-    if (submenuKeys.length === 0) {
-      throwConfigError(
-        `Submenu must contain exactly one key (${validSubmenuKeys.join(
-          ", ",
-        )}). Found no keys.`,
-        [...currentPath, "submenu"],
-      );
-    } else {
-      throwConfigError(
-        `Submenu must contain exactly one key (${validSubmenuKeys.join(
-          ", ",
-        )}). Found ${submenuKeys.length} key(s): ${submenuKeys.join(", ")}.`,
-        [...currentPath, "submenu"],
-      );
-    }
-  }
-
-  // Check if the single key is valid
-  if (presentSubmenuKeys.length !== 1) {
-    const invalidKey = invalidSubmenuKeys[0];
-    throwConfigError(
-      `Submenu must contain exactly one key (${validSubmenuKeys.join(
-        ", ",
-      )}). Found invalid key: ${invalidKey}.`,
-      [...currentPath, "submenu"],
-    );
-  }
-
-  const submenuKey = presentSubmenuKeys[0];
-  const submenuValue =
-    submenu[submenuKey as keyof Omit<NavigationItem, "menu">];
-
-  // Validate pages array
-  if (submenuKey === "pages") {
-    checkType(
-      submenuValue,
-      "array",
-      [...currentPath, "submenu", "pages"],
-      "Submenu pages",
-    );
-    const pages = (submenuValue as NavigationItem["pages"]) ?? [];
-    for (const [i, item] of pages.entries()) {
-      const itemPath = [...currentPath, "submenu", "pages", i];
-      if (typeof item === "string") {
-        const normalizedPagePath = normalizeDocsPagePath(item, itemPath);
-        (submenuValue as (string | NavPage | NavGroup | NavOpenApiPage)[])[i] =
-          normalizedPagePath;
-        validateFileExistence(normalizedPagePath, itemPath);
-      } else {
-        await validateNavigationNode(item, itemPath);
-      }
-    }
-  }
-
-  // Validate openapi - can be string or NavOpenApi object
-  if (submenuKey === "openapi") {
-    if (typeof submenuValue === "string") {
-      // Simple string case - validate file exists and is valid
-      await validateOpenApiFile(submenuValue, [
-        ...currentPath,
-        "submenu",
-        "openapi",
-      ]);
-    } else if (typeof submenuValue === "object") {
-      // NavOpenApi object case - validate structure and include/exclude
-      await validateNavOpenApi(submenuValue, [
-        ...currentPath,
-        "submenu",
-        "openapi",
-      ]);
-    } else {
-      throwConfigError(
-        "OpenAPI must be either a string (file path or hosted file) or an object.",
-        [...currentPath, "submenu", "openapi"],
-      );
-    }
-  }
-}
-
-async function validateNavMenu(menu: any, currentPath: Path) {
-  checkType(menu, "object", currentPath, "Menu");
-
-  // Optional: type
-  if (menu.type !== undefined) {
-    if (menu.type !== "dropdown" && menu.type !== "segmented") {
-      throwConfigError(
-        "Menu type must be 'dropdown' or 'segmented' if provided. Defaults to 'dropdown'",
-        [...currentPath, "type"],
-      );
-    }
-  }
-
-  // Optional: label
-  checkType(menu.label, "string", [...currentPath, "label"], "Menu label");
-
-  // Required: items
-  if (!menu.items) {
-    throwConfigError("Menu must have an 'items' array.", [
-      ...currentPath,
-      "items",
-    ]);
-  }
-  checkType(menu.items, "array", [...currentPath, "items"], "Menu items");
-
-  // Validate each menu item
-  for (const [i, item] of menu.items.entries()) {
-    await validateNavMenuItem(item, [...currentPath, "items", i]);
-  }
-}
-
-function validateNavbarItem(
-  item: any,
-  currentPath: Path,
-): HiddenPageRoute | null {
-  // Check if object exists, otherwise we skip (it's optional)
-  if (item === undefined) return null;
-
-  checkType(item, "object", currentPath, "Navbar item");
-
-  // Required properties
-  if (typeof item.text !== "string") {
-    throwConfigError("Navbar item must have a 'text' property.", [
-      ...currentPath,
-      "text",
-    ]);
-  }
-  if (typeof item.href !== "string") {
-    throwConfigError("Navbar item must have an 'href' property.", [
-      ...currentPath,
-      "href",
-    ]);
-  }
-
-  const hiddenPageRoute = normalizeInternalPageHref(
-    item.href,
-    [...currentPath, "href"],
-    "Navbar item href",
-  );
-  if (hiddenPageRoute) {
-    item.href = hiddenPageRoute.linkHref;
-  }
-
-  // Optional property
-  validateIcon(item.icon, [...currentPath, "icon"]);
-  if (item.color !== undefined) {
-    if (currentPath[0] !== "navbar" || currentPath[1] !== "primary") {
-      throwConfigError(
-        "Navbar item color is only supported on navbar.primary.",
-        [...currentPath, "color"],
-      );
-    }
-
-    item.color = normalizeThemeColorConfig(
-      item.color,
-      [...currentPath, "color"],
-      "Navbar primary color",
-    );
-  }
-
-  return hiddenPageRoute;
-}
-
-// --- Top-Level Validation Functions (Your Clean API) ---
-
-function validateTitle(title: DocsConfig["title"]) {
-  checkType(title, "string", ["title"], "Title");
-  if (!title) throwConfigError("Title is missing.", ["title"]);
-}
-
-function validateLogoPaddingValue(
-  value: unknown,
-  currentPath: Path,
-  label: string,
-): void {
-  if (value === undefined) return;
-
-  if (typeof value !== "number" || !Number.isFinite(value)) {
-    throwConfigError(`${label} must be a finite number.`, currentPath);
-  }
-
-  const numericValue = value as number;
-  if (numericValue < 0) {
-    throwConfigError(`${label} cannot be negative.`, currentPath);
-  }
-}
-
-function validateLogoImagePath(
-  imagePath: string,
-  currentPath: Path,
-  label: string,
-): void {
-  const validExtensions = [".svg", ".png", ".jpg", ".jpeg", ".webp", ".gif"];
-  const hasValidExtension = validExtensions.some((ext) =>
-    imagePath.toLowerCase().endsWith(ext),
-  );
-  if (!hasValidExtension) {
-    throwConfigError(
-      `${label} must be a valid image file (.svg, .png, .jpg, .jpeg, .webp, .gif)`,
-      currentPath,
-    );
-  }
-
-  const normalizedPath = imagePath.startsWith("/")
-    ? imagePath.slice(1)
-    : imagePath;
-  const fullPath = path.join(DOCS_DIR, normalizedPath);
-
-  if (!fs.existsSync(fullPath)) {
-    throwConfigError(
-      `${label} file not found. Expected: ${normalizedPath}`,
-      currentPath,
-    );
-  }
-}
-
-function validateAssistantIconSource(
-  iconSource: unknown,
-  currentPath: Path,
-): string {
-  checkType(iconSource, "string", currentPath, "Assistant icon source");
-  if (typeof iconSource !== "string") {
-    throwConfigError("Assistant icon source must be a string.", currentPath);
-  }
-
-  const trimmedSource = iconSource.trim();
-  if (trimmedSource.length === 0) {
-    throwConfigError("Assistant icon source cannot be empty.", currentPath);
-  }
-
-  if (isUrl(trimmedSource)) {
-    throwConfigError(
-      "Assistant icon source must be a local image path relative to docs.json.",
-      currentPath,
-    );
-  }
-
-  if (trimmedSource.includes(":")) {
-    throwConfigError(
-      `Invalid assistant icon source: "${trimmedSource}". Assistant icons must be local image files, not Iconify icon names.`,
-      currentPath,
-    );
-  }
-
-  if (
-    trimmedSource.startsWith("//") ||
-    trimmedSource.startsWith("#") ||
-    trimmedSource.startsWith("?") ||
-    trimmedSource.startsWith("./") ||
-    trimmedSource.startsWith("../")
-  ) {
-    throwConfigError(
-      "Assistant icon source must be a local image path relative to docs.json.",
-      currentPath,
-    );
-  }
-
-  const parsed = new URL(trimmedSource, "https://docs.invalid/");
-  const validExtensions = [
-    ".svg",
-    ".png",
-    ".jpg",
-    ".jpeg",
-    ".webp",
-    ".gif",
-    ".ico",
-    ".avif",
-  ];
-  const hasValidExtension = validExtensions.some((ext) =>
-    parsed.pathname.toLowerCase().endsWith(ext),
-  );
-  if (!hasValidExtension) {
-    throwConfigError(
-      "Assistant icon source must be a valid image file (.svg, .png, .jpg, .jpeg, .webp, .gif, .ico, .avif).",
-      currentPath,
-    );
-  }
-
-  const normalizedPath = parsed.pathname.replace(/^\/+/, "");
-  const fullPath = path.join(DOCS_DIR, normalizedPath);
-
-  if (!fs.existsSync(fullPath)) {
-    throwConfigError(
-      `Assistant icon source file not found. Expected: ${normalizedPath}`,
-      currentPath,
-    );
-  }
-
-  return trimmedSource;
-}
-
-function validateLogoVariant(
-  variant: LogoVariant | undefined,
-  currentPath: Path,
-  mode: "light" | "dark",
-): void {
-  if (variant === undefined) return;
-
-  if (typeof variant === "string") {
-    validateLogoImagePath(variant, currentPath, `Logo ${mode}`);
-    return;
-  }
-
-  if (
-    typeof variant !== "object" ||
-    variant === null ||
-    Array.isArray(variant)
-  ) {
-    throwConfigError(
-      `Logo ${mode} must be a string path or an object with 'image' and optional 'padding'.`,
-      currentPath,
-    );
-  }
-
-  const supportedKeys = new Set(["image", "padding"]);
-  for (const key of Object.keys(variant)) {
-    if (!supportedKeys.has(key)) {
-      throwConfigError(
-        `Logo ${mode} object only supports 'image' and 'padding'.`,
-        [...currentPath, key],
-      );
-    }
-  }
-
-  if (typeof variant.image !== "string") {
-    throwConfigError(`Logo ${mode} object must include an 'image' string.`, [
-      ...currentPath,
-      "image",
-    ]);
-  }
-
-  validateLogoImagePath(
-    variant.image,
-    [...currentPath, "image"],
-    `Logo ${mode} image`,
-  );
-
-  if (variant.padding === undefined) return;
-
-  if (
-    typeof variant.padding !== "object" ||
-    variant.padding === null ||
-    Array.isArray(variant.padding)
-  ) {
-    throwConfigError(
-      `Logo ${mode} padding must be an object with optional 'top' and 'bottom'.`,
-      [...currentPath, "padding"],
-    );
-  }
-
-  const paddingKeys = Object.keys(variant.padding);
-  for (const key of paddingKeys) {
-    if (key !== "top" && key !== "bottom") {
-      throwConfigError(
-        `Logo ${mode} padding only supports 'top' and 'bottom'.`,
-        [...currentPath, "padding", key],
-      );
-    }
-  }
-
-  validateLogoPaddingValue(
-    variant.padding.top,
-    [...currentPath, "padding", "top"],
-    `Logo ${mode} padding top`,
-  );
-  validateLogoPaddingValue(
-    variant.padding.bottom,
-    [...currentPath, "padding", "bottom"],
-    `Logo ${mode} padding bottom`,
-  );
-}
-
-function validateLogo(logo: DocsConfig["logo"]) {
-  // Logo is optional, so if it's undefined, we're done
-  if (logo === undefined) return;
-
-  // If logo is provided, it must be an object
-  checkType(logo, "object", ["logo"], "Logo configuration");
-
-  validateLogoVariant(logo.light, ["logo", "light"], "light");
-  validateLogoVariant(logo.dark, ["logo", "dark"], "dark");
-
-  // Validate 'href' if provided
-  if (logo.href !== undefined) {
-    checkType(logo.href, "string", ["logo", "href"], "Logo href");
-
-    // Validate it's either a valid URL or a valid internal path
-    // Internal paths should start with /
-    // External URLs should start with http:// or https://
-    const trimmedHref = logo.href.trim();
-
-    if (trimmedHref === "") {
-      throwConfigError("Logo href cannot be an empty string", ["logo", "href"]);
-    }
-
-    // Check if it's a URL
-    const isUrl =
-      trimmedHref.startsWith("http://") || trimmedHref.startsWith("https://");
-
-    // Check if it's an internal path (starts with /)
-    const isInternalPath = trimmedHref.startsWith("/");
-
-    if (!isUrl && !isInternalPath) {
-      throwConfigError(
-        "Logo href must be either a valid URL (http:// or https://) or an internal path (starting with /)",
-        ["logo", "href"],
-      );
-    }
-  }
-
-  if (logo.pill !== undefined) {
-    if (typeof logo.pill === "string") {
-      if (logo.pill.trim() === "") {
-        throwConfigError(
-          "Logo pill text cannot be an empty string. Use false to hide the pill.",
-          ["logo", "pill"],
-        );
-      }
-    } else if (logo.pill !== false) {
-      throwConfigError("Logo pill must be a string or false.", [
-        "logo",
-        "pill",
-      ]);
-    }
-  }
-}
-
-function validateTheme(theme: DocsConfig["theme"]): void {
-  if (theme === undefined) return;
-
-  checkType(theme, "object", ["theme"], "Theme configuration");
-  if (typeof theme !== "object" || theme === null || Array.isArray(theme)) {
-    throwConfigError("Theme configuration must be an object.", ["theme"]);
-  }
-
-  const normalizeBaseColor = (
-    value: unknown,
-    currentPath: Path,
-    label: string,
-  ): BaseColorOption => {
-    checkType(value, "string", currentPath, label);
-    if (typeof value !== "string") {
-      throwConfigError(`${label} must be a string.`, currentPath);
-    }
-
-    const normalizedBaseColor = (value as string).trim().toLowerCase();
-    if (normalizedBaseColor.length === 0) {
-      throwConfigError(`${label} cannot be empty.`, currentPath);
-    }
-
-    if (!BASE_COLOR_OPTIONS.includes(normalizedBaseColor as BaseColorOption)) {
-      throwConfigError(
-        `${label} must be one of: ${BASE_COLOR_OPTIONS.join(", ")}.`,
-        currentPath,
-      );
-    }
-
-    return normalizedBaseColor as BaseColorOption;
-  };
-
-  if (theme.baseColor !== undefined) {
-    if (typeof theme.baseColor === "string") {
-      theme.baseColor = normalizeBaseColor(
-        theme.baseColor,
-        ["theme", "baseColor"],
-        "Theme base color",
-      );
-    } else {
-      checkType(
-        theme.baseColor,
-        "object",
-        ["theme", "baseColor"],
-        "Theme base color",
-      );
-      if (
-        typeof theme.baseColor !== "object" ||
-        theme.baseColor === null ||
-        Array.isArray(theme.baseColor)
-      ) {
-        throwConfigError(
-          "Theme base color must be a string or an object with light/dark values.",
-          ["theme", "baseColor"],
-        );
-      }
-
-      const baseColorByMode = theme.baseColor as Record<string, unknown>;
-      const allowedKeys = new Set(["light", "dark"]);
-      for (const key of Object.keys(baseColorByMode)) {
-        if (!allowedKeys.has(key)) {
-          throwConfigError(
-            "Theme base color object only supports 'light' and 'dark'.",
-            ["theme", "baseColor", key],
-          );
-        }
-      }
-
-      const light =
-        baseColorByMode.light !== undefined
-          ? normalizeBaseColor(
-              baseColorByMode.light,
-              ["theme", "baseColor", "light"],
-              "Theme base color light",
-            )
-          : undefined;
-      const dark =
-        baseColorByMode.dark !== undefined
-          ? normalizeBaseColor(
-              baseColorByMode.dark,
-              ["theme", "baseColor", "dark"],
-              "Theme base color dark",
-            )
-          : undefined;
-
-      if (!light && !dark) {
-        throwConfigError(
-          "Theme base color object must include 'light', 'dark', or both.",
-          ["theme", "baseColor"],
-        );
-      }
-
-      const resolvedLight: BaseColorOption = light ?? "neutral";
-      const resolvedDark: BaseColorOption = dark ?? "neutral";
-
-      theme.baseColor = {
-        light: resolvedLight,
-        dark: resolvedDark,
-      };
-    }
-  }
-
-  const normalizeShikiThemeName = (
-    value: unknown,
-    currentPath: Path,
-    label: string,
-  ): string => {
-    checkType(value, "string", currentPath, label);
-    if (typeof value !== "string") {
-      throwConfigError(`${label} must be a string.`, currentPath);
-    }
-
-    const normalizedThemeName = value.trim().toLowerCase();
-    if (normalizedThemeName.length === 0) {
-      throwConfigError(`${label} cannot be empty.`, currentPath);
-    }
-
-    if (!isBundledShikiThemeName(normalizedThemeName)) {
-      throwConfigError(
-        `${label} must be a bundled Shiki theme name. Supported themes include: ${SHIKI_BUNDLED_THEME_NAMES.join(", ")}.`,
-        currentPath,
-      );
-    }
-
-    return normalizedThemeName;
-  };
-
-  if (theme.code !== undefined) {
-    checkType(theme.code, "object", ["theme", "code"], "Theme code");
-    if (
-      typeof theme.code !== "object" ||
-      theme.code === null ||
-      Array.isArray(theme.code)
-    ) {
-      throwConfigError("Theme code must be an object.", ["theme", "code"]);
-    }
-
-    const codeTheme = theme.code as CodeTheme & Record<string, unknown>;
-    const allowedCodeKeys = new Set(["syntaxTheme"]);
-    for (const key of Object.keys(codeTheme)) {
-      if (!allowedCodeKeys.has(key)) {
-        throwConfigError(
-          "Theme code configuration only supports 'syntaxTheme'.",
-          ["theme", "code", key],
-        );
-      }
-    }
-
-    if (codeTheme.syntaxTheme !== undefined) {
-      if (typeof codeTheme.syntaxTheme === "string") {
-        const themeName = normalizeShikiThemeName(
-          codeTheme.syntaxTheme,
-          ["theme", "code", "syntaxTheme"],
-          "Theme code syntax theme",
-        );
-        codeTheme.syntaxTheme = {
-          light: themeName,
-          dark: themeName,
-        };
-      } else {
-        checkType(
-          codeTheme.syntaxTheme,
-          "object",
-          ["theme", "code", "syntaxTheme"],
-          "Theme code syntax theme",
-        );
-        if (
-          typeof codeTheme.syntaxTheme !== "object" ||
-          codeTheme.syntaxTheme === null ||
-          Array.isArray(codeTheme.syntaxTheme)
-        ) {
-          throwConfigError(
-            "Theme code syntax theme must be a string or an object with light/dark values.",
-            ["theme", "code", "syntaxTheme"],
-          );
-        }
-
-        const syntaxThemeByMode = codeTheme.syntaxTheme as Record<
-          string,
-          unknown
-        >;
-        const allowedSyntaxThemeKeys = new Set(["light", "dark"]);
-        for (const key of Object.keys(syntaxThemeByMode)) {
-          if (!allowedSyntaxThemeKeys.has(key)) {
-            throwConfigError(
-              "Theme code syntax theme object only supports 'light' and 'dark'.",
-              ["theme", "code", "syntaxTheme", key],
-            );
-          }
-        }
-
-        const light =
-          syntaxThemeByMode.light !== undefined
-            ? normalizeShikiThemeName(
-                syntaxThemeByMode.light,
-                ["theme", "code", "syntaxTheme", "light"],
-                "Theme code syntax theme light",
-              )
-            : undefined;
-        const dark =
-          syntaxThemeByMode.dark !== undefined
-            ? normalizeShikiThemeName(
-                syntaxThemeByMode.dark,
-                ["theme", "code", "syntaxTheme", "dark"],
-                "Theme code syntax theme dark",
-              )
-            : undefined;
-
-        if (!light && !dark) {
-          throwConfigError(
-            "Theme code syntax theme object must include 'light', 'dark', or both.",
-            ["theme", "code", "syntaxTheme"],
-          );
-        }
-
-        codeTheme.syntaxTheme = {
-          light: light ?? DEFAULT_SHIKI_LIGHT_THEME,
-          dark: dark ?? DEFAULT_SHIKI_DARK_THEME,
-        };
-      }
-    }
-  }
-
-  if (theme.tag !== undefined) {
-    checkType(theme.tag, "object", ["theme", "tag"], "Theme tag");
-    if (
-      typeof theme.tag !== "object" ||
-      theme.tag === null ||
-      Array.isArray(theme.tag)
-    ) {
-      throwConfigError("Theme tag must be an object.", ["theme", "tag"]);
-    }
-
-    const tagTheme = theme.tag as TagTheme & Record<string, unknown>;
-    const allowedTagKeys = new Set(["color"]);
-    for (const key of Object.keys(tagTheme)) {
-      if (!allowedTagKeys.has(key)) {
-        throwConfigError("Theme tag configuration only supports 'color'.", [
-          "theme",
-          "tag",
-          key,
-        ]);
-      }
-    }
-
-    if (tagTheme.color !== undefined) {
-      tagTheme.color = normalizeThemeColorConfig(
-        tagTheme.color,
-        ["theme", "tag", "color"],
-        "Theme tag color",
-      );
-    }
-  }
-
-  if (theme.card !== undefined) {
-    checkType(theme.card, "object", ["theme", "card"], "Theme card");
-    if (
-      typeof theme.card !== "object" ||
-      theme.card === null ||
-      Array.isArray(theme.card)
-    ) {
-      throwConfigError("Theme card must be an object.", ["theme", "card"]);
-    }
-
-    const cardTheme = theme.card as CardTheme & Record<string, unknown>;
-    const allowedCardKeys = new Set(["cover", "button"]);
-    for (const key of Object.keys(cardTheme)) {
-      if (!allowedCardKeys.has(key)) {
-        throwConfigError(
-          "Theme card configuration only supports 'cover' and 'button'.",
-          ["theme", "card", key],
-        );
-      }
-    }
-
-    if (cardTheme.cover !== undefined) {
-      checkType(
-        cardTheme.cover,
-        "object",
-        ["theme", "card", "cover"],
-        "Theme card cover",
-      );
-      if (
-        typeof cardTheme.cover !== "object" ||
-        cardTheme.cover === null ||
-        Array.isArray(cardTheme.cover)
-      ) {
-        throwConfigError("Theme card cover must be an object.", [
-          "theme",
-          "card",
-          "cover",
-        ]);
-      }
-
-      const coverTheme = cardTheme.cover as CardCoverTheme &
-        Record<string, unknown>;
-      const allowedCoverKeys = new Set(["colors", "colorSeed"]);
-      for (const key of Object.keys(coverTheme)) {
-        if (!allowedCoverKeys.has(key)) {
-          throwConfigError(
-            "Theme card cover configuration only supports 'colors' and 'colorSeed'.",
-            ["theme", "card", "cover", key],
-          );
-        }
-      }
-
-      if (coverTheme.colors !== undefined) {
-        coverTheme.colors = normalizeHexColorArray(
-          coverTheme.colors,
-          ["theme", "card", "cover", "colors"],
-          "Theme card cover colors",
-        );
-      }
-
-      if (coverTheme.colorSeed !== undefined) {
-        coverTheme.colorSeed = normalizeSeedValue(
-          coverTheme.colorSeed,
-          ["theme", "card", "cover", "colorSeed"],
-          "Theme card cover color seed",
-        );
-      }
-    }
-
-    if (cardTheme.button !== undefined) {
-      checkType(
-        cardTheme.button,
-        "object",
-        ["theme", "card", "button"],
-        "Theme card button",
-      );
-      if (
-        typeof cardTheme.button !== "object" ||
-        cardTheme.button === null ||
-        Array.isArray(cardTheme.button)
-      ) {
-        throwConfigError("Theme card button must be an object.", [
-          "theme",
-          "card",
-          "button",
-        ]);
-      }
-
-      const buttonTheme = cardTheme.button as CardButtonTheme &
-        Record<string, unknown>;
-      const allowedButtonKeys = new Set(["color"]);
-      for (const key of Object.keys(buttonTheme)) {
-        if (!allowedButtonKeys.has(key)) {
-          throwConfigError(
-            "Theme card button configuration only supports 'color'.",
-            ["theme", "card", "button", key],
-          );
-        }
-      }
-
-      if (buttonTheme.color !== undefined) {
-        buttonTheme.color = normalizeThemeColorConfig(
-          buttonTheme.color,
-          ["theme", "card", "button", "color"],
-          "Theme card button color",
-        );
-      }
-    }
-  }
-
-  if (theme.themeColor === undefined) {
-    return;
-  }
-
-  if (typeof theme.themeColor === "string") {
-    theme.themeColor = normalizeHexColor(
-      theme.themeColor,
-      ["theme", "themeColor"],
-      "Theme color",
-    );
-    return;
-  }
-
-  checkType(theme.themeColor, "object", ["theme", "themeColor"], "Theme color");
-  if (
-    typeof theme.themeColor !== "object" ||
-    theme.themeColor === null ||
-    Array.isArray(theme.themeColor)
-  ) {
-    throwConfigError(
-      "Theme color must be a string or an object with light/dark values.",
-      ["theme", "themeColor"],
-    );
-  }
-
-  const themeColorByMode = theme.themeColor as Record<string, unknown>;
-  const allowedKeys = new Set(["light", "dark"]);
-  for (const key of Object.keys(themeColorByMode)) {
-    if (!allowedKeys.has(key)) {
-      throwConfigError("Theme color object only supports 'light' and 'dark'.", [
-        "theme",
-        "themeColor",
-        key,
-      ]);
-    }
-  }
-
-  const light =
-    themeColorByMode.light !== undefined
-      ? normalizeHexColor(
-          themeColorByMode.light,
-          ["theme", "themeColor", "light"],
-          "Theme color light",
-        )
-      : undefined;
-  const dark =
-    themeColorByMode.dark !== undefined
-      ? normalizeHexColor(
-          themeColorByMode.dark,
-          ["theme", "themeColor", "dark"],
-          "Theme color dark",
-        )
-      : undefined;
-
-  if (!light && !dark) {
-    throwConfigError(
-      "Theme color object must include 'light', 'dark', or both.",
-      ["theme", "themeColor"],
-    );
-  }
-
-  theme.themeColor = {
-    ...(light !== undefined ? { light } : {}),
-    ...(dark !== undefined ? { dark } : {}),
-  };
-}
-
-function validateAssistant(assistant: DocsConfig["assistant"]): void {
-  if (assistant === undefined) return;
-
-  checkType(assistant, "object", ["assistant"], "Assistant configuration");
-  if (
-    typeof assistant !== "object" ||
-    assistant === null ||
-    Array.isArray(assistant)
-  ) {
-    throwConfigError("Assistant configuration must be an object.", [
-      "assistant",
-    ]);
-  }
-
-  const allowedAssistantKeys = new Set([
-    "button",
-    "navbarButton",
-    "heading",
-    "questions",
-    "icon",
-  ]);
-  for (const key of Object.keys(assistant)) {
-    if (!allowedAssistantKeys.has(key)) {
-      throwConfigError(
-        "Assistant configuration only supports 'button', 'navbarButton', 'heading', 'questions', and 'icon'.",
-        ["assistant", key],
-      );
-    }
-  }
-
-  if (assistant.button !== undefined) {
-    checkType(
-      assistant.button,
-      "object",
-      ["assistant", "button"],
-      "Assistant button configuration",
-    );
-    if (
-      typeof assistant.button !== "object" ||
-      assistant.button === null ||
-      Array.isArray(assistant.button)
-    ) {
-      throwConfigError("Assistant button configuration must be an object.", [
-        "assistant",
-        "button",
-      ]);
-    }
-
-    const allowedButtonKeys = new Set(["size", "color"]);
-    for (const key of Object.keys(assistant.button)) {
-      if (!allowedButtonKeys.has(key)) {
-        throwConfigError(
-          "Assistant button configuration only supports 'size' and 'color'.",
-          ["assistant", "button", key],
-        );
-      }
-    }
-
-    if (assistant.button.size !== undefined) {
-      checkType(
-        assistant.button.size,
-        "string",
-        ["assistant", "button", "size"],
-        "Assistant button size",
-      );
-      if (typeof assistant.button.size !== "string") {
-        throwConfigError("Assistant button size must be a string.", [
-          "assistant",
-          "button",
-          "size",
-        ]);
-      }
-
-      const trimmedSize = assistant.button.size.trim();
-      if (trimmedSize !== "small" && trimmedSize !== "default") {
-        throwConfigError(
-          "Assistant button size must be either 'small' or 'default'.",
-          ["assistant", "button", "size"],
-        );
-      }
-      assistant.button.size = trimmedSize;
-    }
-
-    if (assistant.button.color !== undefined) {
-      assistant.button.color = normalizeThemeColorConfig(
-        assistant.button.color,
-        ["assistant", "button", "color"],
-        "Assistant button color",
-      );
-    }
-  }
-
-  if (assistant.navbarButton !== undefined) {
-    checkType(
-      assistant.navbarButton,
-      "object",
-      ["assistant", "navbarButton"],
-      "Assistant navbar button configuration",
-    );
-    if (
-      typeof assistant.navbarButton !== "object" ||
-      assistant.navbarButton === null ||
-      Array.isArray(assistant.navbarButton)
-    ) {
-      throwConfigError(
-        "Assistant navbar button configuration must be an object.",
-        ["assistant", "navbarButton"],
-      );
-    }
-
-    const allowedNavbarButtonKeys = new Set(["enabled", "text", "color"]);
-    for (const key of Object.keys(assistant.navbarButton)) {
-      if (!allowedNavbarButtonKeys.has(key)) {
-        throwConfigError(
-          "Assistant navbar button configuration only supports 'enabled', 'text', and 'color'.",
-          ["assistant", "navbarButton", key],
-        );
-      }
-    }
-
-    if (assistant.navbarButton.enabled !== undefined) {
-      checkType(
-        assistant.navbarButton.enabled,
-        "boolean",
-        ["assistant", "navbarButton", "enabled"],
-        "Assistant navbar button enabled",
-      );
-      if (typeof assistant.navbarButton.enabled !== "boolean") {
-        throwConfigError(
-          "Assistant navbar button enabled must be a boolean.",
-          ["assistant", "navbarButton", "enabled"],
-        );
-      }
-    }
-
-    if (assistant.navbarButton.text !== undefined) {
-      checkType(
-        assistant.navbarButton.text,
-        "string",
-        ["assistant", "navbarButton", "text"],
-        "Assistant navbar button text",
-      );
-      if (typeof assistant.navbarButton.text !== "string") {
-        throwConfigError("Assistant navbar button text must be a string.", [
-          "assistant",
-          "navbarButton",
-          "text",
-        ]);
-      }
-
-      const trimmedText = assistant.navbarButton.text.trim();
-      if (trimmedText.length === 0) {
-        throwConfigError("Assistant navbar button text cannot be empty.", [
-          "assistant",
-          "navbarButton",
-          "text",
-        ]);
-      }
-      assistant.navbarButton.text = trimmedText;
-    }
-
-    if (assistant.navbarButton.color !== undefined) {
-      assistant.navbarButton.color = normalizeThemeColorConfig(
-        assistant.navbarButton.color,
-        ["assistant", "navbarButton", "color"],
-        "Assistant navbar button color",
-      );
-    }
-  }
-
-  if (assistant.heading !== undefined) {
-    checkType(
-      assistant.heading,
-      "string",
-      ["assistant", "heading"],
-      "Assistant heading",
-    );
-    if (typeof assistant.heading !== "string") {
-      throwConfigError("Assistant heading must be a string.", [
-        "assistant",
-        "heading",
-      ]);
-    }
-
-    const trimmedHeading = assistant.heading.trim();
-    if (trimmedHeading.length === 0) {
-      throwConfigError("Assistant heading cannot be empty.", [
-        "assistant",
-        "heading",
-      ]);
-    }
-    assistant.heading = trimmedHeading;
-  }
-
-  if (assistant.questions !== undefined) {
-    checkType(
-      assistant.questions,
-      "array",
-      ["assistant", "questions"],
-      "Assistant questions",
-    );
-    if (!Array.isArray(assistant.questions)) {
-      throwConfigError("Assistant questions must be an array.", [
-        "assistant",
-        "questions",
-      ]);
-    }
-
-    if (assistant.questions.length > 3) {
-      throwConfigError("Assistant questions can include at most 3 questions.", [
-        "assistant",
-        "questions",
-      ]);
-    }
-
-    assistant.questions = assistant.questions.map((question, index) => {
-      checkType(
-        question,
-        "string",
-        ["assistant", "questions", String(index)],
-        "Assistant question",
-      );
-      if (typeof question !== "string") {
-        throwConfigError("Assistant question must be a string.", [
-          "assistant",
-          "questions",
-          String(index),
-        ]);
-      }
-
-      const trimmedQuestion = question.trim();
-      if (trimmedQuestion.length === 0) {
-        throwConfigError(
-          "Assistant question cannot be empty.",
-          ["assistant", "questions", String(index)],
-        );
-      }
-
-      return trimmedQuestion;
-    });
-  }
-
-  if (assistant.icon === undefined) return;
-
-  checkType(
-    assistant.icon,
-    "object",
-    ["assistant", "icon"],
-    "Assistant icon",
-  );
-  if (
-    typeof assistant.icon !== "object" ||
-    assistant.icon === null ||
-    Array.isArray(assistant.icon)
-  ) {
-    throwConfigError("Assistant icon must be an object.", [
-      "assistant",
-      "icon",
-    ]);
-  }
-
-  const allowedIconKeys = new Set(["src"]);
-  for (const key of Object.keys(assistant.icon)) {
-    if (!allowedIconKeys.has(key)) {
-      throwConfigError(
-        "Assistant icon only supports 'src'.",
-        ["assistant", "icon", key],
-      );
-    }
-  }
-
-  if (assistant.icon.src === undefined) {
-    throwConfigError(
-      "Assistant icon must include 'src'.",
-      ["assistant", "icon"],
-    );
-  }
-
-  if (assistant.icon.src !== undefined) {
-    assistant.icon.src = validateAssistantIconSource(
-      assistant.icon.src,
-      ["assistant", "icon", "src"],
-    );
-  }
-
-}
-
-function validateHome(home: DocsConfig["home"]): string | undefined {
-  if (home === undefined) return undefined;
-
-  const normalizedHome = normalizeDocsPagePath(home, ["home"], "Home path");
-  validateFileExistence(normalizedHome, ["home"]);
-  return normalizedHome;
-}
-
-function validateNavbar(navbar: DocsConfig["navbar"]): HiddenPageRoute[] {
-  const hiddenPageRoutes: HiddenPageRoute[] = [];
-  if (navbar === undefined) return hiddenPageRoutes; // Navbar itself is optional
-
-  checkType(navbar, "object", ["navbar"], "Navbar configuration");
-
-  // Validate 'blur'
-  checkType(navbar.blur, "boolean", ["navbar", "blur"], "Navbar blur setting");
-
-  // Validate 'primary' item
-  const primaryPageRoute = validateNavbarItem(navbar.primary, [
-    "navbar",
-    "primary",
-  ]);
-  if (primaryPageRoute) hiddenPageRoutes.push(primaryPageRoute);
-
-  // Validate 'secondary' item
-  const secondaryPageRoute = validateNavbarItem(navbar.secondary, [
-    "navbar",
-    "secondary",
-  ]);
-  if (secondaryPageRoute) hiddenPageRoutes.push(secondaryPageRoute);
-
-  // Validate 'links' array
-  if (navbar.links !== undefined) {
-    checkType(navbar.links, "array", ["navbar", "links"], "Navbar links");
-
-    if (navbar.links.length > 3) {
-      throwConfigError("Navbar links cannot have more than 3 items.", [
-        "navbar",
-        "links",
-      ]);
-    }
-
-    navbar.links.forEach((link: any, i: number) => {
-      const hiddenPageRoute = validateNavbarItem(link, ["navbar", "links", i]);
-      if (hiddenPageRoute) hiddenPageRoutes.push(hiddenPageRoute);
-    });
-  }
-
-  return hiddenPageRoutes;
-}
-
-function validateFooter(footer: DocsConfig["footer"]): HiddenPageRoute[] {
-  const hiddenPageRoutes: HiddenPageRoute[] = [];
-  if (footer === undefined) return hiddenPageRoutes;
-
-  checkType(footer, "object", ["footer"], "Footer configuration");
-
-  // Validate socials
-  if (footer.socials !== undefined) {
-    checkType(
-      footer.socials,
-      "object",
-      ["footer", "socials"],
-      "Footer socials",
-    );
-    const validSocials = [
-      "x",
-      "website",
-      "facebook",
-      "youtube",
-      "discord",
-      "slack",
-      "github",
-      "linkedin",
-      "instagram",
-      "hacker-news",
-      "medium",
-      "telegram",
-      "bluesky",
-      "threads",
-      "reddit",
-      "podcast",
-    ];
-    for (const [key, value] of Object.entries(footer.socials)) {
-      if (!validSocials.includes(key)) {
-        throwConfigError(
-          `Invalid social platform: ${key}. Valid options are: ${validSocials.join(
-            ", ",
-          )}`,
-          ["footer", "socials", key],
-        );
-      }
-      checkType(
-        value,
-        "string",
-        ["footer", "socials", key],
-        `Social link for ${key}`,
-      );
-      if (!isUrl(value as string)) {
-        throwConfigError(`Social link for ${key} must be a valid URL.`, [
-          "footer",
-          "socials",
-          key,
-        ]);
-      }
-    }
-  }
-
-  // Validate links
-  if (footer.links !== undefined) {
-    checkType(footer.links, "array", ["footer", "links"], "Footer links");
-    footer.links.forEach((link: any, i: number) => {
-      checkType(link, "object", ["footer", "links", i], "Footer link");
-
-      if (typeof link.text !== "string") {
-        throwConfigError("Footer link must have a 'text' property.", [
-          "footer",
-          "links",
-          i,
-          "text",
-        ]);
-      }
-
-      if (typeof link.href !== "string") {
-        throwConfigError("Footer link must have an 'href' property.", [
-          "footer",
-          "links",
-          i,
-          "href",
-        ]);
-      }
-
-      const hiddenPageRoute = normalizeInternalPageHref(
-        link.href,
-        ["footer", "links", i, "href"],
-        "Footer link href",
-      );
-      if (hiddenPageRoute) {
-        link.href = hiddenPageRoute.linkHref;
-        hiddenPageRoutes.push(hiddenPageRoute);
-      }
-    });
-  }
-
-  return hiddenPageRoutes;
-}
-
-async function validateNavigation(navigation: DocsConfig["navigation"]) {
-  checkType(navigation, "object", ["navigation"], "Navigation");
-
-  const keys = Object.keys(navigation);
-  const validKeys = ["pages", "menu", "openapi"];
-  const navKeys = keys.filter((key) => validKeys.includes(key));
-
-  if (navKeys.length !== 1) {
-    throwConfigError(
-      `Navigation must contain exactly one top-level item (${validKeys.join(
-        ", ",
-      )}). Found ${navKeys.length}.`,
-      ["navigation"],
-    );
-  }
-
-  const navKey = navKeys[0];
-  const navValue = (navigation as any)[navKey];
-
-  // Handle "menu" as an object, "pages" as an array
-  if (navKey === "menu") {
-    await validateNavMenu(navValue, ["navigation", "menu"]);
-  } else {
-    // Validate the container itself is an array for pages
-    checkType(
-      navValue,
-      "array",
-      ["navigation", navKey],
-      `Navigation container '${navKey}'`,
-    );
-
-    // Route to Recursive Structural Validation
-    for (const [i, item] of navValue.entries()) {
-      const itemPath = ["navigation", navKey, i] as Path;
-      if (typeof item === "string") {
-        const normalizedPagePath = normalizeDocsPagePath(item, itemPath);
-        navValue[i] = normalizedPagePath;
-        validateFileExistence(normalizedPagePath, itemPath);
-      } else {
-        await validateNavigationNode(item, itemPath);
-      }
-    }
-  }
-}
-
-// --- Config Runner ---
-
-async function validateConfig(config: any): Promise<DocsConfig> {
-  // Execute top-level checks sequentially
-  validateTitle(config.title);
-  validateLogo(config.logo);
-  validateTheme(config.theme);
-  validateAssistant(config.assistant);
-  await validateNavigation(config.navigation);
-  config.home = validateHome(config.home);
-
-  if (config.home === undefined) {
-    const fallbackHome = getFirstPagePathFromNavigation(config.navigation);
-    if (!fallbackHome) {
-      throwConfigError(
-        "Home is undefined and no documentation page exists in navigation to use as fallback.",
-        ["home"],
-      );
-    }
-    config.home = fallbackHome;
-  }
-
-  const hiddenPageRoutes = [
-    ...validateNavbar(config.navbar),
-    ...validateFooter(config.footer),
-  ];
-  const dedupedHiddenPageRoutes = new Map<string, HiddenPageRoute>();
-  for (const route of hiddenPageRoutes) {
-    dedupedHiddenPageRoutes.set(route.href, route);
-  }
-  config.hiddenPageRoutes = Array.from(dedupedHiddenPageRoutes.values());
-
-  // --- 4. Validate Playground ---
-  if (config.playground !== undefined) {
-    checkType(config.playground, "object", ["playground"], "Playground");
-    if (config.playground.proxy !== undefined) {
-      checkType(
-        config.playground.proxy,
-        "boolean",
-        ["playground", "proxy"],
-        "Proxy",
-      );
-    }
-  }
-
-  return config as DocsConfig;
-}
-
-let configCache: Promise<DocsConfig> | null = null;
-let lastMtime: number = 0;
-
-export async function getConfig(): Promise<DocsConfig> {
-  // 1. Check if docs.json exists
-  if (!fs.existsSync(CONFIG_PATH)) {
-    throw new Error(
-      "[USER_ERROR]: Invalid docs.json: `docs.json` missing at root of documentation repo.",
-    );
-  }
-
-  // 2. Check if docs.json has changed
-  const stats = fs.statSync(CONFIG_PATH);
-  if (configCache && stats.mtimeMs === lastMtime) {
-    return configCache;
-  }
-
-  // 3. If docs.json changed or first run, update cache
-  lastMtime = stats.mtimeMs;
-  configCache = (async () => {
-    const fileContent = fs.readFileSync(CONFIG_PATH, "utf-8");
-    let config: any;
-    try {
-      config = JSON.parse(fileContent);
-    } catch (e) {
-      throw new Error(
-        `[USER_ERROR]: Invalid docs.json: Invalid JSON syntax: ${
-          e instanceof Error ? e.message : e
-        }`,
-      );
-    }
-    // ---
-
-    // The custom validation is executed here
-    try {
-      const validatedConfig = await validateConfig(config);
-      return validatedConfig;
-    } catch (error) {
-      // Catch the custom error thrown by throwConfigError and re-throw it.
-      throw new Error(
-        `[USER_ERROR]: Invalid docs.json: ${
-          error instanceof Error ? error.message : error
-        }`,
-      );
-    }
-  })();
-
-  return configCache;
-}
-
-// Validate that only known components are used in MDX content
-function validateComponentUsage(content: string): void {
-  // Remove frontmatter before checking
-  const contentWithoutFrontmatter = content.replace(/^---[\s\S]*?---\n?/, "");
-  const allowedComponentSet = new Set(AVAILABLE_COMPONENTS);
-
-  // Remove code blocks, inline code, and JSX string expressions to avoid false positives
-  const contentWithoutCode = contentWithoutFrontmatter
-    .replace(/````[\s\S]*?````/g, "") // 4-backtick code blocks (check first, they're longer)
-    .replace(/```[\s\S]*?```/g, "") // fenced code blocks
-    .replace(/`[^`]+`/g, "") // inline code
-    // JSX string expressions like {'<Component title="Example" />'} or {"<Component />"}
-    .replace(/\{\s*(['"`])(?:\\.|(?!\1)[\s\S])*?\1\s*\}/g, "");
-
-  // Find all JSX component tags (PascalCase tags)
-  // Matches: <ComponentName, <ComponentName>, <ComponentName />, etc.
-  const componentRegex = /<([A-Z][a-zA-Z0-9]*)/g;
-  let match;
-
-  const unknownComponents: string[] = [];
-
-  while ((match = componentRegex.exec(contentWithoutCode)) !== null) {
-    const componentName = match[1];
-    if (!allowedComponentSet.has(componentName)) {
-      // Avoid duplicate entries
-      if (!unknownComponents.includes(componentName)) {
-        unknownComponents.push(componentName);
-      }
-    }
-  }
-
-  if (unknownComponents.length > 0) {
-    const componentList = unknownComponents.map((c) => `<${c}>`).join(", ");
-    const visibleComponents = AVAILABLE_COMPONENTS.filter(
-      (component) => !INTERNAL_ONLY_COMPONENTS.has(component),
-    );
-    throw new Error(
-      `Unknown component(s): ${componentList}. ` +
-        `Available components are: ${visibleComponents.join(", ")}. ` +
-        "If writing ABOUT a component, use literal backticks: " +
-        "\`<ComponentName>\` or a JSX string: " +
-        "\`{'<ComponentName />'}\`.",
-    );
-  }
-}
-
-// Helper to recursively find MDX files
-function getMdxFiles(dir: string): string[] {
-  let results: string[] = [];
-  const list = fs.readdirSync(dir);
-  list.forEach((file) => {
-    file = path.resolve(dir, file);
-    const stat = fs.statSync(file);
-    if (stat && stat.isDirectory()) {
-      results = results.concat(getMdxFiles(file));
-    } else if (file.endsWith(".mdx")) {
-      results.push(file);
-    }
-  });
-  return results;
-}
-
-// MDX Validation Function
-export async function validateMdxContent() {
-  const files = getMdxFiles(DOCS_DIR);
-
-  for (const file of files) {
-    try {
-      const content = fs.readFileSync(file, "utf-8");
-
-      // Check for Frontmatter
-      const match = content.match(/^---\n([\s\S]*?)\n---/);
-
-      if (match) {
-        // Parse only if it exists
-        const frontmatter = yaml.parse(match[1]);
-
-        // Validate against shared schema
-        const result = docsSchema.safeParse(frontmatter);
-
-        if (!result.success) {
-          const issue = result.error.issues[0];
-          const pathStr = issue.path.join(".");
-          // Throw clean error
-          throw new Error(
-            `Frontmatter validation failed: ${issue.message} (at: ${pathStr})`,
-          );
-        }
-      }
-
-      // Validate component usage BEFORE compiling
-      validateComponentUsage(content);
-
-      // Compile just to check syntax
-      await compile(content, { jsx: true });
-    } catch (e: any) {
-      const relativePath = path.relative(DOCS_DIR, file);
-      const location = e.line ? `:${e.line}:${e.column}` : "";
-      const reason = e.reason || e.message;
-
-      // Throw clean error
-      throw new Error(
-        `[USER_ERROR]: Invalid MDX in ${relativePath}${location} -> ${reason}`,
-      );
-    }
-  }
-}
+export * from "radiant-docs-validator";