@portosaur/core 0.6.3 → 0.9.1

package/configSchema.json

@@ -0,0 +1,354 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Portosaur Project Configuration",
+  "description": "Schema for config.yml — validated at build time by porto.",
+  "type": "object",
+  "properties": {
+    "site": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "url": {
+          "type": "string",
+          "default": "auto"
+        },
+        "path": {
+          "type": "string",
+          "default": "auto"
+        },
+        "title": {
+          "type": "string"
+        },
+        "favicon": {
+          "type": "string",
+          "default": ""
+        },
+        "tagline": {
+          "type": "string",
+          "default": "Short description about you, your passion, your goals etc."
+        },
+        "on_broken_anchors": {
+          "type": "string",
+          "default": "throw"
+        },
+        "on_broken_links": {
+          "type": "string",
+          "default": "throw"
+        },
+        "head_tags": {
+          "type": "array"
+        },
+        "social_card": {
+          "type": "string",
+          "default": ""
+        },
+        "robots_txt": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enable": {
+              "type": "boolean",
+              "default": true
+            },
+            "rules": {
+              "type": "array"
+            },
+            "custom_lines": {
+              "type": "array"
+            }
+          }
+        },
+        "rss": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enable": {
+              "type": "boolean",
+              "default": true
+            },
+            "copyright": {
+              "type": "string"
+            },
+            "desc": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "custom": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "theme": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "appearance": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "default_mode": {
+              "type": "string",
+              "default": "dark"
+            },
+            "show_theme_switch": {
+              "type": "boolean",
+              "default": true
+            },
+            "disable_project_link": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        },
+        "navigation": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "hide_navbar_on_scroll": {
+              "type": "boolean",
+              "default": true
+            },
+            "collapsable_sidebar": {
+              "type": "boolean",
+              "default": true
+            },
+            "breadcrumbs": {
+              "type": "boolean",
+              "default": true
+            }
+          }
+        },
+        "markdown": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mermaid": {
+              "type": "boolean",
+              "default": true
+            },
+            "render_emoji_shortcodes": {
+              "type": "boolean",
+              "default": true
+            },
+            "on_broken_links": {
+              "type": "string",
+              "default": "throw"
+            },
+            "on_broken_images": {
+              "type": "string",
+              "default": "throw"
+            }
+          }
+        },
+        "footer": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enable": {
+              "type": "boolean",
+              "default": true
+            },
+            "message": {
+              "type": "string"
+            },
+            "disable_project_link": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        }
+      }
+    },
+    "home_page": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "hero": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "title": {
+              "type": "string",
+              "default": "Your Name"
+            },
+            "profile_pic": {
+              "type": "string",
+              "default": ""
+            },
+            "desc": {
+              "type": "string",
+              "default": "Short description about you, your passion, your goals etc."
+            },
+            "intro": {
+              "type": "string",
+              "default": "Hello there, I'm"
+            },
+            "subtitle": {
+              "type": "string",
+              "default": "I am a"
+            },
+            "profession": {
+              "type": "string",
+              "default": "Your Profession"
+            },
+            "social": {
+              "type": "array"
+            },
+            "learn_more_button_txt": {
+              "type": "string",
+              "default": "Learn More"
+            }
+          }
+        },
+        "about": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enable": {
+              "type": "boolean",
+              "default": true
+            },
+            "heading": {
+              "type": "string",
+              "default": "About Me"
+            },
+            "image": {
+              "type": "string",
+              "default": ""
+            },
+            "bio": {
+              "type": "array"
+            },
+            "skills": {
+              "type": "array"
+            },
+            "skills_heading": {
+              "type": "string",
+              "default": "My Skills"
+            },
+            "resume": {
+              "type": "string",
+              "default": ""
+            }
+          }
+        },
+        "project_shelf": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enable": {
+              "type": "boolean",
+              "default": true
+            },
+            "heading": {
+              "type": "string",
+              "default": "My Projects"
+            },
+            "subheading": {
+              "type": "string",
+              "default": "A collection of all my works"
+            },
+            "autoplay": {
+              "type": "boolean",
+              "default": true
+            },
+            "projects": {
+              "type": "array"
+            }
+          }
+        },
+        "experience": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enable": {
+              "type": "boolean",
+              "default": false
+            },
+            "heading": {
+              "type": "string",
+              "default": "Experience"
+            },
+            "subheading": {
+              "type": "string",
+              "default": "My professional journey"
+            },
+            "list": {
+              "type": "array"
+            }
+          }
+        },
+        "social": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enable": {
+              "type": "boolean",
+              "default": true
+            },
+            "heading": {
+              "type": "string",
+              "default": "Get In Touch"
+            },
+            "subheading": {
+              "type": "string",
+              "default": "Feel free to reach out"
+            },
+            "links": {
+              "type": "array"
+            }
+          }
+        }
+      }
+    },
+    "tasks": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enable": {
+          "type": "boolean",
+          "default": false
+        },
+        "title": {
+          "type": "string",
+          "default": "Tasks"
+        },
+        "subtitle": {
+          "type": "string",
+          "default": "My current focus"
+        },
+        "list": {
+          "type": "array"
+        }
+      }
+    },
+    "tools": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "link_shortener": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enable": {
+              "type": "boolean",
+              "default": false
+            },
+            "deploy_path": {
+              "type": "string",
+              "default": "/l"
+            },
+            "short_links": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
+      }
+    }
+  },
+  "required": [],
+  "additionalProperties": false
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portosaur/core",
-  "version": "0.6.3",
+  "version": "0.9.1",
   "description": "The engine of portosaur that translates YAML configuration into Docusaurus structures.",
   "license": "GPL-3.0-only",
   "author": "soymadip",
