radiant-docs 0.1.7 → 0.1.8

package/template/src/lib/validation.ts

@@ -12,6 +12,95 @@ const CWD = process.cwd();
 const DOCS_DIR = path.join(CWD, "src/content/docs");
 const CONFIG_PATH = path.join(DOCS_DIR, "docs.json");
 
+// 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",
@@ -19,15 +108,27 @@ const AVAILABLE_COMPONENTS = [
   "Tab",
   "Steps",
   "Step",
-  "Accordian",
-  "AccordianGroup",
+  "Accordion",
+  "AccordionGroup",
+  "Image",
+  "CodeGroup",
+  "ComponentPreview",
 ];
 
-export type NavPage = { page: string; icon?: string; tag?: string };
+// 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?: string;
+  title?: string;
+};
 export type NavGroup = {
   group: string;
   pages: (string | NavPage | NavGroup)[];
-  icon?: string;
+  icon?: string | null;
   expanded?: boolean; // need to add this logic
   tag?: string;
 };
@@ -37,8 +138,7 @@ export type NavOpenApi = {
   exclude?: string[];
 };
 export type NavigationItem = {
-  pages?: (string | NavPage)[];
-  groups?: NavGroup[];
+  pages?: (string | NavPage | NavGroup)[];
   menu?: NavMenu;
   openapi?: string | NavOpenApi;
 };
@@ -46,22 +146,30 @@ export type NavigationItem = {
 export type NavMenuItem = {
   label: string;
   submenu: Omit<NavigationItem, "menu">;
-  icon?: string;
+  icon?: string | null;
 };
 export type NavMenu = {
-  type?: "dropdown" | "collapsible";
+  type?: "dropdown" | "segmented";
   label?: string;
   items: NavMenuItem[];
 };
 export type NavbarItem = {
   text: string;
   href: string;
-  icon?: string;
+  icon?: string | null;
+};
+export type LogoVariant = string | {
+  image: string;
+  padding?: {
+    top?: number;
+    bottom?: number;
+  };
 };
 export type Logo = {
-  light?: string;
-  dark?: string;
+  light?: LogoVariant;
+  dark?: LogoVariant;
   href?: string;
+  pill?: string | false;
 };
 export type DocsConfig = {
   title: string;
@@ -74,6 +182,36 @@ export type DocsConfig = {
     secondary?: NavbarItem;
     links?: NavbarItem[];
   };
+  playground?: {
+    proxy?: boolean;
+  };
+  footer?: Footer;
+};
+
+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)[];
 
