@aravindc26/velu 0.11.16 → 0.11.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aravindc26/velu",
-  "version": "0.11.16",
+  "version": "0.11.17",
   "description": "A modern documentation site generator powered by Markdown and JSON configuration",
   "type": "module",
   "license": "MIT",

package/schema/velu.schema.json

@@ -92,6 +92,26 @@
       ],
       "default": "system"
     },
+    "fonts": {
+      "description": "Custom font configuration. Can be a single font definition (applied to both headings and body) or an object with separate heading and body font definitions.",
+      "oneOf": [
+        { "$ref": "#/definitions/fontDefinition" },
+        {
+          "type": "object",
+          "properties": {
+            "heading": {
+              "$ref": "#/definitions/fontDefinition",
+              "description": "Font used for headings (h1–h6)."
+            },
+            "body": {
+              "$ref": "#/definitions/fontDefinition",
+              "description": "Font used for body text."
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
     "icons": {
       "type": "object",
       "description": "Icon settings compatible with Mint-style configuration.",
@@ -112,44 +132,6 @@
       ],
       "additionalProperties": false
     },
-    "styling": {
-      "type": "object",
-      "description": "Fine-grained styling options.",
-      "properties": {
-        "codeblocks": {
-          "type": "object",
-          "description": "Code block styling options.",
-          "properties": {
-            "theme": {
-              "description": "Shiki theme for syntax highlighting. Use a string for a single theme, or an object with light/dark keys.",
-              "oneOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "object",
-                  "properties": {
-                    "light": {
-                      "type": "string"
-                    },
-                    "dark": {
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "light",
-                    "dark"
-                  ],
-                  "additionalProperties": false
-                }
-              ]
-            }
-          },
-          "additionalProperties": false
-        }
-      },
-      "additionalProperties": false
-    },
     "languages": {
       "type": "array",
       "description": "Supported language codes (e.g. [\"en\", \"es\", \"ja\"]). The first is the default. Display labels are auto-derived.",
@@ -658,6 +640,32 @@
   },
   "additionalProperties": false,
   "definitions": {
+    "fontDefinition": {
+      "type": "object",
+      "description": "A font definition with family name and optional weight, source URL, and format.",
+      "properties": {
+        "family": {
+          "type": "string",
+          "description": "The font family name, e.g. \"Inter\", \"Playfair Display\"."
+        },
+        "weight": {
+          "type": "number",
+          "description": "The font weight, e.g. 400, 700. Variable font weights like 550 are supported."
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1,
+          "description": "URL or path to a custom font file, e.g. /fonts/custom.woff2 or https://example.com/font.woff2."
+        },
+        "format": {
+          "type": "string",
+          "enum": ["woff", "woff2"],
+          "description": "The font file format when using a custom source."
+        }
+      },
+      "required": ["family"],
+      "additionalProperties": false
+    },
     "footerSocials": {
       "type": "object",
       "description": "Map of social network keys to URLs (for example {\"x\":\"https://x.com/org\",\"github\":\"https://github.com/org\"}).",

package/src/build.ts

@@ -2,19 +2,19 @@ import { readFileSync, writeFileSync, mkdirSync, copyFileSync, cpSync, existsSyn
 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 { generateThemeCss, resolveThemeName, type VeluColors } from "./themes.js";
 import { normalizeConfigNavigation } from "./navigation-normalize.js";
 
 // ── Engine directory (shipped with the CLI package) ──────────────────────────
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PACKAGED_ENGINE_DIR = join(__dirname, "engine");
-const DEV_ENGINE_DIR = join(__dirname, "..", "src", "engine");
-const ENGINE_DIR = existsSync(DEV_ENGINE_DIR) ? DEV_ENGINE_DIR : PACKAGED_ENGINE_DIR;
-const CLI_PACKAGE_JSON_PATH = join(__dirname, "..", "package.json");
-const PRIMARY_CONFIG_NAME = "docs.json";
-const LEGACY_CONFIG_NAME = "velu.json";
-const SOURCE_MIRROR_DIR = "velu-imports";
+const DEV_ENGINE_DIR = join(__dirname, "..", "src", "engine");
+const ENGINE_DIR = existsSync(DEV_ENGINE_DIR) ? DEV_ENGINE_DIR : PACKAGED_ENGINE_DIR;
+const CLI_PACKAGE_JSON_PATH = join(__dirname, "..", "package.json");
+const PRIMARY_CONFIG_NAME = "docs.json";
+const LEGACY_CONFIG_NAME = "velu.json";
+const SOURCE_MIRROR_DIR = "velu-imports";
 
 const SOURCE_MIRROR_EXTENSIONS = new Set([
   ".md", ".mdx", ".jsx", ".js", ".tsx", ".ts",
@@ -25,11 +25,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 VARIABLE_SUBSTITUTION_EXTENSIONS = new Set([
-  ".md", ".mdx", ".jsx", ".js", ".tsx", ".ts",
-  ".json", ".yaml", ".yml", ".css", ".txt", ".xml", ".csv",
-]);
+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);
@@ -136,22 +136,22 @@ interface VeluRedirect {
   permanent?: boolean;
 }
 
-interface VeluConfig {
-  $schema?: string;
-  name?: string;
-  title?: string;
-  description?: string;
-  theme?: string;
-  variables?: Record<string, string>;
-  colors?: VeluColors;
-  appearance?: "system" | "light" | "dark";
-  styling?: VeluStyling;
-  metadata?: {
-    timestamp?: boolean;
-  };
-  openapi?: VeluOpenApiSource;
-  languages?: string[];
-  redirects?: VeluRedirect[];
+interface VeluConfig {
+  $schema?: string;
+  name?: string;
+  title?: string;
+  description?: string;
+  theme?: string;
+  variables?: Record<string, string>;
+  colors?: VeluColors;
+  appearance?: "system" | "light" | "dark";
+  fonts?: { family: string; weight?: number; source?: string; format?: "woff" | "woff2" } | { heading?: { family: string; weight?: number; source?: string; format?: "woff" | "woff2" }; body?: { family: string; weight?: number; source?: string; format?: "woff" | "woff2" } };
+  metadata?: {
+    timestamp?: boolean;
+  };
+  openapi?: VeluOpenApiSource;
+  languages?: string[];
+  redirects?: VeluRedirect[];
   navigation: {
     openapi?: VeluOpenApiSource;
     tabs?: VeluTab[];
@@ -405,115 +405,115 @@ function normalizeOpenApiSpecForFrontmatter(spec: string | undefined): string |
   return `/${trimmed.replace(/^\.?\/*/, "")}`;
 }
 
-// ── Helpers ────────────────────────────────────────────────────────────────────
-
-const VARIABLE_TOKEN_PATTERN = /\{\{\s*([A-Za-z0-9.-]+)\s*\}\}/g;
-const VARIABLE_NAME_PATTERN = /^[A-Za-z0-9.-]+$/;
-
-function sanitizeVariableValue(value: string): string {
-  return value.replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}
-
-function extractVariables(input: unknown): Record<string, string> {
-  if (!input || typeof input !== "object" || Array.isArray(input)) return {};
-
-  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 output;
-}
-
-function resolveVariableMap(rawVariables: Record<string, string>): Record<string, string> {
-  const cache = new Map<string, string>();
-  const activeStack = new Set<string>();
-
-  function resolveOne(name: string): string {
-    const cached = cache.get(name);
-    if (cached !== undefined) return cached;
-
-    if (activeStack.has(name)) {
-      throw new Error(`Circular variable reference detected for '{{${name}}}'.`);
-    }
-
-    const raw = rawVariables[name];
-    if (raw === undefined) {
-      throw new Error(`Undefined variable '{{${name}}}' referenced in variable definitions.`);
-    }
-
-    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 output: Record<string, string> = {};
-  for (const name of Object.keys(rawVariables)) {
-    output[name] = resolveOne(name);
-  }
-  return output;
-}
-
-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}.`
-    );
-  }
-
-  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 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 ────────────────────────────────────────────────────────────────────
+
+const VARIABLE_TOKEN_PATTERN = /\{\{\s*([A-Za-z0-9.-]+)\s*\}\}/g;
+const VARIABLE_NAME_PATTERN = /^[A-Za-z0-9.-]+$/;
+
+function sanitizeVariableValue(value: string): string {
+  return value.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function extractVariables(input: unknown): Record<string, string> {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return {};
+
+  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 output;
+}
+
+function resolveVariableMap(rawVariables: Record<string, string>): Record<string, string> {
+  const cache = new Map<string, string>();
+  const activeStack = new Set<string>();
+
+  function resolveOne(name: string): string {
+    const cached = cache.get(name);
+    if (cached !== undefined) return cached;
+
+    if (activeStack.has(name)) {
+      throw new Error(`Circular variable reference detected for '{{${name}}}'.`);
+    }
+
+    const raw = rawVariables[name];
+    if (raw === undefined) {
+      throw new Error(`Undefined variable '{{${name}}}' referenced in variable definitions.`);
+    }
+
+    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 output: Record<string, string> = {};
+  for (const name of Object.keys(rawVariables)) {
+    output[name] = resolveOne(name);
+  }
+  return output;
+}
+
+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}.`
+    );
+  }
+
+  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 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,
+  };
+}
 
 function isExternalDestination(value: string): boolean {
   return /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(value);
@@ -591,7 +591,7 @@ const STATIC_EXTENSIONS = new Set([
   ".zip",
 ]);
 
-function copyStaticAssets(docsDir: string, publicDir: string) {
+function copyStaticAssets(docsDir: string, publicDir: string) {
   function walk(dir: string) {
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
@@ -615,49 +615,49 @@ function copyStaticAssets(docsDir: string, publicDir: string) {
     }
   }
 
-  walk(docsDir);
-}
-
-function resolveProjectName(config: VeluConfig): string {
-  const fromName = typeof config.name === "string" ? config.name.trim() : "";
-  if (fromName) return fromName;
-  const fromTitle = typeof config.title === "string" ? config.title.trim() : "";
-  if (fromTitle) return fromTitle;
-  return "Documentation";
-}
-
-function resolveProjectDescription(config: VeluConfig): string {
-  if (typeof config.description === "string") return config.description.trim();
-  return "";
-}
-
-function resolveCliVersion(): string {
-  try {
-    const raw = readFileSync(CLI_PACKAGE_JSON_PATH, "utf-8");
-    const parsed = JSON.parse(raw) as { version?: unknown };
-    if (typeof parsed.version === "string" && parsed.version.trim().length > 0) {
-      return parsed.version.trim();
-    }
-  } catch {
-    // ignore and fallback
-  }
-  return "unknown";
-}
-
-function writeProjectConstFile(config: VeluConfig, outDir: string) {
-  const constPayload = {
-    name: resolveProjectName(config),
-    description: resolveProjectDescription(config),
-    version: resolveCliVersion(),
-  };
-
-  const constPath = join(outDir, "public", "const.json");
-  writeFileSync(constPath, `${JSON.stringify(constPayload, null, 2)}\n`, "utf-8");
-}
-
-function toPosixPath(value: string): string {
-  return value.replace(/\\/g, "/");
-}
+  walk(docsDir);
+}
+
+function resolveProjectName(config: VeluConfig): string {
+  const fromName = typeof config.name === "string" ? config.name.trim() : "";
+  if (fromName) return fromName;
+  const fromTitle = typeof config.title === "string" ? config.title.trim() : "";
+  if (fromTitle) return fromTitle;
+  return "Documentation";
+}
+
+function resolveProjectDescription(config: VeluConfig): string {
+  if (typeof config.description === "string") return config.description.trim();
+  return "";
+}
+
+function resolveCliVersion(): string {
+  try {
+    const raw = readFileSync(CLI_PACKAGE_JSON_PATH, "utf-8");
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    if (typeof parsed.version === "string" && parsed.version.trim().length > 0) {
+      return parsed.version.trim();
+    }
+  } catch {
+    // ignore and fallback
+  }
+  return "unknown";
+}
+
+function writeProjectConstFile(config: VeluConfig, outDir: string) {
+  const constPayload = {
+    name: resolveProjectName(config),
+    description: resolveProjectDescription(config),
+    version: resolveCliVersion(),
+  };
+
+  const constPath = join(outDir, "public", "const.json");
+  writeFileSync(constPath, `${JSON.stringify(constPayload, null, 2)}\n`, "utf-8");
+}
+
+function toPosixPath(value: string): string {
+  return value.replace(/\\/g, "/");
+}
 
 function isInsideDocsRoot(docsDir: string, targetPath: string): boolean {
   const relPath = relative(docsDir, targetPath);
@@ -824,41 +824,41 @@ function rewriteImportsInContent(
   return out.join("\n");
 }
 
-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 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 });
@@ -866,14 +866,14 @@ function rebuildSourceMirror(docsDir: string, mirrorDir: string, variables: Reco
       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, variables);
-    }
-  }
+      if (entry.isDirectory()) {
+        walk(srcPath);
+        continue;
+      }
+      if (!shouldMirrorSourceFile(srcPath)) continue;
+      copyMirroredSourceFile(srcPath, docsDir, mirrorDir, variables);
+    }
+  }
 
   walk(docsDir);
 }
