@aravindc26/velu 0.11.6 → 0.11.9

package/src/build.ts

@@ -1,9 +1,9 @@
-import { readFileSync, writeFileSync, mkdirSync, copyFileSync, cpSync, existsSync, rmSync, readdirSync } from "node:fs";
-import { join, dirname, relative, extname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { parse as parseYaml } from "yaml";
-import { generateThemeCss, resolveThemeName, type VeluColors, type VeluStyling } from "./themes.js";
-import { normalizeConfigNavigation } from "./navigation-normalize.js";
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, cpSync, existsSync, rmSync, readdirSync } from "node:fs";
+import { join, dirname, relative, extname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { generateThemeCss, resolveThemeName, type VeluColors, type VeluStyling } from "./themes.js";
+import { normalizeConfigNavigation } from "./navigation-normalize.js";
 
 // ── Engine directory (shipped with the CLI package) ──────────────────────────
 const __filename = fileURLToPath(import.meta.url);
@@ -24,7 +24,11 @@ const SOURCE_MIRROR_EXTENSIONS = new Set([
   ".pdf", ".txt", ".xml", ".csv", ".zip",
 ]);
 
-const IMPORT_REWRITE_EXTENSIONS = new Set([".md", ".mdx", ".jsx", ".js", ".tsx", ".ts"]);
+const IMPORT_REWRITE_EXTENSIONS = new Set([".md", ".mdx", ".jsx", ".js", ".tsx", ".ts"]);
+const VARIABLE_SUBSTITUTION_EXTENSIONS = new Set([
+  ".md", ".mdx", ".jsx", ".js", ".tsx", ".ts",
+  ".json", ".yaml", ".yml", ".css", ".txt", ".xml", ".csv",
+]);
 
 function resolveConfigPath(docsDir: string): string {
   const primary = join(docsDir, PRIMARY_CONFIG_NAME);
@@ -47,17 +51,17 @@ interface VeluLink {
   iconType?: string;
 }
 
-interface VeluAnchor {
-  anchor: string;
-  href?: string;
-  icon?: string;
-  iconType?: string;
-  openapi?: VeluOpenApiSource;
-  version?: string;
-  color?: {
-    light: string;
-    dark: string;
-  };
+interface VeluAnchor {
+  anchor: string;
+  href?: string;
+  icon?: string;
+  iconType?: string;
+  openapi?: VeluOpenApiSource;
+  version?: string;
+  color?: {
+    light: string;
+    dark: string;
+  };
   tabs?: VeluTab[];
   hidden?: boolean;
 }
@@ -69,16 +73,16 @@ interface VeluGlobalTab {
   iconType?: string;
 }
 
-interface VeluGroup {
-  group: string;
-  slug: string;
-  icon?: string;
-  iconType?: string;
-  version?: string;
-  openapi?: VeluOpenApiSource;
-  expanded?: boolean;
-  description?: string;
-  hidden?: boolean;
+interface VeluGroup {
+  group: string;
+  slug: string;
+  icon?: string;
+  iconType?: string;
+  version?: string;
+  openapi?: VeluOpenApiSource;
+  expanded?: boolean;
+  description?: string;
+  hidden?: boolean;
   pages: (string | VeluGroup | VeluSeparator | VeluLink)[];
 }
 
@@ -91,17 +95,17 @@ interface VeluMenuItem {
   pages?: (string | VeluSeparator | VeluLink)[];
 }
 
-interface VeluTab {
-  tab: string;
-  slug: string;
-  icon?: string;
-  iconType?: string;
-  href?: string;
-  openapi?: VeluOpenApiSource;
-  version?: string;
-  pages?: (string | VeluSeparator | VeluLink)[];
-  groups?: VeluGroup[];
-  menu?: VeluMenuItem[];
+interface VeluTab {
+  tab: string;
+  slug: string;
+  icon?: string;
+  iconType?: string;
+  href?: string;
+  openapi?: VeluOpenApiSource;
+  version?: string;
+  pages?: (string | VeluSeparator | VeluLink)[];
+  groups?: VeluGroup[];
+  menu?: VeluMenuItem[];
 }
 
 interface VeluLanguageNav {
@@ -131,15 +135,19 @@ interface VeluRedirect {
   permanent?: boolean;
 }
 
-interface VeluConfig {
-  $schema?: string;
-  theme?: string;
-  colors?: VeluColors;
-  appearance?: "system" | "light" | "dark";
-  styling?: VeluStyling;
-  openapi?: VeluOpenApiSource;
-  languages?: string[];
-  redirects?: VeluRedirect[];
+interface VeluConfig {
+  $schema?: string;
+  theme?: string;
+  variables?: Record<string, string>;
+  colors?: VeluColors;
+  appearance?: "system" | "light" | "dark";
+  styling?: VeluStyling;
+  metadata?: {
+    timestamp?: boolean;
+  };
+  openapi?: VeluOpenApiSource;
+  languages?: string[];
+  redirects?: VeluRedirect[];
   navigation: {
     openapi?: VeluOpenApiSource;
     tabs?: VeluTab[];
@@ -154,12 +162,12 @@ interface VeluConfig {
   };
 }
 
-interface VeluOpenApiConfigObject {
-  source?: string | string[];
-  directory?: string;
-}
-
-type VeluOpenApiSource = string | string[] | VeluOpenApiConfigObject;
+interface VeluOpenApiConfigObject {
+  source?: string | string[];
+  directory?: string;
+}
+
+type VeluOpenApiSource = string | string[] | VeluOpenApiConfigObject;
 
 function isSeparator(item: unknown): item is VeluSeparator {
   return typeof item === "object" && item !== null && "separator" in item;
@@ -173,67 +181,67 @@ function isGroup(item: unknown): item is VeluGroup {
   return typeof item === "object" && item !== null && "group" in item;
 }
 
-const HTTP_METHODS = new Set([
-  "GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "TRACE", "CONNECT", "WEBHOOK",
-]);
-const OPENAPI_PATH_METHODS = new Set(["get", "post", "put", "patch", "delete", "options", "head", "trace"]);
-
-interface ParsedOpenApiOperationRef {
-  spec?: string;
-  method: string;
-  endpoint: string;
-  kind?: "path" | "webhook";
-  title?: string;
-  description?: string;
-  deprecated?: boolean;
-  version?: string;
-  content?: string;
-}
-
-function resolveDefaultOpenApiSpec(openapi: VeluOpenApiSource | undefined): string | undefined {
-  const source = extractOpenApiSource(openapi);
-  if (typeof source === "string") {
-    const trimmed = source.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
-  }
-  if (Array.isArray(source)) {
-    const first = source.find((entry) => typeof entry === "string" && entry.trim().length > 0);
-    return typeof first === "string" ? first.trim() : undefined;
-  }
-  return undefined;
-}
-
-function parseOpenApiOperationRef(value: string, inheritedSpec?: string): ParsedOpenApiOperationRef | null {
-  const trimmed = value.trim();
-  if (!trimmed) return null;
-
-  const withSpec = trimmed.match(/^(\S+)\s+([A-Za-z]+)\s+(.+)$/);
-  if (withSpec) {
-    const method = withSpec[2].toUpperCase();
-    const endpoint = withSpec[3].trim();
-    if (!HTTP_METHODS.has(method)) return null;
-    if (method === "WEBHOOK") {
-      if (!endpoint) return null;
-      return { spec: withSpec[1].trim(), method, endpoint, kind: "webhook" };
-    }
-    if (!endpoint.startsWith("/")) return null;
-    return { spec: withSpec[1].trim(), method, endpoint, kind: "path" };
-  }
-
-  const noSpec = trimmed.match(/^([A-Za-z]+)\s+(.+)$/);
-  if (!noSpec) return null;
-  const method = noSpec[1].toUpperCase();
-  const endpoint = noSpec[2].trim();
-  if (!HTTP_METHODS.has(method)) return null;
-  if (method === "WEBHOOK") {
-    if (!endpoint) return null;
-    return { spec: inheritedSpec, method, endpoint, kind: "webhook" };
-  }
-  if (!endpoint.startsWith("/")) return null;
-  return { spec: inheritedSpec, method, endpoint, kind: "path" };
-}
+const HTTP_METHODS = new Set([
+  "GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "TRACE", "CONNECT", "WEBHOOK",
+]);
+const OPENAPI_PATH_METHODS = new Set(["get", "post", "put", "patch", "delete", "options", "head", "trace"]);
+
+interface ParsedOpenApiOperationRef {
+  spec?: string;
+  method: string;
+  endpoint: string;
+  kind?: "path" | "webhook";
+  title?: string;
+  description?: string;
+  deprecated?: boolean;
+  version?: string;
+  content?: string;
+}
+
+function resolveDefaultOpenApiSpec(openapi: VeluOpenApiSource | undefined): string | undefined {
+  const source = extractOpenApiSource(openapi);
+  if (typeof source === "string") {
+    const trimmed = source.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+  if (Array.isArray(source)) {
+    const first = source.find((entry) => typeof entry === "string" && entry.trim().length > 0);
+    return typeof first === "string" ? first.trim() : undefined;
+  }
+  return undefined;
+}
 
-function slugFromOpenApiOperation(method: string, endpoint: string): string {
+function parseOpenApiOperationRef(value: string, inheritedSpec?: string): ParsedOpenApiOperationRef | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+
+  const withSpec = trimmed.match(/^(\S+)\s+([A-Za-z]+)\s+(.+)$/);
+  if (withSpec) {
+    const method = withSpec[2].toUpperCase();
+    const endpoint = withSpec[3].trim();
+    if (!HTTP_METHODS.has(method)) return null;
+    if (method === "WEBHOOK") {
+      if (!endpoint) return null;
+      return { spec: withSpec[1].trim(), method, endpoint, kind: "webhook" };
+    }
+    if (!endpoint.startsWith("/")) return null;
+    return { spec: withSpec[1].trim(), method, endpoint, kind: "path" };
+  }
+
+  const noSpec = trimmed.match(/^([A-Za-z]+)\s+(.+)$/);
+  if (!noSpec) return null;
+  const method = noSpec[1].toUpperCase();
+  const endpoint = noSpec[2].trim();
+  if (!HTTP_METHODS.has(method)) return null;
+  if (method === "WEBHOOK") {
+    if (!endpoint) return null;
+    return { spec: inheritedSpec, method, endpoint, kind: "webhook" };
+  }
+  if (!endpoint.startsWith("/")) return null;
+  return { spec: inheritedSpec, method, endpoint, kind: "path" };
+}
+
+function slugFromOpenApiOperation(method: string, endpoint: string): string {
   const cleaned = endpoint
     .toLowerCase()
     .replace(/^\/+/, "")
@@ -243,164 +251,266 @@ function slugFromOpenApiOperation(method: string, endpoint: string): string {
     .replace(/[-_.]{2,}/g, "-")
     .replace(/^[-_.]+|[-_.]+$/g, "");
   const body = cleaned || "endpoint";
-  return `${method.toLowerCase()}-${body}`;
-}
+  return `${method.toLowerCase()}-${body}`;
+}
+
+function resolveOpenApiSpecList(openapi: VeluOpenApiSource | undefined): string[] {
+  const source = extractOpenApiSource(openapi);
+  if (typeof source === "string") {
+    const trimmed = source.trim();
+    return trimmed ? [trimmed] : [];
+  }
+  if (Array.isArray(source)) {
+    return source
+      .filter((entry): entry is string => typeof entry === "string")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.length > 0);
+  }
+  return [];
+}
+
+function extractOpenApiSource(openapi: VeluOpenApiSource | undefined): string | string[] | undefined {
+  if (typeof openapi === "string" || Array.isArray(openapi)) return openapi;
+  if (openapi && typeof openapi === "object") {
+    const source = (openapi as VeluOpenApiConfigObject).source;
+    if (typeof source === "string" || Array.isArray(source)) return source;
+  }
+  return undefined;
+}
+
+function resolveOpenApiDirectory(openapi: VeluOpenApiSource | undefined): string | undefined {
+  if (!openapi || typeof openapi !== "object" || Array.isArray(openapi)) return undefined;
+  const raw = (openapi as VeluOpenApiConfigObject).directory;
+  if (typeof raw !== "string") return undefined;
+  const trimmed = raw.trim().replace(/\\/g, "/").replace(/^\/+/, "").replace(/\/+$/, "");
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function parseOpenApiDocument(rawSource: string): Record<string, unknown> | null {
+  const source = rawSource.trim();
+  if (!source) return null;
+  try {
+    const parsed = JSON.parse(source);
+    if (parsed && typeof parsed === "object") return parsed as Record<string, unknown>;
+  } catch {
+    // fall through and attempt YAML parse.
+  }
+  try {
+    const parsed = parseYaml(source);
+    if (parsed && typeof parsed === "object") return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function readMintMetadata(operation: Record<string, unknown>) {
+  const xMint = operation["x-mint"];
+  if (!xMint || typeof xMint !== "object") return {};
+  const metadata = (xMint as Record<string, unknown>).metadata;
+  const content = (xMint as Record<string, unknown>).content;
+  const meta = metadata && typeof metadata === "object" ? (metadata as Record<string, unknown>) : {};
+  return {
+    title: typeof meta.title === "string" ? meta.title : undefined,
+    description: typeof meta.description === "string" ? meta.description : undefined,
+    deprecated: typeof meta.deprecated === "boolean" ? meta.deprecated : undefined,
+    version: typeof meta.version === "string" ? meta.version : undefined,
+    content: typeof content === "string" ? content : undefined,
+  };
+}
+
+function pickOperationMethod(pathItem: Record<string, unknown>): string | undefined {
+  for (const method of OPENAPI_PATH_METHODS) {
+    const operation = pathItem[method];
+    if (operation && typeof operation === "object") return method.toUpperCase();
+  }
+  return undefined;
+}
+
+function loadOpenApiOperations(specSource: string, docsDir: string): ParsedOpenApiOperationRef[] {
+  if (/^https?:\/\//i.test(specSource) || specSource.startsWith("file://")) return [];
+
+  const resolvedPath = specSource.startsWith("/")
+    ? join(docsDir, specSource.replace(/^\/+/, ""))
+    : resolve(docsDir, specSource);
+  if (!existsSync(resolvedPath)) return [];
+
+  const parsed = parseOpenApiDocument(readFileSync(resolvedPath, "utf-8"));
+  if (!parsed) return [];
+
+  const paths = parsed.paths;
+  const webhooks = parsed.webhooks;
+
+  const output: ParsedOpenApiOperationRef[] = [];
+  if (paths && typeof paths === "object") {
+    for (const [endpoint, methods] of Object.entries(paths as Record<string, unknown>)) {
+      if (!endpoint.startsWith("/") || !methods || typeof methods !== "object") continue;
+      for (const method of Object.keys(methods as Record<string, unknown>)) {
+        const normalized = method.toLowerCase();
+        if (!OPENAPI_PATH_METHODS.has(normalized)) continue;
+        const operation = (methods as Record<string, unknown>)[method];
+        if (!operation || typeof operation !== "object") continue;
+        if ((operation as Record<string, unknown>)["x-hidden"] === true) continue;
+        const mintMeta = readMintMetadata(operation as Record<string, unknown>);
+        output.push({
+          kind: "path",
+          spec: specSource,
+          method: normalized.toUpperCase(),
+          endpoint,
+          title: mintMeta.title ?? (typeof (operation as Record<string, unknown>).summary === "string" ? String((operation as Record<string, unknown>).summary) : undefined),
+          description: mintMeta.description ?? (typeof (operation as Record<string, unknown>).description === "string" ? String((operation as Record<string, unknown>).description) : undefined),
+          deprecated: mintMeta.deprecated ?? ((operation as Record<string, unknown>).deprecated === true),
+          version: mintMeta.version,
+          content: mintMeta.content,
+        });
+      }
+    }
+  }
+
+  if (webhooks && typeof webhooks === "object") {
+    for (const [webhookName, pathItem] of Object.entries(webhooks as Record<string, unknown>)) {
+      if (!pathItem || typeof pathItem !== "object") continue;
+      const resolvedMethod = pickOperationMethod(pathItem as Record<string, unknown>);
+      if (!resolvedMethod) continue;
+      const operation = (pathItem as Record<string, unknown>)[resolvedMethod.toLowerCase()];
+      if (!operation || typeof operation !== "object") continue;
+      if ((operation as Record<string, unknown>)["x-hidden"] === true) continue;
+      const mintMeta = readMintMetadata(operation as Record<string, unknown>);
+      output.push({
+        kind: "webhook",
+        spec: specSource,
+        method: "WEBHOOK",
+        endpoint: webhookName,
+        title: mintMeta.title ?? (typeof (operation as Record<string, unknown>).summary === "string" ? String((operation as Record<string, unknown>).summary) : undefined),
+        description: mintMeta.description ?? (typeof (operation as Record<string, unknown>).description === "string" ? String((operation as Record<string, unknown>).description) : undefined),
+        deprecated: mintMeta.deprecated ?? ((operation as Record<string, unknown>).deprecated === true),
+        version: mintMeta.version,
+        content: mintMeta.content,
+      });
+    }
+  }
+  return output;
+}
+
+function normalizeOpenApiSpecForFrontmatter(spec: string | undefined): string | undefined {
+  if (!spec) return undefined;
+  const trimmed = spec.trim();
+  if (!trimmed) return undefined;
+  if (/^https?:\/\//i.test(trimmed) || trimmed.startsWith("file://")) return trimmed;
+  if (trimmed.startsWith("/")) return trimmed;
+  return `/${trimmed.replace(/^\.?\/*/, "")}`;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
 
-function resolveOpenApiSpecList(openapi: VeluOpenApiSource | undefined): string[] {
-  const source = extractOpenApiSource(openapi);
-  if (typeof source === "string") {
-    const trimmed = source.trim();
-    return trimmed ? [trimmed] : [];
-  }
-  if (Array.isArray(source)) {
-    return source
-      .filter((entry): entry is string => typeof entry === "string")
-      .map((entry) => entry.trim())
-      .filter((entry) => entry.length > 0);
-  }
-  return [];
-}
+const VARIABLE_TOKEN_PATTERN = /\{\{\s*([A-Za-z0-9.-]+)\s*\}\}/g;
+const VARIABLE_NAME_PATTERN = /^[A-Za-z0-9.-]+$/;
 
-function extractOpenApiSource(openapi: VeluOpenApiSource | undefined): string | string[] | undefined {
-  if (typeof openapi === "string" || Array.isArray(openapi)) return openapi;
-  if (openapi && typeof openapi === "object") {
-    const source = (openapi as VeluOpenApiConfigObject).source;
-    if (typeof source === "string" || Array.isArray(source)) return source;
-  }
-  return undefined;
+function sanitizeVariableValue(value: string): string {
+  return value.replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
-function resolveOpenApiDirectory(openapi: VeluOpenApiSource | undefined): string | undefined {
-  if (!openapi || typeof openapi !== "object" || Array.isArray(openapi)) return undefined;
-  const raw = (openapi as VeluOpenApiConfigObject).directory;
-  if (typeof raw !== "string") return undefined;
-  const trimmed = raw.trim().replace(/\\/g, "/").replace(/^\/+/, "").replace(/\/+$/, "");
-  return trimmed.length > 0 ? trimmed : undefined;
-}
+function extractVariables(input: unknown): Record<string, string> {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return {};
 
-function parseOpenApiDocument(rawSource: string): Record<string, unknown> | null {
-  const source = rawSource.trim();
-  if (!source) return null;
-  try {
-    const parsed = JSON.parse(source);
-    if (parsed && typeof parsed === "object") return parsed as Record<string, unknown>;
-  } catch {
-    // fall through and attempt YAML parse.
-  }
-  try {
-    const parsed = parseYaml(source);
-    if (parsed && typeof parsed === "object") return parsed as Record<string, unknown>;
-  } catch {
-    return null;
+  const output: Record<string, string> = {};
+  for (const [rawKey, rawValue] of Object.entries(input as Record<string, unknown>)) {
+    const key = rawKey.trim();
+    if (!key) continue;
+    if (!VARIABLE_NAME_PATTERN.test(key)) {
+      throw new Error(`Invalid variable name '${rawKey}'. Variable names can only contain letters, numbers, periods, and hyphens.`);
+    }
+    if (typeof rawValue !== "string") {
+      throw new Error(`Invalid value for variable '${rawKey}'. Variables must be strings.`);
+    }
+    output[key] = rawValue;
   }
-  return null;
+  return output;
 }
 
-function readMintMetadata(operation: Record<string, unknown>) {
-  const xMint = operation["x-mint"];
-  if (!xMint || typeof xMint !== "object") return {};
-  const metadata = (xMint as Record<string, unknown>).metadata;
-  const content = (xMint as Record<string, unknown>).content;
-  const meta = metadata && typeof metadata === "object" ? (metadata as Record<string, unknown>) : {};
-  return {
-    title: typeof meta.title === "string" ? meta.title : undefined,
-    description: typeof meta.description === "string" ? meta.description : undefined,
-    deprecated: typeof meta.deprecated === "boolean" ? meta.deprecated : undefined,
-    version: typeof meta.version === "string" ? meta.version : undefined,
-    content: typeof content === "string" ? content : undefined,
-  };
-}
+function resolveVariableMap(rawVariables: Record<string, string>): Record<string, string> {
+  const cache = new Map<string, string>();
+  const activeStack = new Set<string>();
 
-function pickOperationMethod(pathItem: Record<string, unknown>): string | undefined {
-  for (const method of OPENAPI_PATH_METHODS) {
-    const operation = pathItem[method];
-    if (operation && typeof operation === "object") return method.toUpperCase();
-  }
-  return undefined;
-}
+  function resolveOne(name: string): string {
+    const cached = cache.get(name);
+    if (cached !== undefined) return cached;
 
-function loadOpenApiOperations(specSource: string, docsDir: string): ParsedOpenApiOperationRef[] {
-  if (/^https?:\/\//i.test(specSource) || specSource.startsWith("file://")) return [];
+    if (activeStack.has(name)) {
+      throw new Error(`Circular variable reference detected for '{{${name}}}'.`);
+    }
 
-  const resolvedPath = specSource.startsWith("/")
-    ? join(docsDir, specSource.replace(/^\/+/, ""))
-    : resolve(docsDir, specSource);
-  if (!existsSync(resolvedPath)) return [];
+    const raw = rawVariables[name];
+    if (raw === undefined) {
+      throw new Error(`Undefined variable '{{${name}}}' referenced in variable definitions.`);
+    }
 
-  const parsed = parseOpenApiDocument(readFileSync(resolvedPath, "utf-8"));
-  if (!parsed) return [];
+    activeStack.add(name);
+    const resolved = raw.replace(VARIABLE_TOKEN_PATTERN, (_match, token: string) => resolveOne(token));
+    activeStack.delete(name);
+    cache.set(name, resolved);
+    return resolved;
+  }
 
-  const paths = parsed.paths;
-  const webhooks = parsed.webhooks;
+  const output: Record<string, string> = {};
+  for (const name of Object.keys(rawVariables)) {
+    output[name] = resolveOne(name);
+  }
+  return output;
+}
 
-  const output: ParsedOpenApiOperationRef[] = [];
-  if (paths && typeof paths === "object") {
-    for (const [endpoint, methods] of Object.entries(paths as Record<string, unknown>)) {
-      if (!endpoint.startsWith("/") || !methods || typeof methods !== "object") continue;
-      for (const method of Object.keys(methods as Record<string, unknown>)) {
-        const normalized = method.toLowerCase();
-        if (!OPENAPI_PATH_METHODS.has(normalized)) continue;
-        const operation = (methods as Record<string, unknown>)[method];
-        if (!operation || typeof operation !== "object") continue;
-        if ((operation as Record<string, unknown>)["x-hidden"] === true) continue;
-        const mintMeta = readMintMetadata(operation as Record<string, unknown>);
-        output.push({
-          kind: "path",
-          spec: specSource,
-          method: normalized.toUpperCase(),
-          endpoint,
-          title: mintMeta.title ?? (typeof (operation as Record<string, unknown>).summary === "string" ? String((operation as Record<string, unknown>).summary) : undefined),
-          description: mintMeta.description ?? (typeof (operation as Record<string, unknown>).description === "string" ? String((operation as Record<string, unknown>).description) : undefined),
-          deprecated: mintMeta.deprecated ?? ((operation as Record<string, unknown>).deprecated === true),
-          version: mintMeta.version,
-          content: mintMeta.content,
-        });
-      }
+function replaceVariablesInString(
+  value: string,
+  variables: Record<string, string>,
+  context: string,
+  sanitizeValues: boolean,
+): string {
+  const undefinedVariables = new Set<string>();
+  const replaced = value.replace(VARIABLE_TOKEN_PATTERN, (match, rawName: string) => {
+    const name = rawName.trim();
+    const resolved = variables[name];
+    if (resolved === undefined) {
+      undefinedVariables.add(name);
+      return match;
     }
+    return sanitizeValues ? sanitizeVariableValue(resolved) : resolved;
+  });
+
+  if (undefinedVariables.size > 0) {
+    throw new Error(
+      `Undefined variable(s) ${Array.from(undefinedVariables).map((name) => `'{{${name}}}'`).join(", ")} in ${context}.`
+    );
   }
 
-  if (webhooks && typeof webhooks === "object") {
-    for (const [webhookName, pathItem] of Object.entries(webhooks as Record<string, unknown>)) {
-      if (!pathItem || typeof pathItem !== "object") continue;
-      const resolvedMethod = pickOperationMethod(pathItem as Record<string, unknown>);
-      if (!resolvedMethod) continue;
-      const operation = (pathItem as Record<string, unknown>)[resolvedMethod.toLowerCase()];
-      if (!operation || typeof operation !== "object") continue;
-      if ((operation as Record<string, unknown>)["x-hidden"] === true) continue;
-      const mintMeta = readMintMetadata(operation as Record<string, unknown>);
-      output.push({
-        kind: "webhook",
-        spec: specSource,
-        method: "WEBHOOK",
-        endpoint: webhookName,
-        title: mintMeta.title ?? (typeof (operation as Record<string, unknown>).summary === "string" ? String((operation as Record<string, unknown>).summary) : undefined),
-        description: mintMeta.description ?? (typeof (operation as Record<string, unknown>).description === "string" ? String((operation as Record<string, unknown>).description) : undefined),
-        deprecated: mintMeta.deprecated ?? ((operation as Record<string, unknown>).deprecated === true),
-        version: mintMeta.version,
-        content: mintMeta.content,
-      });
-    }
+  return replaced;
+}
+
+function applyVariablesToConfig(value: unknown, variables: Record<string, string>, path = "docs.json"): unknown {
+  if (typeof value === "string") return replaceVariablesInString(value, variables, path, false);
+  if (Array.isArray(value)) return value.map((entry, index) => applyVariablesToConfig(entry, variables, `${path}[${index}]`));
+  if (!value || typeof value !== "object") return value;
+
+  const output: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+    output[key] = applyVariablesToConfig(entry, variables, `${path}.${key}`);
   }
   return output;
 }
 
-function normalizeOpenApiSpecForFrontmatter(spec: string | undefined): string | undefined {
-  if (!spec) return undefined;
-  const trimmed = spec.trim();
-  if (!trimmed) return undefined;
-  if (/^https?:\/\//i.test(trimmed) || trimmed.startsWith("file://")) return trimmed;
-  if (trimmed.startsWith("/")) return trimmed;
-  return `/${trimmed.replace(/^\.?\/*/, "")}`;
+function loadConfig(docsDir: string): { config: VeluConfig; rawConfig: VeluConfig; variables: Record<string, string> } {
+  const raw = readFileSync(resolveConfigPath(docsDir), "utf-8");
+  const parsed = JSON.parse(raw) as VeluConfig;
+  const rawVariables = extractVariables(parsed.variables);
+  const resolvedVariables = resolveVariableMap(rawVariables);
+  const withVariables = applyVariablesToConfig(parsed, resolvedVariables) as VeluConfig;
+  withVariables.variables = resolvedVariables;
+  return {
+    config: normalizeConfigNavigation(withVariables),
+    rawConfig: withVariables,
+    variables: resolvedVariables,
+  };
 }
 
-// ── Helpers ────────────────────────────────────────────────────────────────────
-
-function loadConfig(docsDir: string): VeluConfig {
-  const raw = readFileSync(resolveConfigPath(docsDir), "utf-8");
-  const parsed = JSON.parse(raw) as VeluConfig;
-  return normalizeConfigNavigation(parsed);
-}
-
 function isExternalDestination(value: string): boolean {
   return /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(value);
 }
@@ -673,27 +783,41 @@ function rewriteImportsInContent(
   return out.join("\n");
 }
 
-function copyMirroredSourceFile(srcPath: string, docsDir: string, mirrorDir: string) {
-  if (!shouldMirrorSourceFile(srcPath)) return;
-  if (!isInsideDocsRoot(docsDir, srcPath)) return;
-
-  const relPath = relative(docsDir, srcPath);
-  const destPath = join(mirrorDir, relPath);
-  mkdirSync(dirname(destPath), { recursive: true });
-
-  if (shouldRewriteImports(srcPath)) {
-    const raw = readFileSync(srcPath, "utf-8");
-    const rewritten = rewriteImportsInContent(raw, srcPath, destPath, docsDir, mirrorDir);
-    writeFileSync(destPath, rewritten, "utf-8");
-    return;
-  }
-
-  copyFileSync(srcPath, destPath);
-}
-
-function rebuildSourceMirror(docsDir: string, mirrorDir: string) {
-  rmSync(mirrorDir, { recursive: true, force: true });
-  mkdirSync(mirrorDir, { recursive: true });
+function copyMirroredSourceFile(
+  srcPath: string,
+  docsDir: string,
+  mirrorDir: string,
+  variables: Record<string, string>,
+) {
+  if (!shouldMirrorSourceFile(srcPath)) return;
+  if (!isInsideDocsRoot(docsDir, srcPath)) return;
+
+  const relPath = relative(docsDir, srcPath);
+  const destPath = join(mirrorDir, relPath);
+  mkdirSync(dirname(destPath), { recursive: true });
+
+  if (shouldRewriteImports(srcPath)) {
+    let raw = readFileSync(srcPath, "utf-8");
+    raw = replaceVariablesInString(raw, variables, relPath, true);
+    const rewritten = rewriteImportsInContent(raw, srcPath, destPath, docsDir, mirrorDir);
+    writeFileSync(destPath, rewritten, "utf-8");
+    return;
+  }
+
+  const extension = extname(srcPath).toLowerCase();
+  if (VARIABLE_SUBSTITUTION_EXTENSIONS.has(extension)) {
+    const raw = readFileSync(srcPath, "utf-8");
+    const substituted = replaceVariablesInString(raw, variables, relPath, true);
+    writeFileSync(destPath, substituted, "utf-8");
+    return;
+  }
+
+  copyFileSync(srcPath, destPath);
+}
+
+function rebuildSourceMirror(docsDir: string, mirrorDir: string, variables: Record<string, string>) {
+  rmSync(mirrorDir, { recursive: true, force: true });
+  mkdirSync(mirrorDir, { recursive: true });
 
   function walk(dir: string) {
     const entries = readdirSync(dir, { withFileTypes: true });
@@ -701,14 +825,14 @@ function rebuildSourceMirror(docsDir: string, mirrorDir: string) {
       if (entry.name.startsWith(".")) continue;
       if (entry.name === "node_modules") continue;
       const srcPath = join(dir, entry.name);
-      if (entry.isDirectory()) {
-        walk(srcPath);
-        continue;
-      }
-      if (!shouldMirrorSourceFile(srcPath)) continue;
-      copyMirroredSourceFile(srcPath, docsDir, mirrorDir);
-    }
-  }
+      if (entry.isDirectory()) {
+        walk(srcPath);
+        continue;
+      }
+      if (!shouldMirrorSourceFile(srcPath)) continue;
+      copyMirroredSourceFile(srcPath, docsDir, mirrorDir, variables);
+    }
+  }
 
   walk(docsDir);
 }
@@ -722,20 +846,20 @@ function pageBasename(page: string): string {
   return page.split("/").pop()!;
 }
 
-interface PageMapping {
-  src: string;   // original page reference
-  dest: string;  // destination path under content/docs (without extension)
-  kind: "file" | "openapi-operation";
-  openapiSpec?: string;
-  openapiMethod?: string;
-  openapiEndpoint?: string;
-  openapiKind?: "path" | "webhook";
-  title?: string;
-  description?: string;
-  deprecated?: boolean;
-  version?: string;
-  content?: string;
-}
+interface PageMapping {
+  src: string;   // original page reference
+  dest: string;  // destination path under content/docs (without extension)
+  kind: "file" | "openapi-operation";
+  openapiSpec?: string;
+  openapiMethod?: string;
+  openapiEndpoint?: string;
+  openapiKind?: "path" | "webhook";
+  title?: string;
+  description?: string;
+  deprecated?: boolean;
+  version?: string;
+  content?: string;
+}
 
 interface MetaFile {
   dir: string;
@@ -748,7 +872,7 @@ interface BuildArtifacts {
   firstPage: string;
 }
 
-function buildArtifacts(config: VeluConfig, docsDirForOpenApi?: string): BuildArtifacts {
+function buildArtifacts(config: VeluConfig, docsDirForOpenApi?: string): BuildArtifacts {
   const pageMap: PageMapping[] = [];
   const metaFiles: MetaFile[] = [];
   const rootTabs = (config.navigation.tabs || []).filter((tab) => !tab.href);
@@ -776,173 +900,173 @@ function buildArtifacts(config: VeluConfig, docsDirForOpenApi?: string): BuildAr
     return String(item);
   }
 
-  function uniqueDestination(dest: string): string {
-    if (!usedDestinations.has(dest)) {
-      usedDestinations.add(dest);
-      return dest;
+  function uniqueDestination(dest: string): string {
+    if (!usedDestinations.has(dest)) {
+      usedDestinations.add(dest);
+      return dest;
     }
     let count = 2;
     while (usedDestinations.has(`${dest}-${count}`)) count += 1;
     const candidate = `${dest}-${count}`;
-    usedDestinations.add(candidate);
-    return candidate;
-  }
-
-  function metaEntryForDestination(baseDir: string, destination: string): string {
-    const fromParts = baseDir.split("/").filter(Boolean);
-    const toParts = destination.split("/").filter(Boolean);
-
-    let index = 0;
-    while (index < fromParts.length && index < toParts.length && fromParts[index] === toParts[index]) {
-      index += 1;
-    }
-
-    const up = Array(fromParts.length - index).fill("..");
-    const down = toParts.slice(index);
-    const rel = [...up, ...down].join("/");
-    return rel || pageBasename(destination);
-  }
-
-  function resolveGenerationDestination(openapi: VeluOpenApiSource | undefined, fallback: string): string {
-    const override = resolveOpenApiDirectory(openapi);
-    if (!override) return fallback;
-    if (!fallback) return override;
-    if (override === fallback || override.startsWith(`${fallback}/`)) return override;
-    return `${fallback}/${override}`;
-  }
+    usedDestinations.add(candidate);
+    return candidate;
+  }
 
-  function toPageMapping(item: string, destDir: string, inheritedSpec?: string): PageMapping {
-    const parsedOpenApi = parseOpenApiOperationRef(item, inheritedSpec);
-    if (!parsedOpenApi) {
-      const basename = pageBasename(item);
-      const dest = uniqueDestination(`${destDir}/${basename}`);
-      return { src: item, dest, kind: "file" };
-    }
+  function metaEntryForDestination(baseDir: string, destination: string): string {
+    const fromParts = baseDir.split("/").filter(Boolean);
+    const toParts = destination.split("/").filter(Boolean);
+
+    let index = 0;
+    while (index < fromParts.length && index < toParts.length && fromParts[index] === toParts[index]) {
+      index += 1;
+    }
+
+    const up = Array(fromParts.length - index).fill("..");
+    const down = toParts.slice(index);
+    const rel = [...up, ...down].join("/");
+    return rel || pageBasename(destination);
+  }
+
+  function resolveGenerationDestination(openapi: VeluOpenApiSource | undefined, fallback: string): string {
+    const override = resolveOpenApiDirectory(openapi);
+    if (!override) return fallback;
+    if (!fallback) return override;
+    if (override === fallback || override.startsWith(`${fallback}/`)) return override;
+    return `${fallback}/${override}`;
+  }
+
+  function toPageMapping(item: string, destDir: string, inheritedSpec?: string): PageMapping {
+    const parsedOpenApi = parseOpenApiOperationRef(item, inheritedSpec);
+    if (!parsedOpenApi) {
+      const basename = pageBasename(item);
+      const dest = uniqueDestination(`${destDir}/${basename}`);
+      return { src: item, dest, kind: "file" };
+    }
 
     const slug = slugFromOpenApiOperation(parsedOpenApi.method, parsedOpenApi.endpoint);
     const dest = uniqueDestination(`${destDir}/${slug}`);
-    return {
-      src: item,
-      dest,
-      kind: "openapi-operation",
-      openapiSpec: parsedOpenApi.spec,
-      openapiMethod: parsedOpenApi.method,
-      openapiEndpoint: parsedOpenApi.endpoint,
-      openapiKind: parsedOpenApi.kind,
-      title: parsedOpenApi.title,
-      description: parsedOpenApi.description,
-      deprecated: parsedOpenApi.deprecated,
-      version: parsedOpenApi.version,
-      content: parsedOpenApi.content,
-    };
-  }
-
-  function resolveInheritedVersion(value: unknown, inherited?: string): string | undefined {
-    if (typeof value === "string" && value.trim().length > 0) return value.trim();
-    return inherited;
-  }
-
-  function toPageMappingWithVersion(
-    item: string,
-    destDir: string,
-    inheritedSpec?: string,
-    inheritedVersion?: string,
-  ): PageMapping {
-    const mapping = toPageMapping(item, destDir, inheritedSpec);
-    if (mapping.kind === "openapi-operation" && mapping.version === undefined) {
-      mapping.version = inheritedVersion;
-    }
-    return mapping;
-  }
-
-  function toOperationMapping(
-    ref: ParsedOpenApiOperationRef,
-    destDir: string,
-    inheritedVersion?: string,
-  ): PageMapping {
-    const slug = slugFromOpenApiOperation(ref.method, ref.endpoint);
-    const dest = uniqueDestination(`${destDir}/${slug}`);
-    return {
-      src: `${ref.spec ? `${ref.spec} ` : ""}${ref.method} ${ref.endpoint}`,
-      dest,
-      kind: "openapi-operation",
-      openapiSpec: ref.spec,
-      openapiMethod: ref.method,
-      openapiEndpoint: ref.endpoint,
-      openapiKind: ref.kind,
-      title: ref.title,
-      description: ref.description,
-      deprecated: ref.deprecated,
-      version: ref.version ?? inheritedVersion,
-      content: ref.content,
-    };
-  }
-
-  function buildOpenApiMappings(
-    openapi: VeluOpenApiSource | undefined,
-    destDir: string,
-    fallbackSpec?: string,
-    inheritedVersion?: string,
-  ): PageMapping[] {
-    if (!docsDirForOpenApi) return [];
-    const specs = resolveOpenApiSpecList(openapi);
-    if (specs.length === 0 && fallbackSpec) specs.push(fallbackSpec);
-    if (specs.length === 0) return [];
-
-    const output: PageMapping[] = [];
-    const seen = new Set<string>();
-    for (const spec of specs) {
-      for (const operation of loadOpenApiOperations(spec, docsDirForOpenApi)) {
-        const key = `${operation.spec ?? ""}::${operation.kind ?? "path"}::${operation.method}::${operation.endpoint}`;
-        if (seen.has(key)) continue;
-        seen.add(key);
-        output.push(toOperationMapping(operation, destDir, inheritedVersion));
-      }
-    }
-    return output;
-  }
-
-  function addGroup(
-    group: VeluGroup,
-    parentDir: string,
-    inheritedOpenApiSpec?: string,
-    inheritedVersion?: string,
-  ) {
-    const groupDir = `${parentDir}/${group.slug}`;
-    const pages: string[] = [];
-    const openApiSpec = resolveDefaultOpenApiSpec(group.openapi) ?? inheritedOpenApiSpec;
-    const groupVersion = resolveInheritedVersion(group.version, inheritedVersion);
-
-    const groupPageItems = Array.isArray(group.pages) ? group.pages : [];
-    for (const item of groupPageItems) {
-      if (typeof item === "string") {
-        const mapping = toPageMappingWithVersion(item, groupDir, openApiSpec, groupVersion);
-        pageMap.push(mapping);
-        pages.push(metaEntryForDestination(groupDir, mapping.dest));
-        trackFirstPage(mapping.dest);
-      } else if (isGroup(item)) {
-        addGroup(item, groupDir, openApiSpec, groupVersion);
-        pages.push(item.hidden ? `!${item.slug}` : item.slug);
-      } else if (isSeparator(item)) {
-        pages.push(`---${item.separator}---`);
-      } else if (isLink(item)) {
+    return {
+      src: item,
+      dest,
+      kind: "openapi-operation",
+      openapiSpec: parsedOpenApi.spec,
+      openapiMethod: parsedOpenApi.method,
+      openapiEndpoint: parsedOpenApi.endpoint,
+      openapiKind: parsedOpenApi.kind,
+      title: parsedOpenApi.title,
+      description: parsedOpenApi.description,
+      deprecated: parsedOpenApi.deprecated,
+      version: parsedOpenApi.version,
+      content: parsedOpenApi.content,
+    };
+  }
+
+  function resolveInheritedVersion(value: unknown, inherited?: string): string | undefined {
+    if (typeof value === "string" && value.trim().length > 0) return value.trim();
+    return inherited;
+  }
+
+  function toPageMappingWithVersion(
+    item: string,
+    destDir: string,
+    inheritedSpec?: string,
+    inheritedVersion?: string,
+  ): PageMapping {
+    const mapping = toPageMapping(item, destDir, inheritedSpec);
+    if (mapping.kind === "openapi-operation" && mapping.version === undefined) {
+      mapping.version = inheritedVersion;
+    }
+    return mapping;
+  }
+
+  function toOperationMapping(
+    ref: ParsedOpenApiOperationRef,
+    destDir: string,
+    inheritedVersion?: string,
+  ): PageMapping {
+    const slug = slugFromOpenApiOperation(ref.method, ref.endpoint);
+    const dest = uniqueDestination(`${destDir}/${slug}`);
+    return {
+      src: `${ref.spec ? `${ref.spec} ` : ""}${ref.method} ${ref.endpoint}`,
+      dest,
+      kind: "openapi-operation",
+      openapiSpec: ref.spec,
+      openapiMethod: ref.method,
+      openapiEndpoint: ref.endpoint,
+      openapiKind: ref.kind,
+      title: ref.title,
+      description: ref.description,
+      deprecated: ref.deprecated,
+      version: ref.version ?? inheritedVersion,
+      content: ref.content,
+    };
+  }
+
+  function buildOpenApiMappings(
+    openapi: VeluOpenApiSource | undefined,
+    destDir: string,
+    fallbackSpec?: string,
+    inheritedVersion?: string,
+  ): PageMapping[] {
+    if (!docsDirForOpenApi) return [];
+    const specs = resolveOpenApiSpecList(openapi);
+    if (specs.length === 0 && fallbackSpec) specs.push(fallbackSpec);
+    if (specs.length === 0) return [];
+
+    const output: PageMapping[] = [];
+    const seen = new Set<string>();
+    for (const spec of specs) {
+      for (const operation of loadOpenApiOperations(spec, docsDirForOpenApi)) {
+        const key = `${operation.spec ?? ""}::${operation.kind ?? "path"}::${operation.method}::${operation.endpoint}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        output.push(toOperationMapping(operation, destDir, inheritedVersion));
+      }
+    }
+    return output;
+  }
+
+  function addGroup(
+    group: VeluGroup,
+    parentDir: string,
+    inheritedOpenApiSpec?: string,
+    inheritedVersion?: string,
+  ) {
+    const groupDir = `${parentDir}/${group.slug}`;
+    const pages: string[] = [];
+    const openApiSpec = resolveDefaultOpenApiSpec(group.openapi) ?? inheritedOpenApiSpec;
+    const groupVersion = resolveInheritedVersion(group.version, inheritedVersion);
+
+    const groupPageItems = Array.isArray(group.pages) ? group.pages : [];
+    for (const item of groupPageItems) {
+      if (typeof item === "string") {
+        const mapping = toPageMappingWithVersion(item, groupDir, openApiSpec, groupVersion);
+        pageMap.push(mapping);
+        pages.push(metaEntryForDestination(groupDir, mapping.dest));
+        trackFirstPage(mapping.dest);
+      } else if (isGroup(item)) {
+        addGroup(item, groupDir, openApiSpec, groupVersion);
+        pages.push(item.hidden ? `!${item.slug}` : item.slug);
+      } else if (isSeparator(item)) {
+        pages.push(`---${item.separator}---`);
+      } else if (isLink(item)) {
         pages.push(
           item.icon
             ? `[${item.icon}][${item.label}](${item.href})`
             : `[${item.label}](${item.href})`
         );
-      }
-    }
-
-    if (groupPageItems.length === 0 && group.openapi !== undefined) {
-      const generatedDestDir = resolveGenerationDestination(group.openapi, groupDir);
-      const generatedMappings = buildOpenApiMappings(group.openapi, generatedDestDir, openApiSpec, groupVersion);
-      for (const mapping of generatedMappings) {
-        pageMap.push(mapping);
-        pages.push(metaEntryForDestination(groupDir, mapping.dest));
-        trackFirstPage(mapping.dest);
-      }
-    }
+      }
+    }
+
+    if (groupPageItems.length === 0 && group.openapi !== undefined) {
+      const generatedDestDir = resolveGenerationDestination(group.openapi, groupDir);
+      const generatedMappings = buildOpenApiMappings(group.openapi, generatedDestDir, openApiSpec, groupVersion);
+      for (const mapping of generatedMappings) {
+        pageMap.push(mapping);
+        pages.push(metaEntryForDestination(groupDir, mapping.dest));
+        trackFirstPage(mapping.dest);
+      }
+    }
 
     const groupMeta: Record<string, unknown> = {
       title: group.group,
@@ -957,41 +1081,41 @@ function buildArtifacts(config: VeluConfig, docsDirForOpenApi?: string): BuildAr
     metaFiles.push({ dir: groupDir, data: groupMeta });
   }
 
-  for (const tab of rootTabs) {
-    const tabPages: string[] = [];
-    const tabOpenApiSpec = resolveDefaultOpenApiSpec(tab.openapi) ?? defaultOpenApiSpec;
-    const tabVersion = resolveInheritedVersion(tab.version);
-
-    if (tab.groups) {
-      for (const group of tab.groups) {
-        addGroup(group, tab.slug, tabOpenApiSpec, tabVersion);
-        tabPages.push(group.hidden ? `!${group.slug}` : group.slug);
-      }
-    }
+  for (const tab of rootTabs) {
+    const tabPages: string[] = [];
+    const tabOpenApiSpec = resolveDefaultOpenApiSpec(tab.openapi) ?? defaultOpenApiSpec;
+    const tabVersion = resolveInheritedVersion(tab.version);
 
-    const tabPageItems = Array.isArray(tab.pages) ? tab.pages : [];
-    if (tabPageItems.length > 0) {
-      for (const item of tabPageItems) {
-        if (typeof item === "string") {
-          const mapping = toPageMappingWithVersion(item, tab.slug, tabOpenApiSpec, tabVersion);
-          pageMap.push(mapping);
-          tabPages.push(metaEntryForDestination(tab.slug, mapping.dest));
-          trackFirstPage(mapping.dest);
-        } else {
-          tabPages.push(metaEntry(item));
-        }
-      }
-    }
-
-    if ((tab.groups?.length ?? 0) === 0 && tabPageItems.length === 0 && tab.openapi !== undefined) {
-      const generatedDestDir = resolveGenerationDestination(tab.openapi, tab.slug);
-      const generatedMappings = buildOpenApiMappings(tab.openapi, generatedDestDir, tabOpenApiSpec, tabVersion);
-      for (const mapping of generatedMappings) {
-        pageMap.push(mapping);
-        tabPages.push(metaEntryForDestination(tab.slug, mapping.dest));
-        trackFirstPage(mapping.dest);
-      }
-    }
+    if (tab.groups) {
+      for (const group of tab.groups) {
+        addGroup(group, tab.slug, tabOpenApiSpec, tabVersion);
+        tabPages.push(group.hidden ? `!${group.slug}` : group.slug);
+      }
+    }
+
+    const tabPageItems = Array.isArray(tab.pages) ? tab.pages : [];
+    if (tabPageItems.length > 0) {
+      for (const item of tabPageItems) {
+        if (typeof item === "string") {
+          const mapping = toPageMappingWithVersion(item, tab.slug, tabOpenApiSpec, tabVersion);
+          pageMap.push(mapping);
+          tabPages.push(metaEntryForDestination(tab.slug, mapping.dest));
+          trackFirstPage(mapping.dest);
+        } else {
+          tabPages.push(metaEntry(item));
+        }
+      }
+    }
+
+    if ((tab.groups?.length ?? 0) === 0 && tabPageItems.length === 0 && tab.openapi !== undefined) {
+      const generatedDestDir = resolveGenerationDestination(tab.openapi, tab.slug);
+      const generatedMappings = buildOpenApiMappings(tab.openapi, generatedDestDir, tabOpenApiSpec, tabVersion);
+      for (const mapping of generatedMappings) {
+        pageMap.push(mapping);
+        tabPages.push(metaEntryForDestination(tab.slug, mapping.dest));
+        trackFirstPage(mapping.dest);
+      }
+    }
 
     const tabMeta: Record<string, unknown> = {
       title: tab.tab,
@@ -1014,11 +1138,11 @@ function buildArtifacts(config: VeluConfig, docsDirForOpenApi?: string): BuildAr
 
 // ── Build ──────────────────────────────────────────────────────────────────────
 
-function build(docsDir: string, outDir: string) {
-  const configPath = resolveConfigPath(docsDir);
-  const configName = configPath.endsWith(PRIMARY_CONFIG_NAME) ? PRIMARY_CONFIG_NAME : LEGACY_CONFIG_NAME;
-  console.log(`📖 Loading ${configName} from: ${docsDir}`);
-  const config = loadConfig(docsDir);
+function build(docsDir: string, outDir: string) {
+  const configPath = resolveConfigPath(docsDir);
+  const configName = configPath.endsWith(PRIMARY_CONFIG_NAME) ? PRIMARY_CONFIG_NAME : LEGACY_CONFIG_NAME;
+  console.log(`📖 Loading ${configName} from: ${docsDir}`);
+  const { config, rawConfig, variables } = loadConfig(docsDir);
 
   if (existsSync(outDir)) {
     rmSync(outDir, { recursive: true, force: true });
@@ -1031,15 +1155,16 @@ function build(docsDir: string, outDir: string) {
   console.log("📦 Copied engine files");
 
   // ── 2. Create additional directories ─────────────────────────────────────
-  mkdirSync(join(outDir, "content", "docs"), { recursive: true });
-  mkdirSync(join(outDir, "public"), { recursive: true });
-  const sourceMirrorDir = join(outDir, SOURCE_MIRROR_DIR);
-  rebuildSourceMirror(docsDir, sourceMirrorDir);
+  mkdirSync(join(outDir, "content", "docs"), { recursive: true });
+  mkdirSync(join(outDir, "public"), { recursive: true });
+  const sourceMirrorDir = join(outDir, SOURCE_MIRROR_DIR);
+  rebuildSourceMirror(docsDir, sourceMirrorDir, variables);
 
   // ── 3. Copy config into the generated project ────────────────────────────
-  copyFileSync(configPath, join(outDir, PRIMARY_CONFIG_NAME));
-  copyFileSync(configPath, join(outDir, LEGACY_CONFIG_NAME));
-  console.log(`📋 Copied ${configName} as ${PRIMARY_CONFIG_NAME} (and legacy ${LEGACY_CONFIG_NAME})`);
+  const serializedConfig = `${JSON.stringify(rawConfig, null, 2)}\n`;
+  writeFileSync(join(outDir, PRIMARY_CONFIG_NAME), serializedConfig, "utf-8");
+  writeFileSync(join(outDir, LEGACY_CONFIG_NAME), serializedConfig, "utf-8");
+  console.log(`📋 Copied ${configName} as ${PRIMARY_CONFIG_NAME} (and legacy ${LEGACY_CONFIG_NAME})`);
 
   // ── 3b. Copy static assets from docs project into public/ ─────────────────
   copyStaticAssets(docsDir, join(outDir, "public"));
@@ -1054,12 +1179,13 @@ function build(docsDir: string, outDir: string) {
   const navLanguages = config.navigation.languages;
   const simpleLanguages = config.languages || [];
 
-  function processPage(srcPath: string, destPath: string, slug: string) {
-    mkdirSync(dirname(destPath), { recursive: true });
-    let content = readFileSync(srcPath, "utf-8");
-    if (!content.startsWith("---")) {
-      const titleMatch = content.match(/^#\s+(.+)$/m);
-      const title = titleMatch ? titleMatch[1] : pageLabelFromSlug(slug);
+  function processPage(srcPath: string, destPath: string, slug: string) {
+    mkdirSync(dirname(destPath), { recursive: true });
+    let content = readFileSync(srcPath, "utf-8");
+    content = replaceVariablesInString(content, variables, relative(docsDir, srcPath), true);
+    if (!content.startsWith("---")) {
+      const titleMatch = content.match(/^#\s+(.+)$/m);
+      const title = titleMatch ? titleMatch[1] : pageLabelFromSlug(slug);
       if (titleMatch) {
         content = content.replace(/^#\s+.+$/m, "").trimStart();
       }
@@ -1069,12 +1195,12 @@ function build(docsDir: string, outDir: string) {
     writeFileSync(destPath, content, "utf-8");
   }
 
-  function writeLangContent(
-    langCode: string,
-    artifacts: BuildArtifacts,
-    isDefault: boolean,
-    useLangFolders = false
-  ) {
+  function writeLangContent(
+    langCode: string,
+    artifacts: BuildArtifacts,
+    isDefault: boolean,
+    useLangFolders = false
+  ) {
     const storagePrefix = useLangFolders ? langCode : (isDefault ? "" : langCode);
     const urlPrefix = isDefault ? "" : langCode;
 
@@ -1082,53 +1208,55 @@ function build(docsDir: string, outDir: string) {
     const metas = storagePrefix
       ? artifacts.metaFiles.map((m) => ({ dir: m.dir ? `${storagePrefix}/${m.dir}` : storagePrefix, data: { ...m.data } }))
       : artifacts.metaFiles;
-    for (const meta of metas) {
-      const metaPath = join(contentDir, meta.dir, "meta.json");
-      mkdirSync(dirname(metaPath), { recursive: true });
-      writeFileSync(metaPath, JSON.stringify(meta.data, null, 2) + "\n", "utf-8");
-    }
-
-    function sanitizeFrontmatterValue(value: string): string {
-      return value.replace(/\r?\n+/g, " ").replace(/"/g, '\\"').trim();
-    }
-
-    // Copy pages using explicit source paths from docs.json/velu.json
-    for (const mapping of artifacts.pageMap) {
+    for (const meta of metas) {
+      const metaPath = join(contentDir, meta.dir, "meta.json");
+      mkdirSync(dirname(metaPath), { recursive: true });
+      writeFileSync(metaPath, JSON.stringify(meta.data, null, 2) + "\n", "utf-8");
+    }
+
+    function sanitizeFrontmatterValue(value: string): string {
+      return value.replace(/\r?\n+/g, " ").replace(/"/g, '\\"').trim();
+    }
+
+    // Copy pages using explicit source paths from docs.json/velu.json
+    for (const mapping of artifacts.pageMap) {
       const destPath = join(
         contentDir,
         storagePrefix ? `${storagePrefix}/${mapping.dest}.mdx` : `${mapping.dest}.mdx`,
       );
 
-      if (mapping.kind === "openapi-operation") {
-        mkdirSync(dirname(destPath), { recursive: true });
-        const operationLabel = `${mapping.openapiMethod ?? "GET"} ${mapping.openapiEndpoint ?? "/"}`;
-        const normalizedSpec = normalizeOpenApiSpecForFrontmatter(mapping.openapiSpec);
-        const openapiValue = normalizedSpec
-          ? `${normalizedSpec} ${operationLabel}`
-          : operationLabel;
-        const title = sanitizeFrontmatterValue(mapping.title ?? operationLabel);
-        const description = typeof mapping.description === "string"
-          ? sanitizeFrontmatterValue(mapping.description)
-          : "";
-        const version = typeof mapping.version === "string"
-          ? sanitizeFrontmatterValue(mapping.version)
-          : "";
-        const openapi = openapiValue.replace(/"/g, '\\"');
-        const warning = normalizedSpec
-          ? ""
-          : "\n> Warning: No OpenAPI spec source was resolved for this operation. Set `openapi` on this tab/group/navigation or at the top level.\n";
-        const descriptionLine = description ? `\ndescription: "${description}"` : "";
-        const deprecatedLine = mapping.deprecated === true ? `\ndeprecated: true` : "";
-        const statusLine = mapping.deprecated === true ? `\nstatus: "deprecated"` : "";
+      if (mapping.kind === "openapi-operation") {
+        mkdirSync(dirname(destPath), { recursive: true });
+        const operationLabel = `${mapping.openapiMethod ?? "GET"} ${mapping.openapiEndpoint ?? "/"}`;
+        const normalizedSpec = normalizeOpenApiSpecForFrontmatter(mapping.openapiSpec);
+        const openapiValue = normalizedSpec
+          ? `${normalizedSpec} ${operationLabel}`
+          : operationLabel;
+        const title = sanitizeFrontmatterValue(mapping.title ?? operationLabel);
+        const description = typeof mapping.description === "string"
+          ? sanitizeFrontmatterValue(mapping.description)
+          : "";
+        const version = typeof mapping.version === "string"
+          ? sanitizeFrontmatterValue(mapping.version)
+          : "";
+        const openapi = openapiValue.replace(/"/g, '\\"');
+        const warning = normalizedSpec
+          ? ""
+          : "\n> Warning: No OpenAPI spec source was resolved for this operation. Set `openapi` on this tab/group/navigation or at the top level.\n";
+        const descriptionLine = description ? `\ndescription: "${description}"` : "";
+        const deprecatedLine = mapping.deprecated === true ? `\ndeprecated: true` : "";
+        const statusLine = mapping.deprecated === true ? `\nstatus: "deprecated"` : "";
         const versionLine = version ? `\nversion: "${version}"` : "";
-        const content = typeof mapping.content === "string" ? `${mapping.content.trim()}\n` : "";
+        const content = typeof mapping.content === "string"
+          ? `${replaceVariablesInString(mapping.content.trim(), variables, `openapi:${mapping.dest}`, true)}\n`
+          : "";
         writeFileSync(
-          destPath,
-          `---\ntitle: "${title}"${descriptionLine}${deprecatedLine}${statusLine}${versionLine}\nopenapi: "${openapi}"\n---\n${warning}${content}`,
-          "utf-8",
-        );
-        continue;
-      }
+          destPath,
+          `---\ntitle: "${title}"${descriptionLine}${deprecatedLine}${statusLine}${versionLine}\nopenapi: "${openapi}"\n---\n${warning}${content}`,
+          "utf-8",
+        );
+        continue;
+      }
 
       const src = mapping.src;
       // Check for .mdx first, then .md
@@ -1138,10 +1266,10 @@ function build(docsDir: string, outDir: string) {
         srcPath = join(docsDir, `${src}.md`);
         ext = ".md";
       }
-      if (!existsSync(srcPath)) {
-        console.warn(`Warning: Missing page source: ${src}${ext} (language: ${langCode})`);
-        continue;
-      }
+      if (!existsSync(srcPath)) {
+        console.warn(`Warning: Missing page source: ${src}${ext} (language: ${langCode})`);
+        continue;
+      }
       processPage(srcPath, destPath, src);
     }
 
@@ -1166,7 +1294,7 @@ function build(docsDir: string, outDir: string) {
       const langEntry = navLanguages[i];
       const isDefault = i === 0;
       const langConfig = { ...config, navigation: { ...config.navigation, tabs: langEntry.tabs } } as VeluConfig;
-      const artifacts = buildArtifacts(langConfig, docsDir);
+      const artifacts = buildArtifacts(langConfig, docsDir);
       writeLangContent(langEntry.language, artifacts, isDefault, true);
       totalPages += artifacts.pageMap.length;
       totalMeta += artifacts.metaFiles.length;
@@ -1177,7 +1305,7 @@ function build(docsDir: string, outDir: string) {
     writeFileSync(rootMetaPath, JSON.stringify({ pages: rootPages }, null, 2) + "\n", "utf-8");
   } else {
     // ── Mode 2: Simple (single-lang or same-nav multi-lang) ───────────
-    const artifacts = buildArtifacts(config, docsDir);
+    const artifacts = buildArtifacts(config, docsDir);
     const useLangFolders = simpleLanguages.length > 1;
     writeLangContent(simpleLanguages[0] || "en", artifacts, true, useLangFolders);
     totalPages += artifacts.pageMap.length;