portosaurus 2.1.5 → 2.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portosaurus",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "private": false,
   "homepage": "https://github.com/soymadip/portosaurus",
   "repository": {
@@ -15,9 +15,11 @@
     "src/assets/",
     "src/cli/",
     "src/core/",
+    "src/plugins/",
+    "src/template/",
+    "src/template/.gitignore",
     "src/theme/",
-    "src/utils/",
-    "src/template/"
+    "src/utils/"
   ],
   "scripts": {
     "test": "bun test",

package/src/cli/README.md

@@ -0,0 +1,8 @@
+# Portosaurus CLI Commands
+
+This directory contains the entry points for the `porto` CLI. Each command is implemented as an asynchronous function that handles project lifecycle tasks.
+
+- **`init.mjs`**: Handles new project creation, template mirroring, and initial setup.
+- **`dev.mjs`**: Wraps the Docusaurus development server, providing automatic config shimming and asset generation.
+- **`build.mjs`**: Orchestrates production builds, ensuring the site is ready for deployment.
+- **`serve.mjs`**: Provides a way to preview the production build locally.

package/src/cli/build.mjs

@@ -7,7 +7,7 @@ import {
   writePortoConfigShim,
   runDocusaurus,
   PortoRoot,
-} from "../utils/helpers.mjs";
+} from "../utils/cliHelpers.mjs";
 
 export async function buildCommand(siteDir, extraArgs) {
   const UserRoot = siteDir

package/src/cli/dev.mjs

@@ -7,7 +7,7 @@ import {
   writePortoConfigShim,
   runDocusaurus,
   PortoRoot,
-} from "../utils/helpers.mjs";
+} from "../utils/cliHelpers.mjs";
 
 export async function devCommand(siteDir, extraArgs) {
   const UserRoot = siteDir

package/src/cli/init.mjs

@@ -2,7 +2,7 @@ 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/helpers.mjs";
+import { PortoRoot, mirrorSync } from "../utils/cliHelpers.mjs";
 
 export async function initCommand(projectName, options) {
   const projectDir = path.resolve(process.cwd(), projectName);

package/src/cli/serve.mjs

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

package/src/core/README.md

@@ -0,0 +1,5 @@
+# Portosaurus Core Engine
+
+This directory contains the central configuration engine that transforms user-provided settings into a valid Docusaurus configuration.
+
+- **`buildDocuConfig.mjs`**: The main orchestration file. It deep-merges user configs with template defaults, resolves variable placeholders (`{{...}}`), and registers internal plugins and themes.

package/src/core/buildDocuConfig.mjs

@@ -4,249 +4,19 @@ import { fileURLToPath } from "url";
 import { createRequire } from "module";
 import { logger } from "../utils/logger.mjs";
 
+import {
+  deepMerge,
+  resolveVars,
+  resolveSiteUrl,
+  resolveBasePath,
+  getVersion,
+  useEnabled,
+  createStaticAssetResolver,
+} from "../utils/configUtils.mjs";
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PortoRoot = path.resolve(__dirname, "../../");
 
-// ─── Helpers ────────────────────────────────────────────────
-
-/**
- * Deep merge two objects. Source values override target values.
- * Arrays are replaced, not concatenated.
- */
-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;
-}
-
-/**
- * Resolve {{...}} template references and @alias/ path prefixes
- * inside config string values.
- *
- * Template refs: {{hero_section.profile_pic}} → resolves to the value
- * Path aliases:  @porto/img/icon.png → img/icon.png (prefix stripped)
- *
- * @param {*}      obj        - The value (or tree) to resolve.
- * @param {Object} UserConfig - The full config object for {{...}} lookups.
- * @param {Object} aliases    - Map of prefix → absolute directory path.
- *                              e.g. { "@porto/": "/abs/path/to/assets" }
- * @param {Set}    pathStack  - Internal: tracks {{...}} refs to prevent cycles.
- * @param {number} depth      - Internal: recursion depth guard.
- */
-export function resolveVars(
-  obj,
-  UserConfig,
-  aliases = {},
-  pathStack = new Set(),
-  depth = 0,
-) {
-  if (depth > 10) return obj;
-
-  if (typeof obj === "string") {
-    // If the entire string is exactly one {{tag}}, return the raw value
-    const singleMatch = obj.match(/^\{\{([^}]+)\}\}$/);
-
-    if (singleMatch && !obj.includes("{{", 2)) {
-      const refPath = singleMatch[1];
-      const parts = refPath.split(".");
-      let val = UserConfig;
-
-      for (const p of parts) {
-        if (val == null || typeof val !== "object") break;
-        val = val[p];
-      }
-      if (val !== undefined && val !== obj) {
-        return resolveVars(val, UserConfig, aliases, pathStack, depth + 1);
-      }
-    }
-
-    // Resolve {{...}} template variables
-    let result = obj.replace(
-      /(\\?)\{\{([^}]+)\}\}/g,
-      (match, escape, refPath) => {
-        // If escaped with \, return the literal {{tag}}
-        if (escape === "\\") {
-          return `{{${refPath}}}`;
-        }
-
-        // Check for circularity
-        if (pathStack.has(refPath)) {
-          return match;
-        }
-
-        const parts = refPath.split(".");
-        let val = UserConfig;
-
-        for (const p of parts) {
-          if (val == null || typeof val !== "object") return match;
-          val = val[p];
-        }
-
-        if (val === undefined) {
-          return match;
-        }
-
-        // Recurse in case the resolved value also has template refs
-        const newStack = new Set(pathStack);
-        newStack.add(refPath);
-
-        if (
-          typeof val === "string" &&
-          (val.includes("{{") || val.startsWith("@"))
-        ) {
-          return resolveVars(val, UserConfig, aliases, 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),
-    );
-  }
-
-  if (obj && typeof obj === "object") {
-    const result = {};
-    for (const [key, value] of Object.entries(obj)) {
-      result[key] = resolveVars(value, UserConfig, aliases, pathStack, depth);
-    }
-    return result;
-  }
-  return obj;
-}
-
-/**
- * Resolves the site URL based on config value and environment.
- */
-function resolveSiteUrl(configValue) {
-  if (configValue === "auto") {
-    // GitLab Detection
-    if (process.env.CI_PAGES_URL) {
-      try {
-        const url = new URL(process.env.CI_PAGES_URL);
-        return `${url.protocol}//${url.host}`;
-      } catch (e) {}
-    }
-
-    // GitHub/Gitea/Forgejo Detection
-    if (process.env.GITHUB_ACTIONS === "true") {
-      const serverUrl = process.env.GITHUB_SERVER_URL || "https://github.com";
-
-      // GitHub specific logic
-      if (serverUrl === "https://github.com") {
-        const repoOwner = process.env.GITHUB_REPOSITORY_OWNER;
-        return `https://${repoOwner}.github.io`;
-      }
-
-      // Forgejo/Gitea/Other Actions - Best effort based on instance URL
-      try {
-        const url = new URL(serverUrl);
-        return `${url.protocol}//${url.host}`;
-      } catch (e) {}
-    }
-
-    return "http://localhost";
-  }
-  return configValue;
-}
-
-/**
- * Resolves the base path based on config value and environment.
- */
-function resolveBasePath(configValue) {
-  if (configValue === "auto") {
-    // GitLab Detection
-    if (process.env.CI_PAGES_URL) {
-      try {
-        const url = new URL(process.env.CI_PAGES_URL);
-        return url.pathname.endsWith("/") ? url.pathname : `${url.pathname}/`;
-      } catch (e) {}
-    }
-
-    // GitHub/Gitea/Forgejo Detection
-    if (process.env.GITHUB_ACTIONS === "true") {
-      const repo = process.env.GITHUB_REPOSITORY; // "owner/repo"
-
-      if (!repo) {
-        return "/";
-      }
-
-      const [owner, name] = repo.split("/");
-      const serverUrl = process.env.GITHUB_SERVER_URL || "https://github.com";
-
-      // GitHub User/Org Pages logic
-      if (serverUrl === "https://github.com" && name === `${owner}.github.io`) {
-        return "/";
-      }
-
-      return `/${name}/`;
-    }
-
-    return "/";
-  }
-  return configValue;
-}
-
-/**
- * Read the portosaurus package version.
- */
-function getVersion() {
-  try {
-    const pkgPath = path.resolve(PortoRoot, "package.json");
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-    return pkg.version || "0.0.0";
-  } catch {
-    return "N/A";
-  }
-}
-
-/**
- * Filter items that have enable/value conditional structure.
- */
-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];
-  });
-}
-
 // ─── Main Config Generator ─────────────────────────────────
 
 /**
@@ -302,7 +72,9 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
   // Meta tags
   let PortoMetaTags = [];
   try {
-    const meta = require(path.resolve(PortoRoot, "src/theme/config/metaTags.js"));
+    const meta = require(
+      path.resolve(PortoRoot, "src/theme/config/metaTags.js"),
+    );
     PortoMetaTags = meta.PortoMetaTags ?? meta.metaTags ?? [];
   } catch {
     // OK — no meta tags
@@ -322,39 +94,11 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
    *   - Remote URLs (http/https) pass through as-is.
    *   - Local paths are checked against UserStaticDir, then PortoAssetDir.
    */