@@ -1179,11 +1179,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, rawConfig, variables } = 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 });
@@ -1196,39 +1196,39 @@ 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, variables);
+  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 ────────────────────────────
-  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})`);
+  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"));
-  writeRedirectArtifacts(config, outDir);
-  writeProjectConstFile(rawConfig, outDir);
-  if ((config.redirects ?? []).length > 0) {
-    console.log("↪️  Generated redirect artifacts");
-  }
-  console.log("🧾 Generated const.json");
-  console.log("🖼️  Copied static assets");
+  copyStaticAssets(docsDir, join(outDir, "public"));
+  writeRedirectArtifacts(config, outDir);
+  writeProjectConstFile(rawConfig, outDir);
+  if ((config.redirects ?? []).length > 0) {
+    console.log("↪️  Generated redirect artifacts");
+  }
+  console.log("🧾 Generated const.json");
+  console.log("🖼️  Copied static assets");
 
   // ── 4. Build content + metadata artifacts ────────────────────────────────
   const contentDir = join(outDir, "content", "docs");
   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");
-    content = replaceVariablesInString(content, variables, relative(docsDir, srcPath), true);
-    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();
       }
@@ -1289,11 +1289,11 @@ function build(docsDir: string, outDir: string) {
         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"
-          ? `${replaceVariablesInString(mapping.content.trim(), variables, `openapi:${mapping.dest}`, true)}\n`
-          : "";
-        writeFileSync(
+        const versionLine = version ? `\nversion: "${version}"` : "";
+        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",
@@ -1370,11 +1370,22 @@ function build(docsDir: string, outDir: string) {
   console.log(`📄 Generated ${totalPages} pages + ${totalMeta} navigation meta files`);
 
   // ── 5. Generate theme CSS (dynamic — depends on user config) ─────────────
+  // Resolve fonts config into { heading?, body? } shape
+  const resolvedFonts = (() => {
+    const raw = config.fonts;
+    if (!raw) return undefined;
+    if ('family' in raw && typeof (raw as Record<string, unknown>).family === 'string') {
+      return { heading: raw as { family: string; weight?: number; source?: string; format?: "woff" | "woff2" }, body: raw as { family: string; weight?: number; source?: string; format?: "woff" | "woff2" } };
+    }
+    const obj = raw as { heading?: { family: string; weight?: number; source?: string; format?: "woff" | "woff2" }; body?: { family: string; weight?: number; source?: string; format?: "woff" | "woff2" } };
+    return (obj.heading || obj.body) ? obj : undefined;
+  })();
+
   const themeCss = generateThemeCss({
     theme: config.theme,
     colors: config.colors,
     appearance: config.appearance,
-    styling: config.styling,
+    fonts: resolvedFonts,
   });
   writeFileSync(join(outDir, "app", "velu-theme.css"), themeCss, "utf-8");
   console.log(`🎨 Generated theme: ${resolveThemeName(config.theme)}`);

package/src/cli.ts

@@ -1,5 +1,5 @@
 import { resolve, join, dirname, delimiter } from "node:path";
-import { existsSync, mkdirSync, writeFileSync, readdirSync, copyFileSync, cpSync, rmSync, renameSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, readdirSync, copyFileSync, cpSync, rmSync, renameSync, readFileSync, statSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
@@ -237,6 +237,19 @@ function samePath(a: string, b: string): boolean {
   return resolve(a).replace(/\\/g, "/").toLowerCase() === resolve(b).replace(/\\/g, "/").toLowerCase();
 }
 
+function copyDirMerge(src: string, dest: string): void {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyDirMerge(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
 function prepareRuntimeOutDir(docsOutDir: string): string {
   const runtimeOutDir = join(PACKAGE_ROOT, ".velu-out");
   if (samePath(docsOutDir, runtimeOutDir)) return runtimeOutDir;
@@ -249,13 +262,24 @@ function prepareRuntimeOutDir(docsOutDir: string): string {
     const stale = `${runtimeOutDir}-stale-${Date.now()}`;
     try {
       renameSync(runtimeOutDir, stale);
-      // Best-effort async cleanup — ignore errors if still locked.
       try { rmSync(stale, { recursive: true, force: true }); } catch {}
     } catch {
-      // If even rename fails, try to overwrite in place.
+      // If even rename fails, clear contents so cpSync can work.
+      try {
+        for (const entry of readdirSync(runtimeOutDir)) {
+          rmSync(join(runtimeOutDir, entry), { recursive: true, force: true });
+        }
+      } catch {}
     }
   }
-  cpSync(docsOutDir, runtimeOutDir, { recursive: true, force: true });
+
+  if (existsSync(runtimeOutDir)) {
+    // cpSync fails with EEXIST when the destination directory exists (Node 20).
+    // Fall back to a manual recursive copy that handles existing directories.
+    copyDirMerge(docsOutDir, runtimeOutDir);
+  } else {
+    cpSync(docsOutDir, runtimeOutDir, { recursive: true, force: true });
+  }
   return runtimeOutDir;
 }
 

package/src/engine/app/global.css

@@ -987,14 +987,14 @@ nextjs-portal {
   display: grid !important;
   grid-template-columns: 2.25rem minmax(0, 1fr);
   column-gap: 0.75rem;
-  align-items: start !important;
+  align-items: center !important;
 }
 
 [data-card].velu-card-horizontal > div.not-prose {
   grid-row: 1 / span 3;
   margin-bottom: 0;
-  margin-top: 0.02rem;
-  align-self: start;
+  margin-top: 0;
+  align-self: center;
   justify-self: start;
 }
 

package/src/engine/app/layout.tsx

@@ -1,6 +1,6 @@
 import type { Metadata } from 'next';
 import type { ReactNode } from 'react';
-import { getAppearance, getBannerConfig, getSeoConfig, getSiteDescription, getSiteFavicon, getSiteName, getSiteOrigin, getSitePrimaryColor } from '@/lib/velu';
+import { getAppearance, getBannerConfig, getFontsConfig, getSeoConfig, getSiteDescription, getSiteFavicon, getSiteName, getSiteOrigin, getSitePrimaryColor } from '@/lib/velu';
 import { Providers } from '@/components/providers';
 import { VeluAssistant } from '@/components/assistant';
 import { VeluBanner } from '@/components/banner';
@@ -24,6 +24,7 @@ const seo = getSeoConfig();
 const favicon = getSiteFavicon();
 const primaryColor = getSitePrimaryColor();
 const bannerConfig = getBannerConfig();
+const fontsConfig = getFontsConfig();
 const generatedDefaultSocialImage = '/og/index.svg';
 const defaultSocialImage = seo.metatags['og:image'] ?? seo.metatags['twitter:image'] ?? generatedDefaultSocialImage;
 const absoluteDefaultSocialImage = defaultSocialImage ? toAbsoluteUrl(siteOrigin, defaultSocialImage) : undefined;
@@ -79,6 +80,19 @@ export default function RootLayout({ children }: { children: ReactNode }) {
     <html lang="en" suppressHydrationWarning>
       <head>
         <link rel="sitemap" type="application/xml" href={`${siteOrigin}/sitemap.xml`} />
+        {fontsConfig && (() => {
+          // Collect Google Fonts families that don't use a custom source
+          const families = new Set<string>();
+          for (const def of [fontsConfig.heading, fontsConfig.body]) {
+            if (def && !def.source) {
+              const weight = def.weight ? `:wght@${def.weight}` : ':wght@400;500;600;700';
+              families.add(`${def.family.replace(/ /g, '+')}${weight}`);
+            }
+          }
+          if (families.size === 0) return null;
+          const url = `https://fonts.googleapis.com/css2?${[...families].map(f => `family=${f}`).join('&')}&display=swap`;
+          return <link rel="stylesheet" href={url} />;
+        })()}
       </head>
       <body className="min-h-screen" suppressHydrationWarning>
         <Providers theme={theme}>

