@portosaur/core 0.8.0 → 0.9.2

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."
+        },
+        "head_tags": {
+          "type": "array"
+        },
+        "on_broken_anchors": {
+          "type": "string",
+          "default": "throw"
+        },
+        "on_broken_links": {
+          "type": "string",
+          "default": "throw"
+        },
+        "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.8.0",
+  "version": "0.9.2",
   "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.8.0",
+    "@portosaur/logger": "^0.9.2",
     "favicons": "^7.2.0",
     "js-yaml": "^4.1.1",
     "rehype-katex": "7",

package/src/generators/docusaurusConfig.mjs

@@ -23,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,
@@ -51,7 +54,7 @@ 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) =>
@@ -80,6 +83,18 @@ export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
     getPortoDotDir(projectDir),
   ].filter((dir) => dir && fs.existsSync(dir));
 
+  // Process all head tags (from plugins and user config)
+  const allHeadTags = buildHeadTags([
+    ...(context.extraHeadTags || []),
+    ...get("site.head_tags", []),
+  ]);
+
+  // Separate regular head tags from meta tags
+  const regularHeadTags = allHeadTags.filter((t) => t.tagName !== "meta");
+  const customMetaTags = allHeadTags
+    .filter((t) => t.tagName === "meta")
+    .map((t) => t.attributes);
+
   // ------- Configuration Setup -------
 
   return {
@@ -96,16 +111,14 @@ export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
 
     staticDirectories,
 
-    headTags: buildHeadTags([
-      ...(context.extraHeadTags || []),
-      ...get("site.head_tags", []),
-    ]),
+    headTags: regularHeadTags,
 
     themeConfig: {
       image: resolveAsset(get("site.social_card", "")) || undefined,
       metadata: [
         { name: "generator", content: `Portosaur v${porto.version}` },
         { name: "theme-color", content: "var(--ifm-background-color)" },
+        ...customMetaTags,
       ],
       colorMode: {
         defaultMode: defaultTheme,
@@ -296,6 +309,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 -------

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,6 +1,7 @@
 import fs from "fs";
 import path from "path";
 import yaml from "js-yaml";
+import { validateUserConfig } from "./utils/validate.mjs";
 
 export { mirrorSync, loadPkg, getPortoDotDir } from "./utils/fs.mjs";
 
@@ -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/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;
+}