@portosaur/core 0.1.0

package/README.md

@@ -0,0 +1,18 @@
+# @portosaur/core
+
+The core logic engine of the Portosaur ecosystem.
+
+## 🧩 Features
+
+- **⚙️ Configuration Engine** — Translates YAML input into Docusaurus-compatible structures.
+- **🔄 Variable Resolution** — Handles recursive template resolution and system overrides.
+- **🛠️ Utility Suite** — File system, git metadata, and path resolution helpers.
+
+## API
+
+- `buildDocuConfig` — Generates Docusaurus configuration objects.
+- `resolveVars` — Resolves template tags within configuration structures.
+
+---
+
+Built with 🦖 by [soymadip](https://github.com/soymadip)

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@portosaur/core",
+  "version": "0.1.0",
+  "description": "Portosaur Core: The engine that translates YAML configuration into Docusaurus structures.",
+  "license": "GPL-3.0-only",
+  "author": "soymadip",
+  "homepage": "https://soymadip.github.io/portosaur",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/soymadip/portosaur"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs",
+      "default": "./src/index.mjs"
+    },
+    "./constants": {
+      "types": "./src/constants.d.ts",
+      "import": "./src/constants.mjs",
+      "default": "./src/constants.mjs"
+    }
+  },
+  "types": "./src/index.d.ts",
+  "dependencies": {
+    "@portosaur/logger": "workspace:*",
+    "favicons": "^7.2.0",
+    "js-yaml": "^4.1.1",
+    "sharp": "^0.34.5"
+  }
+}

package/src/app.mjs