@@ -10,8 +10,12 @@
     "url": "https://github.com/soymadip/portosaur"
   },
   "files": [
-    "src"
+    "src",
+    "configSchema.json"
   ],
+  "scripts": {
+    "prepack": "bun ../cli/bin/porto.mjs schema"
+  },
   "type": "module",
   "exports": {
     ".": {
@@ -27,7 +31,7 @@
   },
   "types": "./src/index.d.ts",
   "dependencies": {
-    "@portosaur/logger": "^0.6.3",
+    "@portosaur/logger": "^0.9.1",
     "favicons": "^7.2.0",
     "js-yaml": "^4.1.1",
     "rehype-katex": "7",

package/src/generators/docusaurusConfig.mjs

@@ -4,6 +4,7 @@ import { createRequire } from "module";
 import { getGitDate } from "../utils/system.mjs";
 import { porto } from "../app.mjs";
 import { resolveVars, getNestedValue } from "../utils/config.mjs";
+import { getPortoDotDir } from "../utils/fs.mjs";
 import {
   resolveSiteUrl,
   resolveBasePath,
@@ -22,14 +23,17 @@ import rehypeKatex from "rehype-katex";
 export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
   const { portoPaths = {}, gitDate = null, env = process.env } = context;
 
+  const rawGet = (key, ...fallbacks) =>
+    getNestedValue(rawUserConfig, key, ...fallbacks);
+
   const portoVersion = porto.version ?? "0.0.0";
   const lastUpdated = gitDate ?? getGitDate(projectDir);
 
   const staticDir = path.resolve(projectDir, "static");
   const assetsDir = portoPaths.assets ?? "";
 
-  const siteUrl = resolveSiteUrl(rawUserConfig.site?.url ?? "auto", env);
-  const sitePath = resolveBasePath(rawUserConfig.site?.path ?? "auto", env);
+  const siteUrl = resolveSiteUrl(rawGet("site.url", "auto"), env);
+  const sitePath = resolveBasePath(rawGet("site.path", "auto"), env);
 
   const resolveAsset = createStaticAssetResolver(
     projectDir,
@@ -50,39 +54,44 @@ export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
     isProd: env.NODE_ENV === "production",
     isDev: env.NODE_ENV === "development",
     nodeEnv: env.NODE_ENV ?? "development",
-    custom: rawUserConfig.custom ?? {},
+    custom: rawGet("custom", {}),
   });
 
   const get = (key, ...fallbacks) =>
     getNestedValue(userConfig, key, ...fallbacks);
 
-  const siteName = get("site.title", "Your Name");
+  const defaultTheme =
+    get("theme.appearance.default_mode", "dark") === "light" ? "light" : "dark";
 
-  // ------- Configuration Setup -------
+  const titleName = get("home_page.hero.title", "Your Name");
+  const siteName = get("site.title", titleName);
+  const siteFavicon = resolveAsset(
+    get("site.favicon", ""),
+    resolveAsset(get("home_page.hero.profile_pic", ""), "img/icon.png"),
+  );
+
+  const siteTagline = get(
+    "home_page.hero.desc",
+    "site.tagline",
+    "Short description about you, your passion, your goals etc.",
+  );
 
   // Collect static directories: local site static/, theme assets/, and portosaur dot-dir.
   const staticDirectories = [
     "static",
     assetsDir,
-    path.join(projectDir, ".docusaurus", "portosaur"),
+    getPortoDotDir(projectDir),
   ].filter((dir) => dir && fs.existsSync(dir));
 
-  const isDarkMode = get("theme.appearance.dark_mode", true);
-  const disableSwitch = get("theme.appearance.disable_switch", false);
+  // ------- Configuration Setup -------
 
   return {
     projectName: siteName,
     title: siteName,
-    tagline: get(
-      "site.tagline",
-      "Short description about you, your passion, your goals etc.",
-    ),
+    tagline: siteTagline,
     url: siteUrl,
     baseUrl: sitePath,
-    favicon: resolveAsset(
-      get("site.favicon", ""),
-      resolveAsset("favicon/favicon.ico", "img/icon.png"),
-    ),
+    favicon: siteFavicon,
     organizationName: siteName,
     onBrokenAnchors: get("site.on_broken_anchors", "throw"),
     onBrokenLinks: get("site.on_broken_links", "throw"),
@@ -90,10 +99,20 @@ export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
 
     staticDirectories,
 
+    headTags: buildHeadTags([
+      ...(context.extraHeadTags || []),
+      ...get("site.head_tags", []),
+    ]),
+
     themeConfig: {
+      image: resolveAsset(get("site.social_card", "")) || undefined,
+      metadata: [
+        { name: "generator", content: `Portosaur v${porto.version}` },
+        { name: "theme-color", content: "var(--ifm-background-color)" },
+      ],
       colorMode: {
-        defaultMode: isDarkMode ? "dark" : "light",
-        disableSwitch,
+        defaultMode: defaultTheme,
+        disableSwitch: !get("theme.appearance.show_theme_switch", true),
         respectPrefersColorScheme: false,
       },
 
@@ -101,7 +120,7 @@ export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
         title: siteName,
         logo: {
           alt: `${siteName} logo`,
-          src: resolveAsset(get("site.favicon", ""), "img/icon.png"),
+          src: siteFavicon,
         },
         hideOnScroll: get("theme.navigation.hide_navbar_on_scroll", true),
         items: [
@@ -161,14 +180,12 @@ export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
               ...(get("tasks.enable", false)
                 ? [{ label: "Tasks", to: "/tasks" }]
                 : []),
-              ...(!get("theme.appearance.disable_branding", false)
+              ...(!get("theme.appearance.disable_project_link", false)
                 ? [
                     {
                       label: `Portosaur v${portoVersion}`,
                       className: "_nav-portosaur-version",
-                      href:
-                        porto?.homepage ||
-                        "https://github.com/soymadip/portosaur",
+                      href: porto?.homepage ?? "#",
                     },
                   ]
                 : []),
@@ -177,53 +194,45 @@ export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
         ],
       },
 
-      footer: {
-        style: "dark",
-        copyright: get(
-          "site.footer_text",
-          `© ${new Date().getFullYear()} ${siteName}. Built with Portosaur.`,
-        ),
+      docs: {
+        sidebar: {
+          hideable: get("theme.navigation.collapsable_sidebar", true),
+        },
       },
-    },
 
-    headTags: buildHeadTags([
-      { meta: { name: "generator", content: `Portosaur v${porto.version}` } },
-      { meta: { name: "theme-color", content: "var(--ifm-background-color)" } },
-      ...(context.extraHeadTags || []),
-      ...get("site.head_tags", []),
-    ]),
+      tableOfContents: {
+        minHeadingLevel: 2,
+        maxHeadingLevel: 3,
+      },
+
+      markdown: {
+        mermaid: get("theme.markdown.mermaid", true),
+        emoji: get("theme.markdown.render_emoji_shortcodes", true),
+        on_broken_links: get("theme.markdown.on_broken_links", "throw"),
+        on_broken_images: get("theme.markdown.on_broken_images", "throw"),
+      },
+
+      ...(get("theme.footer.enable", true)
+        ? {
+            footer: {
+              copyright: get(
+                "theme.footer.message",
+                `© ${new Date().getFullYear()} ${titleName}.${
+                  !get("theme.footer.disable_project_link", false)
+                    ? ` | Built with <a href="${porto?.homepage ?? "#"}" target="_blank" rel="noopener noreferrer">Portosaur.</a>`
+                    : ""
+                }`,
+              ),
+            },
+          }
+        : {}),
+    },
 
     // ------- Custom Fields -------
 
     customFields: {
       portoVersion,
 
-      theme: {
-        markdown: {
-          mermaid: get("theme.markdown.mermaid", true),
-          on_broken_links: get("theme.markdown.on_broken_links", "throw"),
-          on_broken_images: get("theme.markdown.on_broken_images", "throw"),
-        },
-
-        navigation: {
-          collapsable_sidebar: get(
-            "theme.navigation.collapsable_sidebar",
-            true,
-          ),
-
-          hide_navbar_on_scroll: get(
-            "theme.navigation.hide_navbar_on_scroll",
-            true,
-          ),
-        },
-
-        appearance: {
-          dark_mode: get("theme.appearance.dark_mode", true),
-          disable_switch: get("theme.appearance.disable_switch", false),
-          disable_branding: get("theme.appearance.disable_branding", false),
-        },
-      },
-
       heroSection: {
         profilePic: resolveAsset(
           get("home_page.hero.profile_pic", ""),
@@ -231,7 +240,7 @@ export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
         ),
 
         intro: get("home_page.hero.intro", "Hello there, I'm"),
-        title: get("home_page.hero.title", "site.title", "Your Name"),
+        title: titleName,
         subtitle: get("home_page.hero.subtitle", "I am a"),
         profession: get("home_page.hero.profession", "Your Profession"),
         desc: get("home_page.hero.desc", "Welcome to my portfolio."),
@@ -290,6 +299,22 @@ export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
         subtitle: get("tasks.subtitle", "My current focus"),
         list: get("tasks.list", []),
       },
+
+      toolsConfig: {
+        linkShortener: {
+          enable: get("tools.link_shortener.enable", false),
+          deployPath: get("tools.link_shortener.deploy_path", "/l"),
+          shortLinks: get("tools.link_shortener.short_links", {}),
+        },
+      },
+
+      // site.robots_txt is consumed in build.mjs, but we pass it through here
+      // so the schema generator discovers it without hardcoding.
+      robotsTxt: {
+        enable: rawGet("site.robots_txt.enable", true),
+        rules: rawGet("site.robots_txt.rules", []),
+        customLines: rawGet("site.robots_txt.custom_lines", []),
+      },
     },
 
     // ------- Presets -------
@@ -301,6 +326,7 @@ export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
           docs: {
             routeBasePath: "notes",
             path: "notes",
+            breadcrumbs: get("theme.navigation.breadcrumbs", true),
             sidebarPath: path.resolve(
               portoPaths.theme ?? context.portoRoot ?? "",
               "config/sidebar.jsx",
@@ -313,6 +339,14 @@ export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
             showReadingTime: false,
             remarkPlugins: [remarkMath],
             rehypePlugins: [rehypeKatex],
+            feedOptions: {
+              type: get("site.rss.enable", true) ? "all" : null,
+              copyright: get(
+                "site.rss.copyright",
+                `Copyright © ${new Date().getFullYear()} ${siteName}.`,
+              ),
+              description: get("site.rss.desc", siteTagline),
+            },
           },
           theme: {
             customCss: path.resolve(
@@ -331,9 +365,10 @@ export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
         (() => {
           const require = createRequire(import.meta.url);
           return require.resolve("@easyops-cn/docusaurus-search-local", {
-            paths: [portoPaths.theme ?? context.portoRoot ?? ""],
+            paths: [projectDir, portoPaths.theme ?? context.portoRoot ?? ""],
           });
         })(),
+
         {
           hashed: true,
           indexDocs: true,

package/src/generators/generateFavicons.mjs

@@ -1,5 +1,6 @@
 import fs from "fs";
 import path from "path";
+import { getPortoDotDir } from "../utils/fs.mjs";
 import { favicons } from "favicons";
 import { downloadImage } from "../utils/imageDownloader.mjs";
 import { reshapeImage } from "../utils/imageProcessor.mjs";
@@ -121,7 +122,7 @@ export async function generateFavicons(siteDir, options = {}) {
     }
   }
 
-  const cacheDir = path.join(siteDir, ".docusaurus", "portosaur", "cache");
+  const cacheDir = path.join(getPortoDotDir(siteDir), "cache");
   createDirectoryIfNotExists(cacheDir);
   const reshapedImagePath = path.join(cacheDir, "profile_pic_reshaped.png");
   const tempFiles = [];

package/src/index.d.ts

@@ -61,3 +61,10 @@ export function getNestedValue(
   pathStr: string,
   ...fallbacks: string[]
 ): any;
+
+/**
+ * Validates the raw user config against the generated JSON Schema.
+ * Returns dot-notation paths for any unknown keys found.
+ * Freeform blocks (custom, tools.link_shortener.short_links) are skipped.
+ */
+export function validateUserConfig(rawConfig: Record<string, any>): string[];

package/src/index.mjs

@@ -1,8 +1,9 @@
 import fs from "fs";
 import path from "path";
 import yaml from "js-yaml";
+import { validateUserConfig } from "./utils/validate.mjs";
 
-export { mirrorSync, loadPkg } from "./utils/fs.mjs";
+export { mirrorSync, loadPkg, getPortoDotDir } from "./utils/fs.mjs";
 
 export {
   deepMerge,
@@ -11,6 +12,7 @@ export {
   useEnabled,
   openInBrowser,
 } from "./utils/system.mjs";
+import pkg from "../package.json";
 
 export * from "./app.mjs";
 
@@ -28,11 +30,26 @@ export {
 } from "./utils/docusaurus.mjs";
 
 export { resolveVars, getNestedValue } from "./utils/config.mjs";
+export { validateUserConfig } from "./utils/validate.mjs";
 
 export function loadUserConfig(projectDir) {
   const configPath = path.resolve(projectDir, "config.yml");
+
   if (!fs.existsSync(configPath)) {
     throw new Error(`No config.yml found at ${configPath}`);
   }
-  return yaml.load(fs.readFileSync(configPath, "utf8"));
+
+  const rawConfig = yaml.load(fs.readFileSync(configPath, "utf8"));
+
+  // Validate for unknown keys and error early with a clear message.
+  const violations = validateUserConfig(rawConfig);
+
+  if (violations.length > 0) {
+    const list = violations.map((v) => `  - ${v}`).join("\n");
+    throw new Error(
+      `Unknown key(s) in config:\n${list}\n\nCheck the config reference: ${pkg.homepage}/guide/config`,
+    );
+  }
+
+  return rawConfig;
 }

package/src/utils/fs.mjs

@@ -2,6 +2,15 @@ import fs from "fs";
 import path from "path";
 import { text } from "../app.mjs";
 
+/**
+ * Gets the standardized path to the hidden Portosaur data directory.
+ * @param {string} siteDir - The project root directory.
+ * @returns {string} The resolved path.
+ */
+export function getPortoDotDir(siteDir) {
+  return path.join(siteDir, ".docusaurus", ".portosaur");
+}
+
 /**
  * Loads a package.json file from a directory.
  * @param {string} dir - The directory to look in.

package/src/utils/validate.mjs

@@ -0,0 +1,103 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+// ------- Schema Loading -------
+
+let _cachedSchema = null;
+
+/**
+ * Loads and caches the generated configSchema.json from the package root.
+ * The schema is committed to the repo and shipped with @portosaur/core.
+ *
+ * @returns {object} The parsed JSON Schema object.
+ */
+function loadSchema() {
+  if (_cachedSchema) {
+    return _cachedSchema;
+  }
+
+  const schemaPath = path.resolve(
+    fileURLToPath(new URL("../..", import.meta.url)),
+    "configSchema.json",
+  );
+
+  if (!fs.existsSync(schemaPath)) {
+    throw new Error(
+      `Config schema not found at ${schemaPath}. Run \`porto schema\` to regenerate it.`,
+    );
+  }
+
+  _cachedSchema = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
+  return _cachedSchema;
+}
+
+// ------- Validation Walker -------
+
+/**
+ * Recursively walks the user's raw config and collects dot-path strings for
+ * any key not present in the provided JSON Schema node.
+ *
+ * @param {object} configNode - Current slice of the user's raw config.
+ * @param {object} schemaNode - Corresponding JSON Schema node.
+ * @param {string} prefix - Dot-notation prefix accumulated so far.
+ * @param {string[]} violations - Accumulated list of unknown key paths.
+ */
+function walk(configNode, schemaNode, prefix, violations) {
+  if (
+    !configNode ||
+    typeof configNode !== "object" ||
+    Array.isArray(configNode)
+  ) {
+    return;
+  }
+
+  const schemaProperties = schemaNode?.properties ?? {};
+  const allowsAdditional = schemaNode?.additionalProperties !== false;
+
+  // Skip validation for freeform blocks (custom, short_links, etc.)
+  if (allowsAdditional) {
+    return;
+  }
+
+  for (const key of Object.keys(configNode)) {
+    const dotPath = prefix ? `${prefix}.${key}` : key;
+
+    if (!(key in schemaProperties)) {
+      violations.push(dotPath);
+      continue;
+    }
+
+    const childSchema = schemaProperties[key];
+
+    // Recurse into object nodes (skip arrays — no item schema)
+    if (childSchema?.type === "object") {
+      walk(configNode[key], childSchema, dotPath, violations);
+    }
+  }
+}
+
+// ------- Public API -------
+
+/**
+ * Validates the raw user config object against the generated JSON Schema.
+ * Returns a list of dot-notation paths for any unknown keys found.
+ *
+ * Unknown keys inside freeform blocks (custom, tools.link_shortener.short_links)
+ * are intentionally ignored — those blocks allow arbitrary content.
+ *
+ * @param {object} rawConfig - The parsed config.yml object.
+ * @returns {string[]} Array of unknown key paths, empty if config is valid.
+ */
+export function validateUserConfig(rawConfig) {
+  if (!rawConfig || typeof rawConfig !== "object") {
+    return [];
+  }
+
+  const schema = loadSchema();
+  const violations = [];
+
+  walk(rawConfig, schema, "", violations);
+
+  return violations;
+}