-  function resolveStaticAsset(userPath, portoFallback) {
-    // Remote URLs are always valid
-    if (userPath && /^https?:\/\//.test(userPath)) return userPath;
-
-    // Check user's static directory
-    if (userPath && fs.existsSync(path.resolve(UserStaticDir, userPath))) {
-      return userPath;
-    }
-
-    // Check Porto's bundled assets
-    if (userPath && fs.existsSync(path.resolve(PortoAssetDir, userPath))) {
-      return userPath;
-    }
-
-    // Fallback logic with warnings
-    if (portoFallback) {
-      // Only warn if the fallback actually exists and they provided a bad path
-      if (
-        userPath &&
-        userPath !== "favicon/favicon.ico" &&
-        fs.existsSync(path.resolve(PortoAssetDir, portoFallback))
-      ) {
-        logger.warn(`Asset not found: "${userPath}" — using bundled default.`);
-      }
-      return portoFallback;
-    }
-
-    if (userPath && userPath !== "favicon/favicon.ico") {
-      logger.warn(`Asset not found: "${userPath}" — no fallback available.`);
-    }
-
-    return userPath || "";
-  }
+  const resolveStaticAsset = createStaticAssetResolver(
+    UserStaticDir,
+    PortoAssetDir,
+  );
+
 
   // Pages
   const PortoPagesDir = path.resolve(PortoRoot, "src/theme/pages");
@@ -374,7 +118,10 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
     projectName: UserConfig.hero_section.title,
     title: UserConfig.hero_section.title,
     tagline: UserConfig.hero_section.description,
-    favicon: resolveStaticAsset(UserConfig.favicon, "favicon/favicon.ico"),
+    favicon: resolveStaticAsset(
+      UserConfig.favicon,
+      resolveStaticAsset(UserConfig.hero_section.profile_pic, "img/icon.png"),
+    ),
     url: siteUrl,
     baseUrl: basePath,
 
@@ -491,7 +238,7 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
     // so Root.js and MDXComponents are natively transpiled by Docusaurus.
     themes: [
       [
-        path.resolve(PortoRoot, "src/core/plugins/themePlugin.mjs"),
+        path.resolve(PortoRoot, "src/plugins/theme.mjs"),
         {
           themeDir: PortoThemeDir,
         },
@@ -527,7 +274,13 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
         hideOnScroll: UserConfig.hide_navbar_on_scroll,
         logo: {
           alt: "Site Logo",
-          src: resolveStaticAsset(UserConfig.favicon, "favicon/favicon.ico"),
+          src: resolveStaticAsset(
+            UserConfig.favicon,
+            resolveStaticAsset(
+              UserConfig.hero_section.profile_pic,
+              "img/icon.png",
+            ),
+          ),
         },
         items: useEnabled([
           {
@@ -636,8 +389,8 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
           },
         };
       },
-      path.resolve(PortoRoot, "src/utils/build/generateFavicon.mjs"),
-      path.resolve(PortoRoot, "src/utils/build/generateRobotsTxt.mjs"),
+      path.resolve(PortoRoot, "src/plugins/favicon.mjs"),
+      path.resolve(PortoRoot, "src/plugins/robots.mjs"),
       [
         require.resolve("@easyops-cn/docusaurus-search-local", {
           paths: [UserRoot, PortoRoot],

package/src/plugins/README.md

@@ -0,0 +1,8 @@
+# Docusaurus Plugins
+
+This directory contains internal Docusaurus plugins that extend the site's functionality during build and development.
+
+- **`theme.mjs`**: Maps the internal `src/theme` directory so that Docusaurus can pick up Portosaurus components natively.
+- **`favicon.mjs`**: Automates the generation of a complete favicon suite from the user's profile picture.
+- **`robots.mjs`**: Generates a `robots.txt` file based on the configured site URL.
+- **`lib/`**: Contains shared internal utilities used by these plugins (image processing, CSS extraction, etc.).

package/src/{utils/build/generateFavicon.mjs → plugins/favicon.mjs}

@@ -2,11 +2,11 @@ import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 import { favicons } from "favicons";
-import { downloadImage } from "./imageDownloader.mjs";
-import { reshapeImage } from "./imageProcessor.mjs";
-import { getCssVar } from "./cssUtils.mjs";
-import { extractSvg } from "./iconExtractor.mjs";
-import { logger } from "../logger.mjs";
+import { downloadImage } from "./lib/imageDownloader.mjs";
+import { reshapeImage } from "./lib/imageProcessor.mjs";
+import { getCssVar } from "./lib/cssUtils.mjs";
+import { extractSvg } from "./lib/iconExtractor.mjs";
+import { logger } from "../utils/logger.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -142,14 +142,47 @@ export async function generateFavicons(context, options = {}) {
       },
     };
 
-    // 1. Download image with proxy support + caching
-    const downloadedRes = await downloadImage(
-      profilePicUrl,
-      cacheDir,
-      "profile_pic_src.png",
-      { proxies, cacheDir: path.join(cacheDir, "downloads") },
-    );
-    tempFiles.push(downloadedRes);
+    // 1. Resolve image source (Remote URL vs Local Path)
+    let downloadedRes;
+    const isRemote = /^https?:\/\//.test(profilePicUrl);
+
+    if (isRemote) {
+      // Download remote image with proxy support + caching
+      downloadedRes = await downloadImage(
+        profilePicUrl,
+        cacheDir,
+        "profile_pic_src.png",
+        { proxies, cacheDir: path.join(cacheDir, "downloads") },
+      );
+      tempFiles.push(downloadedRes);
+    } else {
+      // Handle local path
+      let localPath = null;
+      // Static directories are provided in siteConfig or we check common ones
+      const staticDirs = siteConfig.staticDirectories || ["static"];
+
+      for (const sDir of staticDirs) {
+        const fullPath = path.resolve(context.siteDir, sDir, profilePicUrl);
+        if (fs.existsSync(fullPath)) {
+          localPath = fullPath;
+          break;
+        }
+      }
+
+      if (!localPath) {
+        // Fallback: check Porto asset dir if not found in user static
+        const portoAssetDir = path.resolve(__dirname, "../../assets");
+        const portoPath = path.resolve(portoAssetDir, profilePicUrl);
+        if (fs.existsSync(portoPath)) {
+          localPath = portoPath;
+        }
+      }
+
+      if (!localPath) {
+        throw new Error(`Local profile picture not found: ${profilePicUrl}`);
+      }
+      downloadedRes = localPath;
+    }
 
     // 2. Reshape if needed
     let finalImagePath = downloadedRes;
@@ -159,7 +192,10 @@ export async function generateFavicons(context, options = {}) {
         reshapedImagePath,
         shape,
       );
-      tempFiles.push(finalImagePath);
+      // Only cleanup if it's a generated temp file, not the original local source
+      if (finalImagePath !== downloadedRes) {
+        tempFiles.push(finalImagePath);
+      }
     }
 
     createDirectoryIfNotExists(outputDir);

package/src/{utils/build → plugins/lib}/cssUtils.mjs

@@ -11,7 +11,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
  */
 export function getCssVar(name) {
   try {
-    const cssPath = path.resolve(__dirname, "../../css/custom.css");
+    const cssPath = path.resolve(__dirname, "../../theme/css/custom.css");
     const cssContent = fs.readFileSync(cssPath, "utf8");
 
     if (name === "--ifm-color-primary") {

package/src/{utils/build → plugins/lib}/iconExtractor.mjs

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
-import { logger } from "../logger.mjs";
+import { logger } from "../../utils/logger.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 

package/src/{utils/build → plugins/lib}/imageDownloader.mjs

@@ -3,7 +3,7 @@ import path from "path";
 import https from "https";
 import http from "http";
 import crypto from "crypto";
-import { logger } from "../logger.mjs";
+import { logger } from "../../utils/logger.mjs";
 
 /**
  * Generates a short hash from a URL for use as a cache key.

package/src/{utils/build → plugins/lib}/imageProcessor.mjs

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 import sharp from "sharp";
-import { logger } from "../logger.mjs";
+import { logger } from "../../utils/logger.mjs";
 
 /**
  * Reshapes an image into a circle or square with rounded corners.

package/src/{utils/build/generateRobotsTxt.mjs → plugins/robots.mjs}

@@ -1,6 +1,6 @@
 import fs from "fs";
 import path from "path";
-import { logger } from "../logger.mjs";
+import { logger } from "../utils/logger.mjs";
 
 /**
  * Generates a robots.txt file in the site's static directory.

package/src/template/.docusaurus/docusaurus-plugin-content-blog/default/blog-post-list-prop-default.json

@@ -0,0 +1,11 @@
+{
+  "title": "Recent posts",
+  "items": [
+    {
+      "title": "Welcome to the Blog",
+      "permalink": "/blog/welcome",
+      "unlisted": false,
+      "date": "2017-03-31T22:00:00.000Z"
+    }
+  ]
+}

package/src/template/.docusaurus/docusaurus-plugin-content-blog/default/p/blog-archive-f05.json

@@ -0,0 +1 @@
+{"archive":{"blogPosts":[{"id":"/welcome","metadata":{"permalink":"/blog/welcome","source":"@site/blog/welcome.md","title":"Welcome to the Blog","description":"Your first blog post! Edit or delete this file to get started.","date":"2017-03-31T22:00:00.000Z","tags":[{"inline":true,"label":"welcome","permalink":"/blog/tags/welcome"}],"hasTruncateMarker":true,"authors":[{"name":"Your Name","title":"Author","url":"https://github.com/yourprofile","key":"you","page":null}],"frontMatter":{"title":"Welcome to the Blog","authors":["you"],"tags":["welcome"]},"unlisted":false},"content":"Your first blog post! Edit or delete this file to get started.\n\n<!-- truncate -->\n\nThis is a blog powered by [Portosaurus](https://github.com/soymadip/portosaurus)."}]}}

package/src/template/.docusaurus/docusaurus-plugin-content-blog/default/p/blog-authors-790.json

@@ -0,0 +1 @@
+{"authors":[{"name":"Your Name","title":"Author","url":"https://github.com/yourprofile","key":"you","page":null,"count":1}]}

package/src/template/.docusaurus/docusaurus-plugin-content-blog/default/p/blog-bd9.json

@@ -0,0 +1 @@
+{"metadata":{"permalink":"/blog","page":1,"postsPerPage":10,"totalPages":1,"totalCount":1,"blogDescription":"Blog","blogTitle":"Blog"}}

package/src/template/.docusaurus/docusaurus-plugin-content-blog/default/site-blog-ss-md-18f.json

@@ -0,0 +1,16 @@
+{
+  "permalink": "/blog/ss",
+  "source": "@site/blog/ss.md",
+  "title": "ss",
+  "description": "",
+  "date": "2017-03-31T22:00:00.000Z",
+  "tags": [],
+  "hasTruncateMarker": false,
+  "authors": [],
+  "frontMatter": {},
+  "unlisted": false,
+  "nextItem": {
+    "title": "Welcome to the Blog",
+    "permalink": "/blog/welcome"
+  }
+}

package/src/template/.docusaurus/docusaurus-plugin-content-blog/default/site-blog-welcome-md-a95.json

@@ -0,0 +1,34 @@
+{
+  "permalink": "/blog/welcome",
+  "source": "@site/blog/welcome.md",
+  "title": "Welcome to the Blog",
+  "description": "Your first blog post! Edit or delete this file to get started.",
+  "date": "2017-03-31T22:00:00.000Z",
+  "tags": [
+    {
+      "inline": true,
+      "label": "welcome",
+      "permalink": "/blog/tags/welcome"
+    }
+  ],
+  "hasTruncateMarker": true,
+  "authors": [
+    {
+      "name": "Your Name",
+      "title": "Author",
+      "url": "https://github.com/yourprofile",
+      "key": "you",
+      "page": null
+    }
+  ],
+  "frontMatter": {
+    "title": "Welcome to the Blog",
+    "authors": [
+      "you"
+    ],
+    "tags": [
+      "welcome"
+    ]
+  },
+  "unlisted": false
+}

package/src/template/.docusaurus/docusaurus-plugin-content-docs/default/p/notes-106.json

@@ -0,0 +1 @@
+{"version":{"pluginId":"default","version":"current","label":"Next","banner":null,"badge":false,"noIndex":false,"className":"docs-version-current","isLast":true,"docsSidebars":{},"docs":{"index":{"id":"index","title":"Notes","description":""},"welcome":{"id":"welcome","title":"Welcome","description":"Welcome to your notes! Add markdown or MDX files in this notes/ directory."}}}}