@@ -0,0 +1,75 @@
+import { readFileSync } from "fs";
+import { resolve } from "path";
+
+/**
+ * Portosaur application metadata and configuration
+ */
+export const porto = (() => {
+  try {
+    const pkgPath = resolve(import.meta.dirname, "../../../package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+
+    return {
+      name: pkg.name || "Portosaur",
+      version: pkg.version || "0.0.0",
+      description: pkg.description || "",
+      license: pkg.license || "",
+      homepage: pkg.homepage || "",
+      repository: pkg.repository?.url || "",
+      engines: pkg.engines || {},
+
+      // Derived/computed fields
+      engineName: `${pkg.name || "Portosaur"}`,
+    };
+  } catch (error) {
+    console.warn(
+      "Failed to read Portosaur metadata from package.json:",
+      error.message,
+    );
+
+    return {
+      name: "Portosaur",
+      version: "0.0.0",
+      description: "",
+      license: "",
+      homepage: "",
+      repository: "",
+      engines: {},
+      engineName: "Portosaur",
+    };
+  }
+})();
+
+/**
+ * Git operations and formats
+ */
+export const git = {
+  dateFormat: 'git log -1 --format=%cd --date=format:"%B %d, %Y"',
+};
+
+/**
+ * Text file extensions for processing
+ */
+export const text = {
+  extensions: new Set([
+    ".js",
+    ".ts",
+    ".tsx",
+    ".mjs",
+    ".json",
+    ".md",
+    ".mdx",
+    ".yml",
+    ".yaml",
+    ".css",
+    ".html",
+    ".txt",
+  ]),
+};
+
+/**
+ * System limits and constraints
+ */
+export const limits = {
+  maxResolveDepth: 10,
+};

package/src/generators/docusaurusConfig.mjs

@@ -0,0 +1,228 @@
+import fs from "fs";
+import path from "path";
+import { getGitDate } from "../utils/system.mjs";
+import { porto } from "../app.mjs";
+import { resolveVars, getNestedValue } from "../utils/config.mjs";
+import {
+  resolveSiteUrl,
+  resolveBasePath,
+  createStaticAssetResolver,
+  buildHeadTags,
+} from "../utils/docusaurus.mjs";
+
+// ------- Main Configuration Generator -------
+
+/**
+ * Generates a Docusaurus configuration object from raw user config
+ */
+export function generateDocusaurusConfig(
+  rawUserConfig,
+  projectDir,
+  context = {},
+) {
+  const {
+    portoPkg = {},
+    portoPaths = {},
+    gitDate = null,
+    env = process.env,
+  } = context;
+
+  const portoVersion = portoPkg.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 resolveAsset = createStaticAssetResolver(
+    projectDir,
+    staticDir,
+    assetsDir,
+  );
+
+  const userConfig = resolveVars(rawUserConfig, rawUserConfig, {
+    siteRoot: projectDir,
+    portoRoot: context.portoRoot ?? "",
+    compileYear: new Date().getFullYear(),
+    compileDate: new Date().toLocaleDateString(),
+    portoVersion,
+    projectVersion: context.projectVersion ?? "0.0.0",
+    siteUrl,
+    baseUrl: sitePath,
+    lastUpdated,
+    isProd: env.NODE_ENV === "production",
+    isDev: env.NODE_ENV === "development",
+    nodeEnv: env.NODE_ENV ?? "development",
+    custom: rawUserConfig.custom ?? {},
+  });
+
+  const get = (key, ...fallbacks) =>
+    getNestedValue(userConfig, key, ...fallbacks);
+
+  const siteName = get("site.title", "Your Name");
+
+  // ------- Configuration Setup -------
+
+  return {
+    projectName: siteName,
+    title: siteName,
+    tagline: get(
+      "site.tagline",
+      "Short description about you, your passion, your goals etc.",
+    ),
+    url: siteUrl,
+    baseUrl: sitePath,
+    favicon: resolveAsset(
+      get("site.favicon", ""),
+      resolveAsset("favicon/favicon.ico", "img/icon.png"),
+    ),
+    organizationName: siteName,
+    onBrokenAnchors: get("site.on_broken_anchors", "throw"),
+    onBrokenLinks: get("site.on_broken_links", "throw"),
+    i18n: { defaultLocale: "en", locales: ["en"] },
+
+    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", []),
+    ]),
+
+    // ------- 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", ""),
+          "img/icon.png",
+        ),
+
+        intro: get("home_page.hero.intro", "Hello there, I'm"),
+        title: get("home_page.hero.title", "site.title", "Your Name"),
+        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."),
+      },
+
+      aboutSection: {
+        enable: get("home_page.about.enable", true),
+        heading: get("home_page.about.heading", "About Me"),
+        image: resolveAsset(get("home_page.about.image", "")),
+        bio: get("home_page.about.bio", []),
+        skills: get("home_page.about.skills", []),
+        skillsHeading: get("home_page.about.skills_heading", "My Skills"),
+        resume: get("home_page.about.resume", ""),
+      },
+
+      projectShelf: {
+        enable: get("home_page.project_shelf.enable", true),
+        heading: get("home_page.project_shelf.heading", "My Projects"),
+        subheading: get(
+          "home_page.project_shelf.subheading",
+          "A collection of all my works",
+        ),
+        autoplay: get("home_page.project_shelf.autoplay", true),
+        projects: get("home_page.project_shelf.projects", []),
+      },
+
+      experienceSection: {
+        enable: get("home_page.experience.enable", false),
+        heading: get("home_page.experience.heading", "Experience"),
+        subheading: get(
+          "home_page.experience.subheading",
+          "My professional journey",
+        ),
+        list: get("home_page.experience.list", []),
+      },
+
+      socialSection: {
+        enable: get("home_page.social.enable", true),
+        heading: get("home_page.social.heading", "Get In Touch"),
+        subheading: get(
+          "home_page.social.subheading",
+          "Feel free to reach out",
+        ),
+        links: get("home_page.social.links", []),
+      },
+
+      tasks: {
+        enable: get("tasks.enable", false),
+        title: get("tasks.title", "Tasks"),
+        subtitle: get("tasks.subtitle", "My current focus"),
+        list: get("tasks.list", []),
+      },
+    },
+
+    // ------- Presets -------
+
+    presets: [
+      [
+        "@docusaurus/preset-classic",
+        {
+          docs: {
+            routeBasePath: "notes",
+            path: "notes",
+            sidebarPath: path.resolve(
+              portoPaths.theme ?? context.portoRoot ?? "",
+              "theme/config/sidebar.js",
+            ),
+          },
+          blog: { path: "blog", showReadingTime: false },
+          theme: {
+            customCss: path.resolve(
+              portoPaths.theme ?? context.portoRoot ?? "",
+              "theme/css/custom.css",
+            ),
+          },
+        },
+      ],
+    ],
+
+    // ------- Plugins -------
+
+    plugins: [
+      [
+        "@docusaurus/plugin-pwa",
+        {
+          debug: !env.NODE_ENV || env.NODE_ENV === "development",
+          offlineModeActivationStrategies: [
+            "always",
+            "deviceRetroactive",
+            "query",
+            "checkRedirect",
+          ],
+        },
+      ],
+    ],
+  };
+}

package/src/generators/generateFavicons.mjs

