radiant-docs 0.1.39 → 0.1.41

package/template/src/lib/validation.ts

@@ -167,22 +167,74 @@ export type NavbarItem = {
   href: string;
   icon?: string | null;
 };
-export type LogoVariant = string | {
-  image: string;
-  padding?: {
-    top?: number;
-    bottom?: number;
-  };
+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 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 ThemeColorByMode = {
+  light?: string;
+  dark?: string;
+};
+export type DocsTheme = {
+  baseColor?: BaseColorOption | BaseColorByMode;
+  themeColor?: string | ThemeColorByMode;
+};
+export type AssistantIcon = {
+  src?: string;
+  color?: string;
+};
+export type AssistantButtonSize = "small" | "default";
+export type AssistantButtonConfig = {
+  size?: AssistantButtonSize;
+};
+export type AssistantConfig = {
+  button?: AssistantButtonConfig;
+  heading?: string;
+  questions?: string[];
+  themeColor?: string | ThemeColorByMode;
+  icon?: AssistantIcon;
+};
 export type DocsConfig = {
   title: string;
   logo?: Logo;
+  theme?: DocsTheme;
+  assistant?: AssistantConfig;
   home?: string;
   navigation: NavigationItem;
   navbar?: {
@@ -195,6 +247,7 @@ export type DocsConfig = {
     proxy?: boolean;
   };
   footer?: Footer;
+  hiddenPageRoutes?: HiddenPageRoute[];
 };
 
 export type SocialPlatform =
@@ -255,6 +308,38 @@ function checkType(
   }
 }
 
+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 validateFileExistence(filePath: string, currentPath: Path): void {
   // Assuming relative path from DOCS_DIR and .mdx extension
   const fullPath = path.join(DOCS_DIR, `${filePath}.mdx`);
@@ -295,6 +380,58 @@ function normalizeDocsPagePath(
   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>();
 
@@ -662,7 +799,11 @@ async function validateNavigationNode(
         continue;
       }
 
-      await validateNavigationNode(child, [...path, "pages", i], groupDepth + 1);
+      await validateNavigationNode(
+        child,
+        [...path, "pages", i],
+        groupDepth + 1,
+      );
     }
     return;
   }
@@ -1049,9 +1190,12 @@ async function validateNavMenu(menu: any, currentPath: Path) {
   }
 }
 
-function validateNavbarItem(item: any, currentPath: Path): void {
+function validateNavbarItem(
+  item: any,
+  currentPath: Path,
+): HiddenPageRoute | null {
   // Check if object exists, otherwise we skip (it's optional)
-  if (item === undefined) return;
+  if (item === undefined) return null;
 
   checkType(item, "object", currentPath, "Navbar item");
 
@@ -1069,8 +1213,18 @@ function validateNavbarItem(item: any, currentPath: Path): void {
     ]);
   }
 
+  const hiddenPageRoute = normalizeInternalPageHref(
+    item.href,
+    [...currentPath, "href"],
+    "Navbar item href",
+  );
+  if (hiddenPageRoute) {
+    item.href = hiddenPageRoute.linkHref;
+  }
+
   // Optional property
   validateIcon(item.icon, [...currentPath, "icon"]);
+  return hiddenPageRoute;
 }
 
 // --- Top-Level Validation Functions (Your Clean API) ---
@@ -1080,7 +1234,11 @@ function validateTitle(title: DocsConfig["title"]) {
   if (!title) throwConfigError("Title is missing.", ["title"]);
 }
 
