portosaurus 2.1.12 → 3.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portosaurus",
-  "version": "2.1.12",
+  "version": "3.0.2",
   "private": false,
   "homepage": "https://github.com/soymadip/portosaurus",
   "repository": {

package/src/cli/build.mjs

@@ -6,8 +6,8 @@ import {
   ensureContentDirs,
   writePortoConfigShim,
   runDocusaurus,
-  PortoRoot,
-} from "../utils/cliHelpers.mjs";
+} from "../utils/cliUtils.mjs";
+import { PortoRoot } from "../core/constants.mjs";
 
 export async function buildCommand(siteDir, extraArgs) {
   const UserRoot = siteDir

package/src/cli/dev.mjs

@@ -6,8 +6,8 @@ import {
   ensureContentDirs,
   writePortoConfigShim,
   runDocusaurus,
-  PortoRoot,
-} from "../utils/cliHelpers.mjs";
+} from "../utils/cliUtils.mjs";
+import { PortoRoot } from "../core/constants.mjs";
 
 export async function devCommand(siteDir, extraArgs) {
   const UserRoot = siteDir

package/src/cli/init.mjs

@@ -2,7 +2,8 @@ import fs from "fs";
 import path from "path";
 import { logger } from "../utils/logger.mjs";
 import { getPackageManager } from "../utils/packageManager.mjs";
-import { PortoRoot, mirrorSync } from "../utils/cliHelpers.mjs";
+import { mirrorSync } from "../utils/cliUtils.mjs";
+import { PortoRoot } from "../core/constants.mjs";
 
 export async function initCommand(projectName, options) {
   const UsrProjDir = path.resolve(process.cwd(), projectName);
@@ -116,9 +117,8 @@ export async function initCommand(projectName, options) {
     // Install dependencies
     const pm = getPackageManager(UsrProjDir);
 
-    logger.info(`Installing dependencies with ${pm.name}...`);
-
     if (options.install !== false) {
+      logger.info(`Installing dependencies with ${pm.name}...`);
       logger.info(`Running ${pm.install}...`);
       try {
         const { execSync } = await import("child_process");

package/src/cli/serve.mjs

@@ -5,7 +5,7 @@ import {
   validateProject,
   writePortoConfigShim,
   runDocusaurus,
-} from "../utils/cliHelpers.mjs";
+} from "../utils/cliUtils.mjs";
 
 export async function serveCommand(siteDir) {
   const UserRoot = siteDir

package/src/core/buildDocuConfig.mjs

@@ -1,8 +1,6 @@
 import fs from "fs";
 import path from "path";
-import { fileURLToPath } from "url";
 import { createRequire } from "module";
-import { logger } from "../utils/logger.mjs";
 
 import {
   deepMerge,
@@ -13,9 +11,7 @@ import {
   useEnabled,
   createStaticAssetResolver,
 } from "../utils/configUtils.mjs";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const PortoRoot = path.resolve(__dirname, "../../");
+import { PortoRoot } from "./constants.mjs";
 
 // ─── Main Config Generator ─────────────────────────────────
 
@@ -43,10 +39,20 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
   // This ensures that even if the user deletes nested fields, the structure remains safe.
   const merged = deepMerge(templateDefaults, UserConfigRaw);
 
-  // Resolve {{...}} template variables and @alias/ path prefixes in one pass
+  // Find Docusaurus root for reference
+  let docuRoot = "";
+  try {
+    docuRoot = path.dirname(require.resolve("@docusaurus/core/package.json"));
+  } catch {
+    // If not found (e.g. during some build stages), fallback to node_modules relative to PortoRoot
+    docuRoot = path.resolve(PortoRoot, "node_modules/@docusaurus/core");
+  }
+
+  // Resolve {{...}} template variables path prefixes in one pass
   const UserConfig = resolveVars(merged, merged, {
-    "@porto/": PortoAssetDir,
-    "@site/": UserStaticDir,
+    siteRoot: UserRoot,
+    portoRoot: PortoRoot,
+    docuRoot: docuRoot,
   });
 
   // Compute derived values
@@ -81,16 +87,22 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
   }
 
   // Paths for content — these point directly to the user's project
-  const UserNotesDir = path.resolve(UserRoot, "notes");
-  const UserBlogDir = path.resolve(UserRoot, "blog");
+  const UserNotesDir = "notes";
+  const UserBlogDir = "blog";
 
-  const StaticDirs = [UserStaticDir, PortoAssetDir].filter((d) =>
-    fs.existsSync(d),
+  const PortoFaviconCacheDir = path.resolve(
+    UserRoot,
+    ".docusaurus/portosaurus/favicon",
   );
 
+  const StaticDirs = [
+    UserStaticDir,
+    PortoAssetDir,
+    PortoFaviconCacheDir,
+  ].filter((d) => fs.existsSync(d));
+
   /**
    * Validates a static asset path with fallback.
-   * Aliases (@porto/, @site/) are already resolved globally by resolveAliases().
    *   - Remote URLs (http/https) pass through as-is.
    *   - Local paths are checked against UserStaticDir, then PortoAssetDir.
    */
@@ -99,7 +111,6 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
     PortoAssetDir,
   );
 
-
   // Pages
   const PortoPagesDir = path.resolve(PortoRoot, "src/theme/pages");
 

package/src/core/constants.mjs

@@ -0,0 +1,21 @@
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The absolute path to the Portosaurus package root.
+ * Calculated relative to this file's location in src/utils/
+ */
+export const PortoRoot = path.resolve(__dirname, "../../");
+
+/**
+ * Common paths inside the framework
+ */
+export const Paths = {
+  template: path.join(PortoRoot, "src/template"),
+  assets: path.join(PortoRoot, "src/assets"),
+  theme: path.join(PortoRoot, "src/theme"),
+  core: path.join(PortoRoot, "src/core"),
+  plugins: path.join(PortoRoot, "src/plugins"),
+};

package/src/plugins/favicon.mjs

@@ -63,7 +63,11 @@ export async function generateFavicons(context, options = {}) {
 
   const staticBaseDir = path.resolve(context.siteDir, "static");
   const imgDir = path.join(staticBaseDir, "img", "svg");
-  const outputDir = path.join(staticBaseDir, options.outputPath || "favicon");
+  const outputDir = path.join(
+    context.siteDir,
+    ".docusaurus/portosaurus",
+    options.outputPath || "favicon",
+  );
 
   // --- Smart Caching ---
   const configHash = Buffer.from(

package/src/template/config.js

@@ -8,8 +8,8 @@ exports.usrConf = {
   site_url: "auto",
   site_path: "auto",
   robots_txt: true,
-  favicon: "@porto/img/icon.png",
-  social_card: "@porto/img/social-card.jpeg",
+  favicon: "{{portoRoot}}/src/assets/img/icon.png", // Default Portosaurus Image
+  social_card: "{{portoRoot}}/src/assets/img/social-card.jpeg",
   collapsable_sidebar: true,
   hide_navbar_on_scroll: true,
   disable_theme_switch: false,
@@ -24,7 +24,7 @@ exports.usrConf = {
     profession: "Your Profession",
     description: "Short description about your profession, passion, goals.",
     learn_more_button_txt: "Learn More",
-    profile_pic: "@porto/img/icon.png",
+    profile_pic: "{{portoRoot}}/src/assets/img/icon.png",
   },
 
   about_me: {

package/src/theme/MDXComponents.js

@@ -21,4 +21,3 @@ const components = {
 };
 
 export default components;
-

package/src/utils/{cliHelpers.mjs → cliUtils.mjs}

@@ -1,12 +1,9 @@
 import fs from "fs";
 import path from "path";
-import { fileURLToPath } from "url";
 import { spawn } from "child_process";
 import { logger } from "./logger.mjs";
 import { getDocuCmd } from "./packageManager.mjs";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-export const PortoRoot = path.resolve(__dirname, "../..");
+import { PortoRoot } from "../core/constants.mjs";
 
 /**
  * Write the ephemeral .portosaurus/docusaurus.config.mjs shim.
@@ -72,11 +69,7 @@ export function ensureContentDirs(UserRoot) {
  * Spawn a Docusaurus command and wait for it to complete.
  */
 export function runDocusaurus(command, extraArgs, UserRoot, configPath) {
-  const {
-    command: cmd,
-    args: pmArgs,
-    packageManager,
-  } = getDocuCmd(UserRoot);
+  const { command: cmd, args: pmArgs, packageManager } = getDocuCmd(UserRoot);
 
   logger.info(`Running docusaurus ${command} (via ${packageManager})`);
 

package/src/utils/configUtils.mjs

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { logger } from "./logger.mjs";
-import { PortoRoot } from "./cliHelpers.mjs";
+import { PortoRoot } from "../core/constants.mjs";
 
 /**
  * Deep merge two objects. Source values override target values.
@@ -34,7 +34,7 @@ export function deepMerge(target, source) {
 export function resolveVars(
   obj,
   UserConfig,
-  aliases = {},
+  systemVars = {},
   pathStack = new Set(),
   depth = 0,
 ) {
@@ -46,6 +46,10 @@ export function resolveVars(
 
     if (singleMatch && !obj.includes("{{", 2)) {
       const refPath = singleMatch[1];
+
+      // Check system variables first
+      if (systemVars[refPath] !== undefined) return systemVars[refPath];
+
       const parts = refPath.split(".");
       let val = UserConfig;
 
@@ -54,7 +58,7 @@ export function resolveVars(
         val = val[p];
       }
       if (val !== undefined && val !== obj) {
-        return resolveVars(val, UserConfig, aliases, pathStack, depth + 1);
+        return resolveVars(val, UserConfig, systemVars, pathStack, depth + 1);
       }
     }
 
@@ -63,6 +67,10 @@ export function resolveVars(
       /(\\?)\{\{([^}]+)\}\}/g,
       (match, escape, refPath) => {
         if (escape === "\\") return `{{${refPath}}}`;
+
+        // Support system variables from systemVars
+        if (systemVars[refPath] !== undefined) return systemVars[refPath];
+
         if (pathStack.has(refPath)) return match;
 
         const parts = refPath.split(".");
@@ -77,40 +85,32 @@ export function resolveVars(
         const newStack = new Set(pathStack);
         newStack.add(refPath);
 
-        if (
-          typeof val === "string" &&
-          (val.includes("{{") || val.startsWith("@"))
-        ) {
-          return resolveVars(val, UserConfig, aliases, newStack, depth + 1);
+        if (typeof val === "string" && val.includes("{{")) {
+          return resolveVars(val, UserConfig, systemVars, newStack, depth + 1);
         }
         return val;
       },
     );
 
-    // Resolve @alias/ path prefixes
-    for (const [prefix, dir] of Object.entries(aliases)) {
-      if (result.startsWith(prefix)) {
-        const relative = result.slice(prefix.length);
-        if (dir && !fs.existsSync(path.resolve(dir, relative))) {
-          logger.warn(`Asset not found: "${result}"`);
-        }
-        return relative;
-      }
-    }
-
     return result;
   }
 
   if (Array.isArray(obj)) {
     return obj.map((item) =>
-      resolveVars(item, UserConfig, aliases, pathStack, depth),
+      resolveVars(item, UserConfig, systemVars, pathStack, depth),
     );
   }
 
   if (obj && typeof obj === "object") {
     const result = {};
     for (const [key, value] of Object.entries(obj)) {
-      result[key] = resolveVars(value, UserConfig, aliases, pathStack, depth);
+      result[key] = resolveVars(
+        value,
+        UserConfig,
+        systemVars,
+        pathStack,
+        depth,
+      );
     }
     return result;
   }
@@ -208,8 +208,21 @@ export function useEnabled(items) {
  */
 export function createStaticAssetResolver(UserStaticDir, PortoAssetDir) {
   return function resolveStaticAsset(userPath, portoFallback) {
+    if (!userPath && !portoFallback) return "";
     if (userPath && /^https?:\/\//.test(userPath)) return userPath;
 
+    // Handle absolute paths (e.g. from {{portoRoot}} resolution)
+    if (userPath && path.isAbsolute(userPath)) {
+      if (userPath.startsWith(UserStaticDir)) {
+        return path.relative(UserStaticDir, userPath);
+      }
+      if (userPath.startsWith(PortoAssetDir)) {
+        return path.relative(PortoAssetDir, userPath);
+      }
+      // If absolute but outside our known static dirs, check if it exists
+      if (fs.existsSync(userPath)) return userPath;
+    }
+
     if (userPath && fs.existsSync(path.resolve(UserStaticDir, userPath))) {
       return userPath;
     }

package/src/template/notes/index.mdx

@@ -1,9 +0,0 @@
----
-hide_table_of_contents: true
----
-
-import NoteCards from "portosaurus/src/theme/components/NoteIndex/index.js";
-
-# Notes
-
-<NoteCards />