@@ -0,0 +1,228 @@
+import fs from "fs";
+import path from "path";
+import { favicons } from "favicons";
+import { downloadImage } from "../utils/imageDownloader.mjs";
+import { reshapeImage } from "../utils/imageProcessor.mjs";
+import { extractSvg } from "../utils/iconExtractor.mjs";
+import { logger } from "@portosaur/logger";
+
+//  Helper Functions
+
+function createDirectoryIfNotExists(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+    return true;
+  }
+  return false;
+}
+
+function cleanupFile(filePath) {
+  if (filePath && fs.existsSync(filePath)) {
+    try {
+      fs.unlinkSync(filePath);
+      return true;
+    } catch (e) {}
+  }
+  return false;
+}
+
+function processManifest(manifestFile, outputDir, appVersion) {
+  try {
+    const manifest = JSON.parse(manifestFile.contents);
+    manifest.version = appVersion;
+    fs.writeFileSync(
+      path.join(outputDir, manifestFile.name),
+      JSON.stringify(manifest, null, 2),
+    );
+    return true;
+  } catch (err) {
+    logger.error(`Failed to process manifest: ${err.message}`);
+    fs.writeFileSync(
+      path.join(outputDir, manifestFile.name),
+      manifestFile.contents,
+    );
+    return false;
+  }
+}
+
+//  Main Generation Function
+
+export async function generateFavicons(siteDir, options = {}) {
+  logger.info("Generating favicons...");
+
+  // Setup options and paths
+  const profilePicUrl = options.imagePath || "img/icon.png";
+  const appVersion = options.appVersion || "1.0";
+  const circular = options.circular !== false;
+  const shape = options.shape || "circle";
+  const proxies = options.proxies || [];
+  const staticBaseDir = path.resolve(siteDir, "static");
+  const imgDir = path.join(staticBaseDir, "img", "svg");
+  const outputDir = path.join(
+    siteDir,
+    ".docusaurus/portosaur",
+    options.outputPath || "favicon",
+  );
+  const configHash = Buffer.from(
+    JSON.stringify({
+      profilePicUrl,
+      shape,
+      circular,
+      outputPath: options.outputPath,
+    }),
+  ).toString("base64");
+  const hashFilePath = path.join(outputDir, ".favicon.hash");
+
+  // Check cache hash and skip if unchanged
+  if (fs.existsSync(hashFilePath)) {
+    const existingHash = fs.readFileSync(hashFilePath, "utf-8");
+    if (existingHash === configHash) {
+      if (fs.existsSync(path.join(outputDir, "favicon.ico"))) {
+        logger.info("Favicons are up to date, skipping generation.");
+        return { success: true, html: [] };
+      }
+    }
+  }
+
+  const cacheDir = path.join(siteDir, ".docusaurus", "portosaur", "cache");
+  createDirectoryIfNotExists(cacheDir);
+  const reshapedImagePath = path.join(cacheDir, "profile_pic_reshaped.png");
+  const tempFiles = [];
+
+  try {
+    // Setup theme colors and configuration
+    const primaryColor = options.themeColor || "#3578e5";
+    const bgColor = options.backgroundColor || "#ffffff";
+    const iconColor = { color: primaryColor };
+    const iconsToGenerate = ["note", "blog"];
+    for (const icon of iconsToGenerate) {
+      try {
+        await extractSvg(icon, imgDir, iconColor);
+      } catch (e) {}
+    }
+
+    // Build favicon configuration
+    const configuration = {
+      path: `/${options.outputPath || "favicon"}/`,
+      appName: options.siteTitle || "Portfolio",
+      appDescription: options.siteTagline || "Portfolio",
+      background: bgColor,
+      theme_color: primaryColor,
+      appleStatusBarStyle: "black-translucent",
+      display: "standalone",
+      scope: "/",
+      start_url: "/",
+      version: appVersion,
+      orientation: "natural",
+      logging: false,
+      loadManifestWithCredentials: true,
+      manifestMaskable: true,
+      icons: {
+        android: {
+          offset: 0,
+          background: false,
+          mask: true,
+          overlayGlow: false,
+          androidPlayStore: true,
+        },
+        favicons: true,
+        appleIcon: true,
+        appleStartup: false,
+        windows: false,
+        yandex: false,
+      },
+    };
+
+    // Resolve image source (remote or local)
+    let downloadedRes;
+    const isRemote = /^https?:\/\//.test(profilePicUrl);
+    if (isRemote) {
+      downloadedRes = await downloadImage(
+        profilePicUrl,
+        cacheDir,
+        "profile_pic_src.png",
+        { proxies, cacheDir: path.join(cacheDir, "downloads") },
+      );
+      tempFiles.push(downloadedRes);
+    } else {
+      let localPath = null;
+      const staticDirs = options.staticDirs || ["static"];
+      for (const sDir of staticDirs) {
+        const fullPath = path.resolve(siteDir, sDir, profilePicUrl);
+        if (fs.existsSync(fullPath)) {
+          localPath = fullPath;
+          break;
+        }
+      }
+      if (!localPath && options.portoAssetsDir) {
+        const portoPath = path.resolve(options.portoAssetsDir, profilePicUrl);
+        if (fs.existsSync(portoPath)) {
+          localPath = portoPath;
+        }
+      }
+      if (!localPath) {
+        throw new Error(`Local profile picture not found: ${profilePicUrl}`);
+      }
+      downloadedRes = localPath;
+    }
+
+    // Process image shape and dimensions
+    let finalImagePath = downloadedRes;
+    if (circular) {
+      finalImagePath = await reshapeImage(
+        downloadedRes,
+        reshapedImagePath,
+        shape,
+      );
+      if (finalImagePath !== downloadedRes) {
+        tempFiles.push(finalImagePath);
+      }
+    }
+
+    // Generate favicon assets using favicons library
+    createDirectoryIfNotExists(outputDir);
+    logger.info(`Generating favicon assets from ${finalImagePath}`);
+    const response = await favicons(finalImagePath, configuration);
+
+    // Process generated images and files
+    let imageCount = 0,
+      fileCount = 0;
+    if (Array.isArray(response.images)) {
+      for (const image of response.images) {
+        fs.writeFileSync(path.join(outputDir, image.name), image.contents);
+        imageCount++;
+      }
+    }
+    if (Array.isArray(response.files)) {
+      for (const file of response.files) {
+        if (file.name.includes("manifest")) {
+          processManifest(file, outputDir, appVersion);
+        } else {
+          fs.writeFileSync(path.join(outputDir, file.name), file.contents);
+        }
+        fileCount++;
+      }
+    }
+
+    // Update cache and cleanup temporary files
+    logger.success(
+      `Generated ${imageCount} favicon images and ${fileCount} support files`,
+    );
+    fs.writeFileSync(hashFilePath, configHash, "utf-8");
+    const htmlFilePath = path.join(outputDir, ".favicon.html");
+    fs.writeFileSync(htmlFilePath, JSON.stringify(response.html), "utf-8");
+    tempFiles.forEach(cleanupFile);
+    return { success: true, html: response.html || [] };
+  } catch (error) {
+    logger.warn(`Favicon generation skipped: ${error.message}`);
+    tempFiles.forEach(cleanupFile);
+    const htmlFilePath = path.join(outputDir, ".favicon.html");
+    if (fs.existsSync(htmlFilePath)) {
+      try {
+        const cachedHtml = JSON.parse(fs.readFileSync(htmlFilePath, "utf-8"));
+        return { success: false, html: cachedHtml };
+      } catch (e) {}
+    }
+    return { success: false, html: [] };
+  }
+}