-function validateLogoPaddingValue(value: unknown, currentPath: Path, label: string): void {
+function validateLogoPaddingValue(
+  value: unknown,
+  currentPath: Path,
+  label: string,
+): void {
   if (value === undefined) return;
 
   if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -1116,10 +1274,85 @@ function validateLogoImagePath(
 
   if (!fs.existsSync(fullPath)) {
     throwConfigError(
-      `${label} file not found. Expected: ${normalizedPath} (relative to content/docs folder)`,
+      `${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(
@@ -1134,7 +1367,11 @@ function validateLogoVariant(
     return;
   }
 
-  if (typeof variant !== "object" || variant === null || Array.isArray(variant)) {
+  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,
@@ -1152,13 +1389,17 @@ function validateLogoVariant(
   }
 
   if (typeof variant.image !== "string") {
-    throwConfigError(
-      `Logo ${mode} object must include an 'image' string.`,
-      [...currentPath, "image"],
-    );
+    throwConfigError(`Logo ${mode} object must include an 'image' string.`, [
+      ...currentPath,
+      "image",
+    ]);
   }
 
-  validateLogoImagePath(variant.image, [...currentPath, "image"], `Logo ${mode} image`);
+  validateLogoImagePath(
+    variant.image,
+    [...currentPath, "image"],
+    `Logo ${mode} image`,
+  );
 
   if (variant.padding === undefined) return;
 
@@ -1242,10 +1483,463 @@ function validateLogo(logo: DocsConfig["logo"]) {
         );
       }
     } else if (logo.pill !== false) {
-      throwConfigError("Logo pill must be a string or false.", ["logo", "pill"]);
+      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,
+      };
+    }
+  }
+
+  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",
+    "heading",
+    "questions",
+    "themeColor",
+    "icon",
+  ]);
+  for (const key of Object.keys(assistant)) {
+    if (!allowedAssistantKeys.has(key)) {
+      throwConfigError(
+        "Assistant configuration only supports 'button', 'heading', 'questions', 'themeColor', 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"]);
+    for (const key of Object.keys(assistant.button)) {
+      if (!allowedButtonKeys.has(key)) {
+        throwConfigError(
+          "Assistant button configuration only supports 'size'.",
+          ["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.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.themeColor !== undefined) {
+    if (typeof assistant.themeColor === "string") {
+      assistant.themeColor = normalizeHexColor(
+        assistant.themeColor,
+        ["assistant", "themeColor"],
+        "Assistant theme color",
+      );
+    } else {
+      checkType(
+        assistant.themeColor,
+        "object",
+        ["assistant", "themeColor"],
+        "Assistant theme color",
+      );
+      if (
+        typeof assistant.themeColor !== "object" ||
+        assistant.themeColor === null ||
+        Array.isArray(assistant.themeColor)
+      ) {
+        throwConfigError(
+          "Assistant theme color must be a string or an object with light/dark values.",
+          ["assistant", "themeColor"],
+        );
+      }
+
+      const assistantThemeColorByMode = assistant.themeColor as Record<
+        string,
+        unknown
+      >;
+      const allowedThemeColorKeys = new Set(["light", "dark"]);
+      for (const key of Object.keys(assistantThemeColorByMode)) {
+        if (!allowedThemeColorKeys.has(key)) {
+          throwConfigError(
+            "Assistant theme color object only supports 'light' and 'dark'.",
+            ["assistant", "themeColor", key],
+          );
+        }
+      }
+
+      const light =
+        assistantThemeColorByMode.light !== undefined
+          ? normalizeHexColor(
+              assistantThemeColorByMode.light,
+              ["assistant", "themeColor", "light"],
+              "Assistant theme color light",
+            )
+          : undefined;
+      const dark =
+        assistantThemeColorByMode.dark !== undefined
+          ? normalizeHexColor(
+              assistantThemeColorByMode.dark,
+              ["assistant", "themeColor", "dark"],
+              "Assistant theme color dark",
+            )
+          : undefined;
+
+      if (!light && !dark) {
+        throwConfigError(
+          "Assistant theme color object must include 'light', 'dark', or both.",
+          ["assistant", "themeColor"],
+        );
+      }
+
+      assistant.themeColor = {
+        ...(light !== undefined ? { light } : {}),
+        ...(dark !== undefined ? { dark } : {}),
+      };
+    }
+  }
+
+  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", "color"]);
+  for (const key of Object.keys(assistant.icon)) {
+    if (!allowedIconKeys.has(key)) {
+      throwConfigError(
+        "Assistant icon only supports 'src' and 'color'.",
+        ["assistant", "icon", key],
+      );
+    }
+  }
+
+  if (
+    assistant.icon.src === undefined &&
+    assistant.icon.color === undefined
+  ) {
+    throwConfigError(
+      "Assistant icon must include 'src', 'color', or both.",
+      ["assistant", "icon"],
+    );
+  }
+
+  if (assistant.icon.src !== undefined) {
+    assistant.icon.src = validateAssistantIconSource(
+      assistant.icon.src,
+      ["assistant", "icon", "src"],
+    );
+  }
+
+  if (assistant.icon.color !== undefined) {
+    assistant.icon.color = normalizeHexColor(
+      assistant.icon.color,
+      ["assistant", "icon", "color"],
+      "Assistant icon color",
+    );
+  }
 }
 
 function validateHome(home: DocsConfig["home"]): string | undefined {
@@ -1256,8 +1950,9 @@ function validateHome(home: DocsConfig["home"]): string | undefined {
   return normalizedHome;
 }
 
-function validateNavbar(navbar: DocsConfig["navbar"]) {
-  if (navbar === undefined) return; // Navbar itself is optional
+function validateNavbar(navbar: DocsConfig["navbar"]): HiddenPageRoute[] {
+  const hiddenPageRoutes: HiddenPageRoute[] = [];
+  if (navbar === undefined) return hiddenPageRoutes; // Navbar itself is optional
 
   checkType(navbar, "object", ["navbar"], "Navbar configuration");
 
@@ -1265,10 +1960,18 @@ function validateNavbar(navbar: DocsConfig["navbar"]) {
   checkType(navbar.blur, "boolean", ["navbar", "blur"], "Navbar blur setting");
 
   // Validate 'primary' item
-  validateNavbarItem(navbar.primary, ["navbar", "primary"]);
+  const primaryPageRoute = validateNavbarItem(navbar.primary, [
+    "navbar",
+    "primary",
+  ]);
+  if (primaryPageRoute) hiddenPageRoutes.push(primaryPageRoute);
 
   // Validate 'secondary' item
-  validateNavbarItem(navbar.secondary, ["navbar", "secondary"]);
+  const secondaryPageRoute = validateNavbarItem(navbar.secondary, [
+    "navbar",
+    "secondary",
+  ]);
+  if (secondaryPageRoute) hiddenPageRoutes.push(secondaryPageRoute);
 
   // Validate 'links' array
   if (navbar.links !== undefined) {
@@ -1282,13 +1985,17 @@ function validateNavbar(navbar: DocsConfig["navbar"]) {
     }
 
     navbar.links.forEach((link: any, i: number) => {
-      validateNavbarItem(link, ["navbar", "links", i]);
+      const hiddenPageRoute = validateNavbarItem(link, ["navbar", "links", i]);
+      if (hiddenPageRoute) hiddenPageRoutes.push(hiddenPageRoute);
     });
   }
+
+  return hiddenPageRoutes;
 }
 
-function validateFooter(footer: DocsConfig["footer"]) {
-  if (footer === undefined) return;
+function validateFooter(footer: DocsConfig["footer"]): HiddenPageRoute[] {
+  const hiddenPageRoutes: HiddenPageRoute[] = [];
+  if (footer === undefined) return hiddenPageRoutes;
 
   checkType(footer, "object", ["footer"], "Footer configuration");
 
@@ -1367,19 +2074,19 @@ function validateFooter(footer: DocsConfig["footer"]) {
         ]);
       }
 
-      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"],
-        );
+      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"]) {
@@ -1433,8 +2140,8 @@ async function validateConfig(config: any): Promise<DocsConfig> {
   // Execute top-level checks sequentially
   validateTitle(config.title);
   validateLogo(config.logo);
-  validateNavbar(config.navbar);
-  validateFooter(config.footer);
+  validateTheme(config.theme);
+  validateAssistant(config.assistant);
   await validateNavigation(config.navigation);
   config.home = validateHome(config.home);
 
@@ -1449,6 +2156,16 @@ async function validateConfig(config: any): Promise<DocsConfig> {
     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");