package/src/engine/lib/velu.ts

@@ -173,6 +173,18 @@ interface VeluContextualCustomOption {
   href: string;
 }
 
+interface VeluFontDef {
+  family: string;
+  weight?: number;
+  source?: string;
+  format?: 'woff' | 'woff2';
+}
+
+export interface VeluResolvedFonts {
+  heading?: VeluFontDef;
+  body?: VeluFontDef;
+}
+
 interface VeluConfig {
   name?: string;
   description?: string;
@@ -188,6 +200,7 @@ interface VeluConfig {
     library?: string;
   };
   appearance?: 'system' | 'light' | 'dark';
+  fonts?: VeluFontDef | { heading?: VeluFontDef; body?: VeluFontDef };
   languages?: string[];
   openapi?: string | string[] | Record<string, unknown>;
   asyncapi?: string | string[] | Record<string, unknown>;
@@ -691,6 +704,19 @@ export function getAppearance(): 'system' | 'light' | 'dark' {
 
 export type VeluIconLibrary = 'fontawesome' | 'lucide' | 'tabler';
 
+export function getFontsConfig(): VeluResolvedFonts | null {
+  const raw = loadVeluConfig().fonts;
+  if (!raw) return null;
+  // Single font definition (has 'family') → apply to both heading and body
+  if ('family' in raw && typeof raw.family === 'string') {
+    return { heading: raw as VeluFontDef, body: raw as VeluFontDef };
+  }
+  // Separate heading/body
+  const obj = raw as { heading?: VeluFontDef; body?: VeluFontDef };
+  if (!obj.heading && !obj.body) return null;
+  return { heading: obj.heading, body: obj.body };
+}
+
 export function getIconLibrary(): VeluIconLibrary {
   const raw = loadVeluConfig().icons?.library;
   if (raw === 'lucide' || raw === 'tabler' || raw === 'fontawesome') return raw;

package/src/engine/mdx-components.tsx

@@ -152,9 +152,7 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {
       ...props
     }: any) => {
       const hasImage = Boolean(img || image);
-      const hasIcon = Boolean(icon);
-      // Mintlify-like default: icon cards are horizontal unless explicitly disabled.
-      const useHorizontal = typeof horizontal === 'boolean' ? horizontal : (hasIcon && !hasImage);
+      const useHorizontal = horizontal === true;
 
       return (
         <Card

package/src/engine/src/lib/velu.ts

@@ -65,7 +65,6 @@ export interface VeluConfig {
   theme?: string;
   colors?: { primary?: string; light?: string; dark?: string };
   appearance?: 'system' | 'light' | 'dark';
-  styling?: { codeblocks?: { theme?: string | { light: string; dark: string } } };
   navigation: {
     tabs?: VeluTab[];
     anchors?: VeluAnchor[];

package/src/themes.ts

@@ -6,17 +6,23 @@ interface VeluColors {
   dark?: string;
 }
 
-interface VeluStyling {
-  codeblocks?: {
-    theme?: string | { light: string; dark: string };
-  };
+interface VeluFontDef {
+  family: string;
+  weight?: number;
+  source?: string;
+  format?: "woff" | "woff2";
+}
+
+interface VeluFontsConfig {
+  heading?: VeluFontDef;
+  body?: VeluFontDef;
 }
 
 interface ThemeConfig {
   theme?: string;
   colors?: VeluColors;
   appearance?: "system" | "light" | "dark";
-  styling?: VeluStyling;
+  fonts?: VeluFontsConfig;
 }
 
 const FUMADOCS_THEMES = [
@@ -160,6 +166,46 @@ function generateThemeCss(config: ThemeConfig): string {
   }
   lines.push("");
 
+  // Font configuration
+  if (config.fonts) {
+    const { heading, body } = config.fonts;
+    // @font-face declarations for custom sources
+    for (const def of [heading, body].filter(Boolean) as VeluFontDef[]) {
+      if (def.source) {
+        const fmt = def.format || (def.source.endsWith(".woff2") ? "woff2" : "woff");
+        lines.push(`@font-face {`);
+        lines.push(`  font-family: '${def.family}';`);
+        lines.push(`  src: url('${def.source}') format('${fmt}');`);
+        if (def.weight) lines.push(`  font-weight: ${def.weight};`);
+        lines.push(`  font-display: swap;`);
+        lines.push(`}`);
+        lines.push("");
+      }
+    }
+    // CSS variable overrides
+    const vars: string[] = [];
+    if (body) {
+      vars.push(`  --font-fd-sans: '${body.family}', ui-sans-serif, system-ui, sans-serif;`);
+    }
+    if (heading) {
+      vars.push(`  --velu-font-heading: '${heading.family}', ui-sans-serif, system-ui, sans-serif;`);
+    }
+    if (vars.length) {
+      lines.push(":root {");
+      lines.push(...vars);
+      lines.push("}");
+      lines.push("");
+    }
+    // Heading font-family rule
+    if (heading) {
+      lines.push("h1, h2, h3, h4, h5, h6 {");
+      lines.push(`  font-family: var(--velu-font-heading);`);
+      if (heading.weight) lines.push(`  font-weight: ${heading.weight};`);
+      lines.push("}");
+      lines.push("");
+    }
+  }
+
   return lines.join("\n");
 }
 
@@ -169,4 +215,4 @@ function getThemeNames(): string[] {
 
 const THEMES = [...FUMADOCS_THEMES];
 
-export { generateThemeCss, getThemeNames, resolveThemeName, THEMES, ThemeConfig, VeluColors, VeluStyling };
+export { generateThemeCss, getThemeNames, resolveThemeName, THEMES, ThemeConfig, VeluColors };

package/src/validate.ts

@@ -113,6 +113,13 @@ interface VeluVersionNav {
 
 type VeluOpenApiSource = string | string[] | Record<string, unknown>;
 
+interface VeluFontDefinition {
+  family: string;
+  weight?: number;
+  source?: string;
+  format?: "woff" | "woff2";
+}
+
 interface VeluConfig {
   $schema?: string;
   variables?: Record<string, string>;
@@ -123,7 +130,8 @@ interface VeluConfig {
   theme?: string;
   colors?: { primary?: string; light?: string; dark?: string };
   appearance?: "system" | "light" | "dark";
-  styling?: { codeblocks?: { theme?: string | { light: string; dark: string } } };
+
+  fonts?: VeluFontDefinition | { heading?: VeluFontDefinition; body?: VeluFontDefinition };
   openapi?: VeluOpenApiSource;
   asyncapi?: VeluOpenApiSource;
   api?: {