package/src/generators/generateRobots.mjs

@@ -0,0 +1,42 @@
+import fs from "fs";
+import path from "path";
+import { logger } from "@portosaur/logger";
+export function generateRobotsTxt(siteDir, options = {}) {
+  if (options.enable === false) {
+    return;
+  }
+  logger.info("Generating robots.txt...");
+  const staticDir = path.resolve(siteDir, "static");
+  const robotsPath = path.join(staticDir, "robots.txt");
+  let content = `User-agent: *
+`;
+  if (options.rules) {
+    for (const rule of options.rules) {
+      if (rule.allow) {
+        for (const p of [].concat(rule.allow)) {
+          content += `Allow: ${p}
+`;
+        }
+      }
+      if (rule.disallow) {
+        for (const p of [].concat(rule.disallow)) {
+          content += `Disallow: ${p}
+`;
+        }
+      }
+    }
+  }
+  if (options.customLines) {
+    for (const line of options.customLines) {
+      content += `${line}
+`;
+    }
+  }
+  if (options.siteUrl) {
+    content += `Sitemap: ${options.siteUrl}${options.baseUrl || "/"}sitemap.xml
+`;
+  }
+  fs.mkdirSync(staticDir, { recursive: true });
+  fs.writeFileSync(robotsPath, content);
+  logger.success(`Generated robots.txt at ${robotsPath}`);
+}

package/src/index.d.ts

@@ -0,0 +1,63 @@
+export { colors, logger } from "@portosaur/logger";
+
+export interface PortoPkg {
+  version?: string;
+  [key: string]: any;
+}
+
+export interface PortoPaths {
+  assets?: string;
+  [key: string]: any;
+}
+
+export interface DocusaurusContext {
+  portoPkg?: PortoPkg;
+  portoPaths?: PortoPaths;
+  gitDate?: string;
+  env?: Record<string, string | undefined>;
+}
+
+/**
+ * Loads and parses the user's config.yml file.
+ */
+export function loadUserConfig(projectDir: string): any;
+
+export { mirrorSync, loadPkg } from "./utils/fs.mjs";
+export {
+  deepMerge,
+  getGitDate,
+  hasCommand,
+  useEnabled,
+  openInBrowser,
+} from "./utils/system.mjs";
+export { porto, git, text, limits } from "./app.mjs";
+export { generateFavicons } from "./generators/generateFavicons.mjs";
+export { generateRobotsTxt } from "./generators/generateRobots.mjs";
+export {
+  generateDocusaurusConfig,
+  buildDocuConfig,
+  resolveSiteUrl,
+  resolveBasePath,
+  createStaticAssetResolver,
+  buildHeadTags,
+} from "./generators/docusaurusConfig.mjs";
+
+/**
+ * Resolves template variables like {{site.name}} or {{env.VAR}} within a string or object.
+ */
+export function resolveVars<T>(
+  obj: T,
+  userConfig: any,
+  systemVars?: Record<string, any>,
+  pathStack?: Set<string>,
+  depth?: number,
+): T;
+
+/**
+ * Gets a nested value from an object using a dot-notated string path.
+ */
+export function getNestedValue(
+  obj: any,
+  pathStr: string,
+  ...fallbacks: string[]
+): any;

