@portosaur/core 0.1.4 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portosaur/core",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "The engine of portosaur that translates YAML configuration into Docusaurus structures.",
   "license": "GPL-3.0-only",
   "author": "soymadip",
@@ -27,9 +27,12 @@
   },
   "types": "./src/index.d.ts",
   "dependencies": {
-    "@portosaur/logger": "^0.1.4",
+    "@portosaur/logger": "^0.2.0",
     "favicons": "^7.2.0",
     "js-yaml": "^4.1.1",
     "sharp": "^0.34.5"
+  },
+  "engines": {
+    "node": ">=24.15.0"
   }
 }

package/src/app.mjs

@@ -1,25 +1,25 @@
 import { readFileSync } from "fs";
-import { resolve } from "path";
+import { fileURLToPath } from "url";
 
 /**
  * Portosaur application metadata and configuration
  */
 export const porto = (() => {
   try {
-    const pkgPath = resolve(import.meta.dirname, "../../../package.json");
+    const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
     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 || {},
+      name: pkg.name,
+      version: pkg.version,
+      description: pkg.description,
+      license: pkg.license,
+      homepage: pkg.homepage,
+      repository: pkg.repository?.url,
+      engines: pkg.engines,
 
       // Derived/computed fields
-      engineName: `${pkg.name || "Portosaur"}`,
+      engineName: pkg.name,
     };
   } catch (error) {
     console.warn(

package/src/generators/docusaurusConfig.mjs

@@ -1,5 +1,6 @@
 import fs from "fs";
 import path from "path";
+import { createRequire } from "module";
 import { getGitDate } from "../utils/system.mjs";
 import { porto } from "../app.mjs";
 import { resolveVars, getNestedValue } from "../utils/config.mjs";
@@ -15,19 +16,10 @@ import {
 /**
  * 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";
+export function buildDocuConfig(rawUserConfig, projectDir, context = {}) {
+  const { portoPaths = {}, gitDate = null, env = process.env } = context;
+
+  const portoVersion = porto.version ?? "0.0.0";
   const lastUpdated = gitDate ?? getGitDate(projectDir);
 
   const staticDir = path.resolve(projectDir, "static");
@@ -65,6 +57,16 @@ export function generateDocusaurusConfig(
 
   // ------- Configuration Setup -------
 
+  // Collect static directories: local site static/, theme assets/, and portosaur dot-dir.
+  const staticDirectories = [
+    "static",
+    assetsDir,
+    path.join(projectDir, ".docusaurus", "portosaur"),
+  ].filter((dir) => dir && fs.existsSync(dir));
+
+  const isDarkMode = get("theme.appearance.dark_mode", true);
+  const disableSwitch = get("theme.appearance.disable_switch", false);
+
   return {
     projectName: siteName,
     title: siteName,
@@ -83,6 +85,104 @@ export function generateDocusaurusConfig(
     onBrokenLinks: get("site.on_broken_links", "throw"),
     i18n: { defaultLocale: "en", locales: ["en"] },
 
+    staticDirectories,
+
+    themeConfig: {
+      colorMode: {
+        defaultMode: isDarkMode ? "dark" : "light",
+        disableSwitch,
+        respectPrefersColorScheme: false,
+      },
+
+      navbar: {
+        title: siteName,
+        logo: {
+          alt: `${siteName} logo`,
+          src: resolveAsset(get("site.favicon", ""), "img/icon.png"),
+        },
+        hideOnScroll: get("theme.navigation.hide_navbar_on_scroll", true),
+        items: [
+          {
+            type: "search",
+            position: "right",
+            className: "navbar-search-bar",
+          },
+          ...(get("home_page.about.enable", true)
+            ? [
+                {
+                  label: "About Me",
+                  to: "/#about",
+                  position: "right",
+                  activeBasePath: "/never-match",
+                },
+              ]
+            : []),
+          ...(get("home_page.project_shelf.enable", true)
+            ? [
+                {
+                  label: "Projects",
+                  to: "/#projects",
+                  position: "right",
+                  activeBasePath: "/never-match",
+                },
+              ]
+            : []),
+          ...(get("home_page.experience.enable", false)
+            ? [
+                {
+                  label: "Experience",
+                  to: "/#experience",
+                  position: "right",
+                  activeBasePath: "/never-match",
+                },
+              ]
+            : []),
+          ...(get("home_page.social.enable", true)
+            ? [
+                {
+                  label: "Contact",
+                  to: "/#contact",
+                  position: "right",
+                  activeBasePath: "/never-match",
+                },
+              ]
+            : []),
+          {
+            type: "dropdown",
+            label: "More",
+            position: "right",
+            className: "_navbar-more-items",
+            items: [
+              { label: "Notes", to: "/notes" },
+              { label: "Blog", to: "/blog" },
+              ...(get("tasks.enable", false)
+                ? [{ label: "Tasks", to: "/tasks" }]
+                : []),
+              ...(!get("theme.appearance.disable_branding", false)
+                ? [
+                    {
+                      label: `Portosaur v${portoVersion}`,
+                      className: "_nav-portosaur-version",
+                      href:
+                        porto?.homepage ||
+                        "https://github.com/soymadip/portosaur",
+                    },
+                  ]
+                : []),
+            ],
+          },
+        ],
+      },
+
+      footer: {
+        style: "dark",
+        copyright: get(
+          "site.footer_text",
+          `© ${new Date().getFullYear()} ${siteName}. Built with Portosaur.`,
+        ),
+      },
+    },
+
     headTags: buildHeadTags([
       { meta: { name: "generator", content: `Portosaur v${porto.version}` } },
       { meta: { name: "theme-color", content: "var(--ifm-background-color)" } },
@@ -132,11 +232,17 @@ export function generateDocusaurusConfig(
         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."),
+        social: get("home_page.hero.social", []),
+        learnMoreButtonTxt: get(
+          "home_page.hero.learn_more_button_txt",
+          "Learn More",
+        ),
       },
 
       aboutSection: {
         enable: get("home_page.about.enable", true),
         heading: get("home_page.about.heading", "About Me"),
+        name: get("site.title", "Your Name"),
         image: resolveAsset(get("home_page.about.image", "")),
         bio: get("home_page.about.bio", []),
         skills: get("home_page.about.skills", []),
@@ -194,20 +300,47 @@ export function generateDocusaurusConfig(
             path: "notes",
             sidebarPath: path.resolve(
               portoPaths.theme ?? context.portoRoot ?? "",
-              "theme/config/sidebar.js",
+              "config/sidebar.jsx",
             ),
           },
           blog: { path: "blog", showReadingTime: false },
           theme: {
             customCss: path.resolve(
               portoPaths.theme ?? context.portoRoot ?? "",
-              "theme/css/custom.css",
+              "css/custom.css",
             ),
           },
         },
       ],
     ],
 
+    // ------- Themes -------
+
+    themes: [
+      [
+        (() => {
+          const require = createRequire(import.meta.url);
+          return require.resolve("@easyops-cn/docusaurus-search-local", {
+            paths: [portoPaths.theme ?? context.portoRoot ?? ""],
+          });
+        })(),
+        {
+          hashed: true,
+          indexDocs: true,
+          indexBlog: true,
+          indexPages: true,
+          docsDir: "notes",
+          docsRouteBasePath: "notes",
+          searchContextByPaths: ["notes", "blog"],
+          highlightSearchTermsOnTargetPage: true,
+          explicitSearchResultPath: true,
+          hideSearchBarWithNoSearchContext: true,
+          searchBarShortcutHint: false,
+          language: ["en"],
+        },
+      ],
+    ],
+
     // ------- Plugins -------
 
     plugins: [
@@ -217,12 +350,25 @@ export function generateDocusaurusConfig(
           debug: !env.NODE_ENV || env.NODE_ENV === "development",
           offlineModeActivationStrategies: [
             "always",
-            "deviceRetroactive",
-            "query",
-            "checkRedirect",
+            "appInstalled",
+            "queryString",
+            "standalone",
           ],
         },
       ],
+
+      // Serve the theme's pages/ directory as page routes.
+      // This registers pages/index.jsx → / and pages/tasks.jsx → /tasks etc.
+      [
+        "@docusaurus/plugin-content-pages",
+        {
+          id: "portosaur-pages",
+          path: path.resolve(
+            portoPaths.theme ?? context.portoRoot ?? "",
+            "pages",
+          ),
+        },
+      ],
     ],
   };
 }

package/src/generators/generateFavicons.mjs

@@ -45,6 +45,36 @@ function processManifest(manifestFile, outputDir, appVersion) {
   }
 }
 
+/**
+ * Converts a raw HTML tag string from the favicons library into a Docusaurus
+ * headTag object: { tagName, attributes }.
+ *
+ * Example input:  '<link rel="icon" href="/favicon/favicon.ico">'
+ * Example output: { tagName: 'link', attributes: { rel: 'icon', href: '/favicon/favicon.ico' } }
+ */
+function parseHtmlTagString(htmlString) {
+  const tagMatch = htmlString.match(/^<(\w+)/);
+  if (!tagMatch) {
+    return null;
+  }
+
+  const tagName = tagMatch[1];
+  const attributes = {};
+  const attrRegex = /([\w-]+)(?:=["']([^"']*)["'])?/g;
+
+  // Skip past the opening tag name to only match attributes
+  attrRegex.lastIndex = tagName.length + 1;
+  let match;
+  while ((match = attrRegex.exec(htmlString)) !== null) {
+    if (match[0] === tagName) {
+      continue;
+    }
+    attributes[match[1]] = match[2] ?? "";
+  }
+
+  return { tagName, attributes };
+}
+
 //  Main Generation Function
 
 export async function generateFavicons(siteDir, options = {}) {
@@ -77,9 +107,16 @@ export async function generateFavicons(siteDir, options = {}) {
   if (fs.existsSync(hashFilePath)) {
     const existingHash = fs.readFileSync(hashFilePath, "utf-8");
     if (existingHash === configHash) {
+      const htmlFilePath = path.join(outputDir, ".favicon.html");
       if (fs.existsSync(path.join(outputDir, "favicon.ico"))) {
         logger.info("Favicons are up to date, skipping generation.");
-        return { success: true, html: [] };
+        try {
+          const cachedHtml = JSON.parse(fs.readFileSync(htmlFilePath, "utf-8"));
+          const headTags = cachedHtml.map(parseHtmlTagString).filter(Boolean);
+          return { success: true, html: headTags };
+        } catch (e) {
+          return { success: true, html: [] };
+        }
       }
     }
   }
@@ -97,7 +134,10 @@ export async function generateFavicons(siteDir, options = {}) {
     const iconsToGenerate = ["note", "blog"];
     for (const icon of iconsToGenerate) {
       try {
-        await extractSvg(icon, imgDir, iconColor);
+        await extractSvg(icon, imgDir, {
+          ...iconColor,
+          assetsDir: options.portoAssetsDir,
+        });
       } catch (e) {}
     }
 
@@ -212,7 +252,10 @@ export async function generateFavicons(siteDir, options = {}) {
     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 || [] };
+    const headTags = (response.html || [])
+      .map(parseHtmlTagString)
+      .filter(Boolean);
+    return { success: true, html: headTags };
   } catch (error) {
     logger.warn(`Favicon generation skipped: ${error.message}`);
     tempFiles.forEach(cleanupFile);
@@ -220,7 +263,8 @@ export async function generateFavicons(siteDir, options = {}) {
     if (fs.existsSync(htmlFilePath)) {
       try {
         const cachedHtml = JSON.parse(fs.readFileSync(htmlFilePath, "utf-8"));
-        return { success: false, html: cachedHtml };
+        const headTags = cachedHtml.map(parseHtmlTagString).filter(Boolean);
+        return { success: false, html: headTags };
       } catch (e) {}
     }
     return { success: false, html: [] };

package/src/index.d.ts

@@ -34,7 +34,6 @@ 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,

package/src/index.mjs

@@ -16,7 +16,7 @@ export * from "./app.mjs";
 
 export { generateFavicons } from "./generators/generateFavicons.mjs";
 export { generateRobotsTxt } from "./generators/generateRobots.mjs";
-export { generateDocusaurusConfig } from "./generators/docusaurusConfig.mjs";
+export { buildDocuConfig } from "./generators/docusaurusConfig.mjs";
 
 export {
   resolveSiteUrl,

package/src/utils/config.mjs

@@ -18,22 +18,26 @@ export function getNestedValue(obj, pathStr, ...fallbacks) {
   }
 
   // Return if value found at requested path
-  if (current !== undefined) return current;
+  if (current !== undefined && current !== null) {
+    return current;
+  }
 
   // ------- Try fallback paths ----------
-  for (const fallback of fallbacks) {
-    if (fallback.includes(".")) {
-      const val = getNestedValue(obj, fallback);
+  if (fallbacks.length === 0) return undefined;
 
+  const defaultVal = fallbacks[fallbacks.length - 1];
+  const altPaths = fallbacks.slice(0, fallbacks.length - 1);
+
+  for (const fallback of altPaths) {
+    if (typeof fallback === "string") {
+      const val = getNestedValue(obj, fallback);
       if (val !== undefined) {
         return val;
       }
-    } else if (obj[fallback] !== undefined) {
-      return obj[fallback];
     }
   }
 
-  return;
+  return defaultVal;
 }
 
 /**

package/src/utils/docusaurus.mjs

@@ -31,16 +31,42 @@ export function resolveBasePath(configValue, env = process.env) {
 }
 
 /**
- * Creates a function to resolve static asset paths
+ * Creates a function to resolve static asset paths.
+ * Handles portoRoot-prefixed absolute paths by extracting the bare relative
+ * subpath after any "assets/" segment, so they resolve correctly from
+ * the registered staticDirectories.
  */
 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)))
+    if (!primaryPath) {
+      return fallbackPath;
+    }
+    if (/^https?:\/\//.test(primaryPath)) {
+      return primaryPath;
+    }
+
+    // Strip known prefix segments that arise from {{portoRoot}}/src/assets/...
+    // or {{portoRoot}}/assets/... template paths so we get a bare relative path
+    // that Docusaurus can serve from its staticDirectories.
+    const match = primaryPath.match(/(?:src\/)?assets\/(.+)$/);
+    const normalizedPath = match ? match[1] : primaryPath;
+
+    if (fs.existsSync(path.resolve(staticDir, normalizedPath))) {
+      return normalizedPath;
+    }
+    if (assetsDir && fs.existsSync(path.resolve(assetsDir, normalizedPath))) {
+      return normalizedPath;
+    }
+
+    // Fallback: try the original path unchanged
+    if (fs.existsSync(path.resolve(staticDir, primaryPath))) {
+      return primaryPath;
+    }
+    if (assetsDir && fs.existsSync(path.resolve(assetsDir, primaryPath))) {
       return primaryPath;
-    return fallbackPath || primaryPath;
+    }
+
+    return fallbackPath || normalizedPath || primaryPath;
   };
 }
 

package/src/utils/iconExtractor.mjs

@@ -1,19 +1,28 @@
 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.
+ * Extracts specific SVGs from a given assets directory and saves them to the project.
+ *
+ * @param {string} iconName   - Icon name without the "icon-" prefix or extension.
+ * @param {string} destDir    - Destination directory to copy the SVG into.
+ * @param {Object} options    - Optional settings.
+ * @param {string} options.assetsDir - Base assets directory containing img/svg/. Required.
+ * @param {string} options.color     - Optional fill color to inject into the SVG.
  */
 export async function extractSvg(iconName, destDir, options = {}) {
+  if (!options.assetsDir) {
+    logger.warn(
+      `extractSvg: assetsDir not provided, skipping icon-${iconName}.svg`,
+    );
+    return false;
+  }
+
   const srcPath = path.resolve(
-    __dirname,
-    `../../assets/img/svg/icon-${iconName}.svg`,
+    options.assetsDir,
+    `img/svg/icon-${iconName}.svg`,
   );
-
   const destPath = path.join(destDir, `icon-${iconName}.svg`);
 
   if (!fs.existsSync(srcPath)) {
@@ -28,6 +37,7 @@ export async function extractSvg(iconName, destDir, options = {}) {
   if (options.color) {
     content = content.replace(/fill="[^"]*"/g, `fill="${options.color}"`);
   }
+
   fs.writeFileSync(destPath, content);
 
   logger.info(`Generated SVG icon: ${destPath}`);