@@ -92,9 +230,9 @@ function checkType(
   value: any,
   type: "string" | "boolean" | "array" | "object",
   currentPath: Path,
-  label: string
+  label: string,
 ): void {
-  if (value === undefined) return;
+  if (value === undefined || value === null) return;
 
   if (type === "array") {
     if (!Array.isArray(value))
@@ -115,19 +253,37 @@ function validateFileExistence(filePath: string, currentPath: Path): void {
   if (!fs.existsSync(fullPath)) {
     throwConfigError(
       `Referenced file not found. Expected: ${filePath}`,
-      currentPath
+      currentPath,
     );
   }
 }
 
-// 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 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;
 }
 
 // Cache for OpenAPI specs (key: filePathOrUrl, value: parsed spec)
@@ -150,7 +306,7 @@ export async function loadOpenApiSpec(filePathOrUrl: string): Promise<any> {
       const response = await fetch(filePathOrUrl);
       if (!response.ok) {
         throw new Error(
-          `Failed to fetch OpenAPI spec: ${response.status} ${response.statusText}`
+          `Failed to fetch OpenAPI spec: ${response.status} ${response.statusText}`,
         );
       }
       fileContent = await response.text();
@@ -158,7 +314,7 @@ export async function loadOpenApiSpec(filePathOrUrl: string): Promise<any> {
       throw new Error(
         `Failed to fetch OpenAPI spec from URL: ${
           error instanceof Error ? error.message : String(error)
-        }`
+        }`,
       );
     }
   } else {
@@ -174,7 +330,7 @@ export async function loadOpenApiSpec(filePathOrUrl: string): Promise<any> {
     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."
+      "The URL does not return a valid OpenAPI specification. The URL appears to return HTML instead of JSON or YAML.",
     );
   }
 
@@ -193,7 +349,7 @@ export async function loadOpenApiSpec(filePathOrUrl: string): Promise<any> {
   } 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}`
+        `The URL does not return a valid OpenAPI specification. Failed to parse as JSON or YAML: ${parseError.message}`,
       );
     }
     throw parseError;
@@ -212,13 +368,13 @@ async function validateOpenApiFile(filePathOrUrl: string, currentPath: Path) {
     // For local files, validate extension and existence
     const validExtensions = [".json", ".yaml", ".yml"];
     const hasValidExtension = validExtensions.some((ext) =>
-      filePathOrUrl.toLowerCase().endsWith(ext)
+      filePathOrUrl.toLowerCase().endsWith(ext),
     );
 
     if (!hasValidExtension) {
       throwConfigError(
         `OpenAPI file must have a valid extension (.json, .yaml, or .yml). Found: ${filePathOrUrl}`,
-        currentPath
+        currentPath,
       );
     }
 
@@ -227,7 +383,7 @@ async function validateOpenApiFile(filePathOrUrl: string, currentPath: Path) {
     if (!fs.existsSync(fullPath)) {
       throwConfigError(
         `Referenced OpenAPI file not found. Expected: ${filePathOrUrl}`,
-        currentPath
+        currentPath,
       );
     }
   } else {
@@ -237,13 +393,13 @@ async function validateOpenApiFile(filePathOrUrl: string, currentPath: Path) {
       if (url.protocol !== "http:" && url.protocol !== "https:") {
         throwConfigError(
           `OpenAPI URL must use http:// or https:// protocol. Found: ${filePathOrUrl}`,
-          currentPath
+          currentPath,
         );
       }
     } catch (error) {
       throwConfigError(
         `Invalid OpenAPI URL format: ${filePathOrUrl}`,
-        currentPath
+        currentPath,
       );
     }
   }
@@ -251,37 +407,70 @@ async function validateOpenApiFile(filePathOrUrl: string, currentPath: Path) {
   // Validate the OpenAPI spec using Spectral (works for both files and URLs)
   try {
     const document = await loadOpenApiSpec(filePathOrUrl);
-
-    const basicRuleset = {
-      formats: oas.formats,
+    const tolerantRuleset = {
+      ...oas,
       rules: {
-        "oas3-schema": oas.rules["oas3-schema"],
+        ...oas.rules,
+        "oas3-schema": {
+          ...oas.rules["oas3-schema"],
+          severity: 1,
+        },
+        "oas2-schema": {
+          ...oas.rules["oas2-schema"],
+          severity: 1,
+        },
       },
     };
 
     const spectral = new Spectral();
 
-    spectral.setRuleset(basicRuleset);
+    spectral.setRuleset(tolerantRuleset);
 
     let results = await spectral.run(document);
+    const blockingResults = results.filter(
+      (result) => result.code === "unrecognized-format",
+    );
 
-    if (results.length > 0) {
-      // Format validation errors - show first few errors
-      const errorMessages = results
-        .slice(0, 5) // Limit to first 5 errors
-        .map((result) => {
-          const pathStr =
-            result.path.length > 0 ? result.path.join(".") : "root";
-          return `${result.message} (at ${pathStr})`;
-        });
+    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 =
-        results.length > 5 ? ` (and ${results.length - 5} more errors)` : "";
+        blockingResults.length > 5
+          ? ` (and ${blockingResults.length - 5} more errors)`
+          : "";
 
       throwConfigError(
         `Invalid OpenAPI specification: ${errorText}${moreErrors}`,
-        currentPath
+        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) {
@@ -289,17 +478,20 @@ async function validateOpenApiFile(filePathOrUrl: string, currentPath: Path) {
     if (error instanceof SyntaxError) {
       throwConfigError(
         `Failed to parse OpenAPI file: ${error.message}`,
-        currentPath
+        currentPath,
       );
     } else if (error instanceof Error) {
-      throwConfigError(
-        `Invalid OpenAPI specification: ${error.message}`,
-        currentPath
-      );
+      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
+        currentPath,
       );
     }
   }
@@ -338,7 +530,7 @@ function extractAvailableEndpoints(openApiDoc: any): Set<string> {
 
 // Helper function to parse endpoint string (e.g., "get /burgers" or "POST /burgers")
 function parseEndpointString(
-  endpointStr: string
+  endpointStr: string,
 ): { method: string; path: string } | null {
   const trimmed = endpointStr.trim();
   const parts = trimmed.split(/\s+/);
@@ -361,10 +553,15 @@ function parseEndpointString(
   return { method, path: normalizedPath };
 }
 
-function validateNavigationNode(item: any, currentPath: Path): void {
+function validateNavigationNode(
+  item: any,
+  currentPath: Path,
+  groupDepth: number = 0,
+): void {
   // A) Base Case: Simple string path
   if (typeof item === "string") {
-    validateFileExistence(item, currentPath);
+    const normalizedPath = normalizeDocsPagePath(item, currentPath);
+    validateFileExistence(normalizedPath, currentPath);
     return;
   }
 
@@ -379,25 +576,41 @@ function validateNavigationNode(item: any, currentPath: Path): void {
   if (typeCount !== 1) {
     throwConfigError(
       "Object must contain exactly one key: 'page' or 'group'.",
-      currentPath
+      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"]);
+
     // 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");
 
     item.pages.forEach((child: any, i: number) => {
-      validateNavigationNode(child, [...path, "pages", i]); // Recursive call
+      if (typeof child === "string") {
+        const childPath = [...path, "pages", i];
+        const normalizedPagePath = normalizeDocsPagePath(child, childPath);
+        item.pages[i] = normalizedPagePath;
+        validateFileExistence(normalizedPagePath, childPath);
+        return;
+      }
+
+      validateNavigationNode(child, [...path, "pages", i], groupDepth + 1);
     });
     return;
   }
@@ -405,9 +618,17 @@ function validateNavigationNode(item: any, currentPath: Path): void {
   // --- Validate Page ---
   if (isPage) {
     const path = [...currentPath];
-    checkType(item.page, "string", [...path, "page"], "Page path");
+    const normalizedPagePath = normalizeDocsPagePath(item.page, [
+      ...path,
+      "page",
+    ]);
+    item.page = normalizedPagePath;
+    validateFileExistence(normalizedPagePath, [...path, "page"]);
+
+    validateIcon(item.icon, [...path, "icon"]);
 
-    validateFileExistence(item.page, [...path, "page"]);
+    // Validate optional title
+    checkType(item.title, "string", [...path, "title"], "Page title");
 
     // Check D.2/D.3: Page cannot have group properties
     if ("expanded" in item)
@@ -421,9 +642,56 @@ function validateNavigationNode(item: any, currentPath: Path): void {
   }
 }
 
+function getFirstPagePathFromPageItems(
+  items: (string | NavPage | NavGroup)[],
+): 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
+  currentPath: Path,
 ): Promise<void> {
   checkType(navOpenApi, "object", currentPath, "Open API object");
 
@@ -431,7 +699,7 @@ async function validateNavOpenApi(
   if (typeof navOpenApi.source !== "string") {
     throwConfigError(
       "Open API object must have an 'source' property that is a string.",
-      [...currentPath, "source"]
+      [...currentPath, "source"],
     );
   }
 
@@ -445,7 +713,7 @@ async function validateNavOpenApi(
   if (hasInclude && hasExclude) {
     throwConfigError(
       "Open API object cannot have both 'include' and 'exclude' properties. They are mutually exclusive.",
-      currentPath
+      currentPath,
     );
   }
 
@@ -464,7 +732,7 @@ async function validateNavOpenApi(
       navOpenApi.include,
       "array",
       [...currentPath, "include"],
-      "Include array"
+      "Include array",
     );
 
     if (navOpenApi.include.length === 0) {
@@ -479,7 +747,7 @@ async function validateNavOpenApi(
       if (typeof entry !== "string") {
         throwConfigError(
           `Include entry at index ${i} must be a string in the format "METHOD /path".`,
-          [...currentPath, "include", i]
+          [...currentPath, "include", i],
         );
       }
 
@@ -487,7 +755,7 @@ async function validateNavOpenApi(
       if (!parsed) {
         throwConfigError(
           `Include entry at index ${i} must be in the format "METHOD /path". Found: ${entry}`,
-          [...currentPath, "include", i]
+          [...currentPath, "include", i],
         );
       }
 
@@ -496,7 +764,7 @@ async function validateNavOpenApi(
       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]
+          [...currentPath, "include", i],
         );
       }
     }
@@ -508,7 +776,7 @@ async function validateNavOpenApi(
       navOpenApi.exclude,
       "array",
       [...currentPath, "exclude"],
-      "Exclude array"
+      "Exclude array",
     );
 
     if (navOpenApi.exclude.length === 0) {
@@ -523,7 +791,7 @@ async function validateNavOpenApi(
       if (typeof entry !== "string") {
         throwConfigError(
           `Exclude entry at index ${i} must be a string in the format "METHOD /path".`,
-          [...currentPath, "exclude", i]
+          [...currentPath, "exclude", i],
         );
       }
 
@@ -531,7 +799,7 @@ async function validateNavOpenApi(
       if (!parsed) {
         throwConfigError(
           `Exclude entry at index ${i} must be in the format "METHOD /path" (e.g., "get /burgers"). Found: ${entry}`,
-          [...currentPath, "exclude", i]
+          [...currentPath, "exclude", i],
         );
       }
 
@@ -540,7 +808,7 @@ async function validateNavOpenApi(
       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]
+          [...currentPath, "exclude", i],
         );
       }
     }
@@ -550,7 +818,7 @@ async function validateNavOpenApi(
 async function validateNavMenuItem(item: NavMenuItem, currentPath: Path) {
   checkType(item, "object", currentPath, "Menu item");
 
-  checkType(item.icon, "string", [...currentPath, "icon"], "Menu item icon");
+  validateIcon(item.icon, [...currentPath, "icon"]);
 
   // Required: label
   if (!item.label) {
@@ -572,12 +840,12 @@ async function validateNavMenuItem(item: NavMenuItem, currentPath: Path) {
 
   const submenu = item.submenu;
   const submenuKeys = Object.keys(submenu);
-  const validSubmenuKeys = ["pages", "groups", "openapi"];
+  const validSubmenuKeys = ["pages", "openapi"];
   const presentSubmenuKeys = submenuKeys.filter((key) =>
-    validSubmenuKeys.includes(key)
+    validSubmenuKeys.includes(key),
   );
   const invalidSubmenuKeys = submenuKeys.filter(
-    (key) => !validSubmenuKeys.includes(key)
+    (key) => !validSubmenuKeys.includes(key),
   );
 
   // Submenu must have exactly one key total
@@ -585,16 +853,16 @@ async function validateNavMenuItem(item: NavMenuItem, currentPath: Path) {
     if (submenuKeys.length === 0) {
       throwConfigError(
         `Submenu must contain exactly one key (${validSubmenuKeys.join(
-          ", "
+          ", ",
         )}). Found no keys.`,
-        [...currentPath, "submenu"]
+        [...currentPath, "submenu"],
       );
     } else {
       throwConfigError(
         `Submenu must contain exactly one key (${validSubmenuKeys.join(
-          ", "
+          ", ",
         )}). Found ${submenuKeys.length} key(s): ${submenuKeys.join(", ")}.`,
-        [...currentPath, "submenu"]
+        [...currentPath, "submenu"],
       );
     }
   }
@@ -604,9 +872,9 @@ async function validateNavMenuItem(item: NavMenuItem, currentPath: Path) {
     const invalidKey = invalidSubmenuKeys[0];
     throwConfigError(
       `Submenu must contain exactly one key (${validSubmenuKeys.join(
-        ", "
+        ", ",
       )}). Found invalid key: ${invalidKey}.`,
-      [...currentPath, "submenu"]
+      [...currentPath, "submenu"],
     );
   }
 
@@ -620,31 +888,20 @@ async function validateNavMenuItem(item: NavMenuItem, currentPath: Path) {
       submenuValue,
       "array",
       [...currentPath, "submenu", "pages"],
-      "Submenu pages"
+      "Submenu pages",
     );
     (submenuValue as NavigationItem["pages"])?.forEach(
-      (page: string | NavPage, i: number) => {
-        if (typeof page === "string") {
-          validateFileExistence(page, [...currentPath, "submenu", "pages", i]);
+      (item: string | NavPage | NavGroup, i: number) => {
+        const itemPath = [...currentPath, "submenu", "pages", i];
+        if (typeof item === "string") {
+          const normalizedPagePath = normalizeDocsPagePath(item, itemPath);
+          (submenuValue as (string | NavPage | NavGroup)[])[i] =
+            normalizedPagePath;
+          validateFileExistence(normalizedPagePath, itemPath);
         } else {
-          validateNavigationNode(page, [...currentPath, "submenu", "pages", i]);
+          validateNavigationNode(item, itemPath);
         }
-      }
-    );
-  }
-
-  // Validate groups array
-  if (submenuKey === "groups") {
-    checkType(
-      submenuValue,
-      "array",
-      [...currentPath, "submenu", "groups"],
-      "Submenu groups"
-    );
-    (submenuValue as NavigationItem["groups"])?.forEach(
-      (group: NavGroup, i: number) => {
-        validateNavigationNode(group, [...currentPath, "submenu", "groups", i]);
-      }
+      },
     );
   }
 
@@ -667,7 +924,7 @@ async function validateNavMenuItem(item: NavMenuItem, currentPath: Path) {
     } else {
       throwConfigError(
         "OpenAPI must be either a string (file path or hosted file) or an object.",
-        [...currentPath, "submenu", "openapi"]
+        [...currentPath, "submenu", "openapi"],
       );
     }
   }
@@ -678,10 +935,10 @@ async function validateNavMenu(menu: any, currentPath: Path) {
 
   // Optional: type
   if (menu.type !== undefined) {
-    if (menu.type !== "dropdown" && menu.type !== "collapsible") {
+    if (menu.type !== "dropdown" && menu.type !== "segmented") {
       throwConfigError(
-        "Menu type must be 'dropdown' or 'collapsible' if provided. Defaults to 'dropdown'",
-        [...currentPath, "type"]
+        "Menu type must be 'dropdown' or 'segmented' if provided. Defaults to 'dropdown'",
+        [...currentPath, "type"],
       );
     }
   }
@@ -725,7 +982,7 @@ function validateNavbarItem(item: any, currentPath: Path): void {
   }
 
   // Optional property
-  checkType(item.icon, "string", [...currentPath, "icon"], "Navbar icon");
+  validateIcon(item.icon, [...currentPath, "icon"]);
 }
 
 // --- Top-Level Validation Functions (Your Clean API) ---
@@ -735,75 +992,131 @@ function validateTitle(title: DocsConfig["title"]) {
   if (!title) throwConfigError("Title is missing.", ["title"]);
 }
 
-function validateLogo(logo: DocsConfig["logo"]) {
-  // Logo is optional, so if it's undefined, we're done
-  if (logo === undefined) return;
+function validateLogoPaddingValue(value: unknown, currentPath: Path, label: string): void {
+  if (value === undefined) return;
 
-  // If logo is provided, it must be an object
-  checkType(logo, "object", ["logo"], "Logo configuration");
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throwConfigError(`${label} must be a finite number.`, currentPath);
+  }
 
-  // Validate 'light' logo if provided
-  if (logo.light !== undefined) {
-    checkType(logo.light, "string", ["logo", "light"], "Logo light path");
+  const numericValue = value as number;
+  if (numericValue < 0) {
+    throwConfigError(`${label} cannot be negative.`, currentPath);
+  }
+}
 
-    // Validate file extension
-    const validExtensions = [".svg", ".png", ".jpg", ".jpeg", ".webp", ".gif"];
-    const hasValidExtension = validExtensions.some((ext) =>
-      logo.light!.toLowerCase().endsWith(ext)
+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,
     );
-    if (!hasValidExtension) {
-      throwConfigError(
-        "Logo light must be a valid image file (.svg, .png, .jpg, .jpeg, .webp, .gif)",
-        ["logo", "light"]
-      );
-    }
+  }
 
-    // Validate file exists in content/docs folder
-    // Normalize path: remove leading slash if present
-    const normalizedPath = logo.light.startsWith("/")
-      ? logo.light.slice(1)
-      : logo.light;
-    const fullPath = path.join(DOCS_DIR, normalizedPath);
+  const normalizedPath = imagePath.startsWith("/")
+    ? imagePath.slice(1)
+    : imagePath;
+  const fullPath = path.join(DOCS_DIR, normalizedPath);
 
-    if (!fs.existsSync(fullPath)) {
-      throwConfigError(
-        `Logo light file not found. Expected: ${normalizedPath} (relative to content/docs folder)`,
-        ["logo", "light"]
-      );
-    }
+  if (!fs.existsSync(fullPath)) {
+    throwConfigError(
+      `${label} file not found. Expected: ${normalizedPath} (relative to content/docs folder)`,
+      currentPath,
+    );
   }
+}
 
-  // Validate 'dark' logo if provided
-  if (logo.dark !== undefined) {
-    checkType(logo.dark, "string", ["logo", "dark"], "Logo dark path");
+function validateLogoVariant(
+  variant: LogoVariant | undefined,
+  currentPath: Path,
+  mode: "light" | "dark",
+): void {
+  if (variant === undefined) return;
 
-    // Validate file extension
-    const validExtensions = [".svg", ".png", ".jpg", ".jpeg", ".webp", ".gif"];
-    const hasValidExtension = validExtensions.some((ext) =>
-      logo.dark!.toLowerCase().endsWith(ext)
+  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,
     );
-    if (!hasValidExtension) {
+  }
+
+  const supportedKeys = new Set(["image", "padding"]);
+  for (const key of Object.keys(variant)) {
+    if (!supportedKeys.has(key)) {
       throwConfigError(
-        "Logo dark must be a valid image file (.svg, .png, .jpg, .jpeg, .webp, .gif)",
-        ["logo", "dark"]
+        `Logo ${mode} object only supports 'image' and 'padding'.`,
+        [...currentPath, key],
       );
     }
+  }
 
-    // Validate file exists in content/docs folder
-    // Normalize path: remove leading slash if present
-    const normalizedPath = logo.dark.startsWith("/")
-      ? logo.dark.slice(1)
-      : logo.dark;
-    const fullPath = path.join(DOCS_DIR, normalizedPath);
+  if (typeof variant.image !== "string") {
+    throwConfigError(
+      `Logo ${mode} object must include an 'image' string.`,
+      [...currentPath, "image"],
+    );
+  }
 
-    if (!fs.existsSync(fullPath)) {
+  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 dark file not found. Expected: ${normalizedPath} (relative to content/docs folder)`,
-        ["logo", "dark"]
+        `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");
@@ -827,14 +1140,32 @@ function validateLogo(logo: DocsConfig["logo"]) {
     if (!isUrl && !isInternalPath) {
       throwConfigError(
         "Logo href must be either a valid URL (http:// or https://) or an internal path (starting with /)",
-        ["logo", "href"]
+        ["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 validateHome(home: DocsConfig["home"]) {
-  checkType(home, "string", ["home"], "Home path");
+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"]) {
@@ -868,40 +1199,142 @@ function validateNavbar(navbar: DocsConfig["navbar"]) {
   }
 }
 
+function validateFooter(footer: DocsConfig["footer"]) {
+  if (footer === undefined) return;
+
+  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 trimmedHref = link.href.trim();
+      const isExternal =
+        trimmedHref.startsWith("http://") || trimmedHref.startsWith("https://");
+      const isInternal = trimmedHref.startsWith("/");
+
+      if (!isExternal && !isInternal) {
+        throwConfigError(
+          "Footer link href must be either a valid URL (http:// or https://) or an internal path (starting with /)",
+          ["footer", "links", i, "href"],
+        );
+      }
+    });
+  }
+}
+
 async function validateNavigation(navigation: DocsConfig["navigation"]) {
   checkType(navigation, "object", ["navigation"], "Navigation");
 
   const keys = Object.keys(navigation);
-  const validKeys = ["pages", "groups", "menu", "openapi"];
+  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"]
+      ["navigation"],
     );
   }
 
   const navKey = navKeys[0];
   const navValue = (navigation as any)[navKey];
 
-  // Handle "menu" as an object, "pages" and "groups" as arrays
+  // 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/groups
+    // Validate the container itself is an array for pages
     checkType(
       navValue,
       "array",
       ["navigation", navKey],
-      `Navigation container '${navKey}'`
+      `Navigation container '${navKey}'`,
     );
 
     // Route to Recursive Structural Validation
     navValue.forEach((item: NavigationItem, i: number) => {
-      validateNavigationNode(item, ["navigation", navKey, i]);
+      const itemPath = ["navigation", navKey, i] as Path;
+      if (typeof item === "string") {
+        const normalizedPagePath = normalizeDocsPagePath(item, itemPath);
+        navValue[i] = normalizedPagePath;
+        validateFileExistence(normalizedPagePath, itemPath);
+      } else {
+        validateNavigationNode(item, itemPath);
+      }
     });
   }
 }
@@ -912,9 +1345,34 @@ async function validateConfig(config: any): Promise<DocsConfig> {
   // Execute top-level checks sequentially
   validateTitle(config.title);
   validateLogo(config.logo);
-  validateHome(config.home);
   validateNavbar(config.navbar);
+  validateFooter(config.footer);
   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;
+  }
+
+  // --- 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;
 }
@@ -926,7 +1384,7 @@ 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."
+      "[USER_ERROR]: Invalid docs.json: `docs.json` missing at root of documentation repo.",
     );
   }
 
@@ -947,7 +1405,7 @@ export async function getConfig(): Promise<DocsConfig> {
       throw new Error(
         `[USER_ERROR]: Invalid docs.json: Invalid JSON syntax: ${
           e instanceof Error ? e.message : e
-        }`
+        }`,
       );
     }
     // ---
@@ -961,7 +1419,7 @@ export async function getConfig(): Promise<DocsConfig> {
       throw new Error(
         `[USER_ERROR]: Invalid docs.json: ${
           error instanceof Error ? error.message : error
-        }`
+        }`,
       );
     }
   })();
@@ -973,32 +1431,7 @@ export async function getConfig(): Promise<DocsConfig> {
 function validateComponentUsage(content: string): void {
   // Remove frontmatter before checking
   const contentWithoutFrontmatter = content.replace(/^---[\s\S]*?---\n?/, "");
-
-  // Extract imported component names from MDX import statements
-  // Matches: import ComponentName from "..." or import { ComponentName } from "..."
-  const importedComponents: string[] = [];
-  const defaultImportRegex = /import\s+([A-Z][a-zA-Z0-9]*)\s+from/g;
-  const namedImportRegex = /import\s*\{([^}]+)\}\s*from/g;
-
-  let importMatch;
-  while (
-    (importMatch = defaultImportRegex.exec(contentWithoutFrontmatter)) !== null
-  ) {
-    importedComponents.push(importMatch[1]);
-  }
-  while (
-    (importMatch = namedImportRegex.exec(contentWithoutFrontmatter)) !== null
-  ) {
-    // Parse named imports like { Foo, Bar as Baz }
-    const names = importMatch[1].split(",").map((n) => {
-      const parts = n.trim().split(/\s+as\s+/);
-      return parts[parts.length - 1].trim(); // Use the alias if present
-    });
-    importedComponents.push(...names.filter((n) => /^[A-Z]/.test(n)));
-  }
-
-  // Combine available components with imported ones
-  const allowedComponents = [...AVAILABLE_COMPONENTS, ...importedComponents];
+  const allowedComponentSet = new Set(AVAILABLE_COMPONENTS);
 
   // Remove code blocks, inline code, and JSX string expressions to avoid false positives
   const contentWithoutCode = contentWithoutFrontmatter
@@ -1016,7 +1449,7 @@ function validateComponentUsage(content: string): void {
 
   while ((match = componentRegex.exec(contentWithoutCode)) !== null) {
     const componentName = match[1];
-    if (!allowedComponents.includes(componentName)) {
+    if (!allowedComponentSet.has(componentName)) {
       // Avoid duplicate entries
       if (!unknownComponents.includes(componentName)) {
         unknownComponents.push(componentName);
@@ -1026,10 +1459,15 @@ function validateComponentUsage(content: string): void {
 
   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: ${AVAILABLE_COMPONENTS.join(", ")}. ` +
-        `If writing ABOUT a component, use backticks: \`<ComponentName>\` or JSX strings: {'<ComponentName />'}`
+        `Available components are: ${visibleComponents.join(", ")}. ` +
+        "If writing ABOUT a component, use literal backticks: " +
+        "\`<ComponentName>\` or a JSX string: " +
+        "\`{'<ComponentName />'}\`.",
     );
   }
 }
@@ -1073,7 +1511,7 @@ export async function validateMdxContent() {
           const pathStr = issue.path.join(".");
           // Throw clean error
           throw new Error(
-            `Frontmatter validation failed: ${issue.message} (at: ${pathStr})`
+            `Frontmatter validation failed: ${issue.message} (at: ${pathStr})`,
           );
         }
       }
@@ -1090,7 +1528,7 @@ export async function validateMdxContent() {
 
       // Throw clean error
       throw new Error(
-        `[USER_ERROR]: Invalid MDX in ${relativePath}${location} -> ${reason}`
+        `[USER_ERROR]: Invalid MDX in ${relativePath}${location} -> ${reason}`,
       );
     }
   }