package/src/index.mjs

@@ -0,0 +1,36 @@
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+
+export { mirrorSync, loadPkg } from "./utils/fs.mjs";
+
+export {
+  deepMerge,
+  getGitDate,
+  hasCommand,
+  useEnabled,
+  openInBrowser,
+} from "./utils/system.mjs";
+
+export * from "./app.mjs";
+
+export { generateFavicons } from "./generators/generateFavicons.mjs";
+export { generateRobotsTxt } from "./generators/generateRobots.mjs";
+export { generateDocusaurusConfig } from "./generators/docusaurusConfig.mjs";
+
+export {
+  resolveSiteUrl,
+  resolveBasePath,
+  createStaticAssetResolver,
+  buildHeadTags,
+} from "./utils/docusaurus.mjs";
+
+export { resolveVars, getNestedValue } from "./utils/config.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"));
+}

package/src/utils/config.mjs

@@ -0,0 +1,138 @@
+import { limits } from "../app.mjs";
+
+/**
+ * Gets a nested value from an object using a dot-notated string path.
+ * Falls back to alternative paths or fallback values if not found.
+ */
+export function getNestedValue(obj, pathStr, ...fallbacks) {
+  // ------- Traverse nested path ----------
+  const parts = pathStr.split(".");
+  let current = obj;
+
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") {
+      current = undefined;
+      break;
+    }
+    current = current[part];
+  }
+
+  // Return if value found at requested path
+  if (current !== undefined) return current;
+
+  // ------- Try fallback paths ----------
+  for (const fallback of fallbacks) {
+    if (fallback.includes(".")) {
+      const val = getNestedValue(obj, fallback);
+
+      if (val !== undefined) {
+        return val;
+      }
+    } else if (obj[fallback] !== undefined) {
+      return obj[fallback];
+    }
+  }
+
+  return;
+}
+
+/**
+ * Resolves template variables like {{key}} recursively within objects, arrays, and strings.
+ * Supports environment variables ({{env.VAR}}) and escaped tags (\\{{...}}).
+ */
+export function resolveVars(
+  obj,
+  userConfig,
+  systemVars = {},
+  pathStack = new Set(),
+  depth = 0,
+) {
+  // Check recursion depth limit
+  if (depth > limits.maxResolveDepth) {
+    return obj;
+  }
+
+  // ------- Handle String Values --------
+  if (typeof obj === "string") {
+    // Try exact match first (single template variable)
+    const exactMatch = obj.match(/^\{\{([^}]+)\}\}$/);
+
+    if (exactMatch) {
+      const refPath = exactMatch[1];
+
+      // Check system variables
+      if (systemVars[refPath] !== undefined) {
+        return systemVars[refPath];
+      }
+
+      // Check environment variables
+      if (refPath.startsWith("env.")) {
+        return process.env[refPath.slice(4)] ?? "";
+      }
+
+      // Resolve from user config
+      const value = getNestedValue(userConfig, refPath);
+      if (value !== undefined && value !== obj) {
+        return resolveVars(value, userConfig, systemVars, pathStack, depth + 1);
+      }
+    }
+
+    // Handle partial template variables with regex replacement
+    return obj.replace(/(\\)?\{\{([^}]+)\}\}/g, (match, escape, refPath) => {
+      // Handle escaped tags
+      if (escape === "\\") {
+        return `{{${refPath}}}`;
+      }
+
+      // Check system variables
+      if (systemVars[refPath] !== undefined) {
+        return String(systemVars[refPath]);
+      }
+
+      // Check environment variables
+      if (refPath.startsWith("env.")) {
+        return process.env[refPath.slice(4)] ?? "";
+      }
+
+      // Prevent circular references
+      if (pathStack.has(refPath)) {
+        return match;
+      }
+
+      // Resolve from user config
+      const value = getNestedValue(userConfig, refPath);
+      if (value === undefined) {
+        return match;
+      }
+
+      // Handle nested resolution
+      const newStack = new Set(pathStack);
+      newStack.add(refPath);
+      if (typeof value === "string" && value.includes("{{")) {
+        return resolveVars(value, userConfig, systemVars, newStack, depth + 1);
+      }
+
+      return String(value);
+    });
+  }
+
+  // ------- Handle Arrays ------------
+  if (Array.isArray(obj)) {
+    return obj.map((item) =>
+      resolveVars(item, userConfig, systemVars, pathStack, depth),
+    );
+  }
+
+  // ------- Handle Objects ------------
+  if (obj && typeof obj === "object") {
+    return Object.fromEntries(
+      Object.entries(obj).map(([key, value]) => [
+        key,
+        resolveVars(value, userConfig, systemVars, pathStack, depth),
+      ]),
+    );
+  }
+
+  // Return primitive values as-is
+  return obj;
+}

package/src/utils/docusaurus.mjs

@@ -0,0 +1,56 @@
+import fs from "fs";
+import path from "path";
+
+/**
+ * Resolves site URL based on config or environment
+ */
+export function resolveSiteUrl(configValue, env = process.env) {
+  if (configValue === "auto") {
+    if (env.CI_PAGES_URL) return new URL(env.CI_PAGES_URL).origin;
+    if (env.GITHUB_ACTIONS === "true")
+      return `https://${env.GITHUB_REPOSITORY_OWNER}.github.io`;
+    return "http://localhost";
+  }
+  return configValue;
+}
+
+/**
+ * Resolves base path based on config or environment
+ */
+export function resolveBasePath(configValue, env = process.env) {
+  if (configValue === "auto") {
+    if (env.CI_PAGES_URL) return new URL(env.CI_PAGES_URL).pathname;
+    if (env.GITHUB_ACTIONS === "true") {
+      const repo = env.GITHUB_REPOSITORY ?? "";
+      const [, name] = repo.split("/");
+      return `/${name}/`;
+    }
+    return "/";
+  }
+  return configValue;
+}
+
+/**
+ * Creates a function to resolve static asset paths
+ */
+export function createStaticAssetResolver(_projectDir, staticDir, assetsDir) {
+  return function (primaryPath, fallbackPath = "") {
+    if (!primaryPath) return fallbackPath;
+    if (/^https?:\/\//.test(primaryPath)) return primaryPath;
+    if (fs.existsSync(path.resolve(staticDir, primaryPath))) return primaryPath;
+    if (assetsDir && fs.existsSync(path.resolve(assetsDir, primaryPath)))
+      return primaryPath;
+    return fallbackPath || primaryPath;
+  };
+}
+
+/**
+ * Transforms tag objects into Docusaurus head tag format
+ */
+export function buildHeadTags(tags = []) {
+  return tags.map((tag) => {
+    if (tag.tagName && tag.attributes) return tag;
+    const [tagName, attributes] = Object.entries(tag)[0];
+    return { tagName, attributes };
+  });
+}

package/src/utils/fs.mjs

@@ -0,0 +1,77 @@
+import fs from "fs";
+import path from "path";
+import { text } from "../app.mjs";
+
+/**
+ * Loads a package.json file from a directory.
+ * @param {string} dir - The directory to look in.
+ * @returns {Object} The parsed package.json or an empty object if not found or invalid.
+ */
+export function loadPkg(dir) {
+  try {
+    const pkgPath = path.resolve(dir, "package.json");
+
+    if (!fs.existsSync(pkgPath)) {
+      return {};
+    }
+
+    return JSON.parse(fs.readFileSync(pkgPath, "utf8")) || {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Recursively copies a directory while performing variable replacements in text files.
+ * @param {string} src - Source directory path.
+ * @param {string} dest - Destination directory path.
+ * @param {Record<string, string>} [replacements={}] - Map of {{key}} to replacement values.
+ * @param {string[]} [ignores=[]] - List of file names or relative paths to skip.
+ * @param {string} [_baseSrc=src] - Internal tracking of the root source path.
+ */
+export function mirrorSync(
+  src,
+  dest,
+  replacements = {},
+  ignores = [],
+  _baseSrc = src,
+) {
+  const ignoreSet = new Set(ignores);
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+
+    // Rename gitignore to .gitignore on copy
+    const targetName = entry.name === "gitignore" ? ".gitignore" : entry.name;
+    const destPath = path.join(dest, targetName);
+    const relativePath = path.relative(_baseSrc, srcPath);
+
+    if (ignoreSet.has(entry.name) || ignoreSet.has(relativePath)) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      mirrorSync(srcPath, destPath, replacements, ignores, _baseSrc);
+    } else {
+      const ext = path.extname(entry.name).toLowerCase();
+
+      if (Object.keys(replacements).length > 0 && text.extensions.has(ext)) {
+        let content = fs.readFileSync(srcPath, "utf8");
+
+        for (const [key, value] of Object.entries(replacements)) {
+          content = content.replace(
+            new RegExp(`\\{\\{${key}\\}\\}`, "g"),
+            value,
+          );
+        }
+
+        fs.writeFileSync(destPath, content);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+}

package/src/utils/iconExtractor.mjs

@@ -0,0 +1,35 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { logger } from "@portosaur/logger";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Extracts specific SVGs from the internal assets and saves them to the project.
+ */
+export async function extractSvg(iconName, destDir, options = {}) {
+  const srcPath = path.resolve(
+    __dirname,
+    `../../assets/img/svg/icon-${iconName}.svg`,
+  );
+
+  const destPath = path.join(destDir, `icon-${iconName}.svg`);
+
+  if (!fs.existsSync(srcPath)) {
+    logger.warn(`Source icon not found: ${srcPath}`);
+    return false;
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+
+  let content = fs.readFileSync(srcPath, "utf8");
+
+  if (options.color) {
+    content = content.replace(/fill="[^"]*"/g, `fill="${options.color}"`);
+  }
+  fs.writeFileSync(destPath, content);
+
+  logger.info(`Generated SVG icon: ${destPath}`);
+  return destPath;
+}

package/src/utils/imageDownloader.mjs

@@ -0,0 +1,154 @@
+import fs from "fs";
+import path from "path";
+import https from "https";
+import http from "http";
+import crypto from "crypto";
+import { logger } from "@portosaur/logger";
+
+//  Cache & Utilities
+function getCacheKey(url) {
+  return crypto.createHash("md5").update(url).digest("hex");
+}
+
+//  Main Download Function
+export async function downloadImage(url, destDir, fileName, options = {}) {
+  const {
+    proxies = [],
+    redirectCount = 0,
+    cacheDir,
+    cacheTTL = 43200000,
+  } = options;
+
+  if (redirectCount > 5) {
+    throw new Error("Too many redirects");
+  }
+
+  // Create destination directory and resolve paths
+  const destPath = path.join(destDir, fileName);
+
+  fs.mkdirSync(destDir, { recursive: true });
+
+  // Check cache first
+  const forceDownload = process.env.PORTO_FORCE_DOWNLOAD === "1";
+
+  if (cacheDir && !forceDownload) {
+    const cacheKey = getCacheKey(url);
+    const cachedPath = path.join(cacheDir, `${cacheKey}-${fileName}`);
+
+    if (fs.existsSync(cachedPath)) {
+      const stats = fs.statSync(cachedPath);
+      const age = Date.now() - stats.mtimeMs;
+
+      if (age < cacheTTL) {
+        logger.info(`Using cached image (${Math.round(age / 60000)}m old)`);
+        fs.copyFileSync(cachedPath, destPath);
+        return destPath;
+      }
+    }
+  }
+
+  // Download the image with HTTP protocol
+  return new Promise((resolve, reject) => {
+    const protocol = url.startsWith("https") ? https : http;
+
+    protocol
+      .get(url, (response) => {
+        // Handle redirects
+        if (
+          response.statusCode &&
+          [301, 302, 303, 307, 308].includes(response.statusCode) &&
+          response.headers.location
+        ) {
+          const redirectUrl = new URL(
+            response.headers.location,
+            url,
+          ).toString();
+
+          logger.info(
+            `Following redirect (${response.statusCode}) to: ${redirectUrl}`,
+          );
+
+          resolve(
+            downloadImage(redirectUrl, destDir, fileName, {
+              ...options,
+              redirectCount: redirectCount + 1,
+            }),
+          );
+
+          return;
+        }
+
+        // Validate HTTP status
+        if (response.statusCode !== 200) {
+          tryProxyFallback(new Error(`HTTP ${response.statusCode}`));
+          return;
+        }
+
+        // Validate content type
+        const contentType = response.headers["content-type"] || "";
+
+        if (!contentType.startsWith("image/") && !url.includes("raw=true")) {
+          logger.warn(`Expected image but got ${contentType} from ${url}`);
+          tryProxyFallback(new Error(`Invalid content type: ${contentType}`));
+          return;
+        }
+
+        // Write file to disk
+        const file = fs.createWriteStream(destPath);
+        response.pipe(file);
+
+        file.on("finish", () => {
+          file.close((err) => {
+            if (err) {
+              reject(err);
+              return;
+            }
+
+            // Cache the downloaded image
+            if (cacheDir) {
+              try {
+                const cacheKey = getCacheKey(url);
+                const cachedPath = path.join(
+                  cacheDir,
+                  `${cacheKey}-${fileName}`,
+                );
+                fs.mkdirSync(cacheDir, { recursive: true });
+                fs.copyFileSync(destPath, cachedPath);
+              } catch {}
+            }
+
+            resolve(destPath);
+          });
+        });
+
+        file.on("error", (err) => {
+          fs.unlink(destPath, () => reject(err));
+        });
+      })
+      .on("error", (err) => {
+        tryProxyFallback(err);
+      });
+
+    // Handle proxy fallback when download fails
+    function tryProxyFallback(originalError) {
+      if (proxies.length > 0) {
+        const nextProxy = proxies[0];
+        const remainingProxies = proxies.slice(1);
+        const proxyUrl = `${nextProxy}${encodeURIComponent(url)}`;
+
+        logger.info(
+          `Download failed or invalid content. Retrying via proxy: ${nextProxy}`,
+        );
+
+        resolve(
+          downloadImage(proxyUrl, destDir, fileName, {
+            ...options,
+            proxies: remainingProxies,
+          }),
+        );
+      } else {
+        reject(originalError || new Error(`Failed to download image: ${url}`));
+      }
+    }
+  });
+}

package/src/utils/imageProcessor.mjs

@@ -0,0 +1,54 @@
+import fs from "fs";
+import path from "path";
+import sharp from "sharp";
+import { logger } from "@portosaur/logger";
+
+//  Image Processing Pipeline
+export async function reshapeImage(inputPath, outputPath, shape = "circle") {
+  try {
+    // Validate input file
+    if (!fs.existsSync(inputPath)) {
+      throw new Error(`Input file not found: ${inputPath}`);
+    }
+
+    // Create output directory
+    const outputDir = path.dirname(outputPath);
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    // Load and analyze image
+    const image = sharp(inputPath);
+    const metadata = await image.metadata();
+
+    if (!metadata.width || !metadata.height) {
+      throw new Error("Could not extract image metadata (width/height)");
+    }
+
+    // Extract and crop to square
+    const size = Math.min(metadata.width, metadata.height);
+
+    let pipeline = image.extract({
+      left: Math.floor((metadata.width - size) / 2),
+      top: Math.floor((metadata.height - size) / 2),
+      width: size,
+      height: size,
+    });
+
+    if (shape === "circle") {
+      const radius = size / 2;
+      const circleSvg = Buffer.from(
+        `<svg><circle cx="${radius}" cy="${radius}" r="${radius}" /></svg>`,
+      );
+
+      pipeline = pipeline.composite([{ input: circleSvg, blend: "dest-in" }]);
+    }
+
+    // Write output file
+    await pipeline.png().toFile(outputPath);
+    return outputPath;
+  } catch (err) {
+    logger.error(`Image processing failed: ${err.message}`);
+    throw err;
+  }
+}

package/src/utils/system.mjs

@@ -0,0 +1,119 @@
+import { execSync, spawn } from "child_process";
+import { git } from "../app.mjs";
+
+/**
+ * Performs a deep merge of two objects.
+ * @param {Object} target - The target object.
+ * @param {Object} source - The source object.
+ * @returns {Object} The merged object.
+ */
+export function deepMerge(target, source) {
+  const result = { ...target };
+
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] &&
+      typeof source[key] === "object" &&
+      !Array.isArray(source[key]) &&
+      target[key] &&
+      typeof target[key] === "object" &&
+      !Array.isArray(target[key])
+    ) {
+      result[key] = deepMerge(target[key], source[key]);
+    } else if (source[key] !== undefined) {
+      result[key] = source[key];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Gets the last modification date of a git project.
+ * @param {string} siteDir - The project directory.
+ * @returns {string} Formatted date string.
+ */
+export function getGitDate(siteDir) {
+  try {
+    const result = execSync(git.dateFormat, {
+      cwd: siteDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+
+    return result.trim();
+  } catch {
+    return new Date().toLocaleDateString("en-US", {
+      year: "numeric",
+      month: "long",
+      day: "numeric",
+    });
+  }
+}
+
+/**
+ * Checks if a command exists in the system PATH.
+ * @param {string} command - The command to check.
+ * @returns {boolean} True if the command is available.
+ */
+export function hasCommand(command) {
+  const cmd =
+    process.platform === "win32" ? `where ${command}` : `which ${command}`;
+
+  try {
+    execSync(cmd, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Filters a list of items, only including those that are enabled.
+ * Supports both raw values and { enable: boolean, value: any } objects.
+ * @param {Array} items - The items to filter.
+ * @returns {Array} The enabled values.
+ */
+export function useEnabled(items) {
+  if (!Array.isArray(items)) {
+    return [];
+  }
+
+  return items.flatMap((item) => {
+    if (
+      item &&
+      typeof item === "object" &&
+      "enable" in item &&
+      "value" in item
+    ) {
+      return item.enable === true ? [item.value] : [];
+    }
+    return [item];
+  });
+}
+
+/**
+ * Opens a URL in the user's default browser.
+ * @param {string} url - The URL to open.
+ * @returns {boolean} True if successful.
+ */
+export function openInBrowser(url) {
+  try {
+    if (process.platform === "darwin") {
+      execSync(`open "${url}"`, { stdio: "ignore" });
+    } else if (process.platform === "win32") {
+      // Windows 'start' treats the first quoted arg as a title, so we pass an empty one first
+      execSync(`start "" "${url}"`, { stdio: "ignore" });
+    } else {
+      // Linux: use spawn + detached to avoid hanging/silent failures
+      const child = spawn("xdg-open", [url], {
+        detached: true,
+        stdio: "ignore",
+      });
+      child.unref();
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}