portosaurus 2.0.3 → 2.1.0

package/src/core/buildDocuConfig.mjs

@@ -0,0 +1,664 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { createRequire } from "module";
+import { logger } from "../utils/logger.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 ─────────────────────────────────
+
+/**
+ * Creates a Docusaurus config from a user's Portosaurus config.
+ *
+ * @param {Object} rawUserConfig - The user's config object (export of config.js).
+ *                                 May be { usrConf: {...} } or just {...}.
+ * @param {string} UserRoot      - Absolute path to the user's project root.
+ * @returns {Object} Complete Docusaurus configuration object.
+ */
+export function buildDocuConfig(rawUserConfig, UserRoot) {
+  // Support both { usrConf: {...} } and direct config objects
+  const UserConfigRaw = rawUserConfig.usrConf ?? rawUserConfig;
+
+  // Load master template defaults for fallback resolution
+  const require = createRequire(import.meta.url);
+  const templateDefaults = require("../template/config.js").usrConf;
+
+  // Static directories — defined early so aliases can reference them
+  const UserStaticDir = path.resolve(UserRoot, "static");
+  const PortoAssetDir = path.resolve(PortoRoot, "src/assets");
+
+  // Hydrate the configuration by deep-merging user config over the template defaults.
+  // 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
+  const UserConfig = resolveVars(merged, merged, {
+    "@porto/": PortoAssetDir,
+    "@site/": UserStaticDir,
+  });
+
+  // Compute derived values
+  const siteUrl = resolveSiteUrl(UserConfig.site_url);
+  const basePath = resolveBasePath(UserConfig.site_path);
+  const version = getVersion();
+
+  const UserProjName = UserConfig.hero_section.title;
+
+  // Resolve internal paths
+
+  // Prism themes
+  let catppuccinMocha, catppuccinLatte;
+  try {
+    const prism = require(path.resolve(PortoRoot, "src/theme/config/prism.js"));
+    catppuccinMocha = prism.catppuccinMocha;
+    catppuccinLatte = prism.catppuccinLatte;
+  } catch {
+    catppuccinMocha = {};
+    catppuccinLatte = {};
+  }
+
+  // Meta tags
+  let PortoMetaTags = [];
+  try {
+    const meta = require(path.resolve(PortoRoot, "src/theme/config/metaTags.js"));
+    PortoMetaTags = meta.PortoMetaTags ?? meta.metaTags ?? [];
+  } catch {
+    // OK — no meta tags
+  }
+
+  // Paths for content — these point directly to the user's project
+  const UserNotesDir = path.resolve(UserRoot, "notes");
+  const UserBlogDir = path.resolve(UserRoot, "blog");
+
+  const StaticDirs = [UserStaticDir, PortoAssetDir].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.
+   */
+  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 || "";
+  }
+
+  // Pages
+  const PortoPagesDir = path.resolve(PortoRoot, "src/theme/pages");
+
+  // Theme overrides
+  const PortoThemeDir = path.resolve(PortoRoot, "src/theme/overrides");
+
+  // Sidebar config
+  const sidebarPath = path.resolve(PortoRoot, "src/theme/config/sidebar.js");
+
+  // CSS
+  const PortoCustomCss = path.resolve(PortoRoot, "src/theme/css/custom.css");
+
+  // ───────────────────────Build the Docusaurus config ───────────────────────
+
+  const config = {
+    projectName: UserConfig.hero_section.title,
+    title: UserConfig.hero_section.title,
+    tagline: UserConfig.hero_section.description,
+    favicon: resolveStaticAsset(UserConfig.favicon, "favicon/favicon.ico"),
+    url: siteUrl,
+    baseUrl: basePath,
+
+    organizationName: UserConfig.hero_section.title,
+    deploymentBranch: "gh-pages",
+    onBrokenAnchors: "ignore",
+    onBrokenLinks: "warn",
+
+    i18n: {
+      defaultLocale: "en",
+      locales: ["en"],
+    },
+
+    headTags: PortoMetaTags,
+
+    customFields: {
+      version,
+
+      heroSection: {
+        profilePic: resolveStaticAsset(
+          UserConfig.hero_section.profile_pic,
+          "img/icon.png",
+        ),
+        intro: UserConfig.hero_section.intro,
+        title: UserConfig.hero_section.title,
+        subtitle: UserConfig.hero_section.subtitle,
+        profession: UserConfig.hero_section.profession,
+        description: UserConfig.hero_section.description,
+        learnMoreButtonTxt: UserConfig.hero_section.learn_more_button_txt,
+      },
+
+      aboutMe: {
+        enable: UserConfig.about_me.enable,
+        image: resolveStaticAsset(
+          UserConfig.about_me.image ?? UserConfig.hero_section.profile_pic,
+          "img/icon.png",
+        ),
+        description: UserConfig.about_me.description,
+        skills: UserConfig.about_me.skills,
+        resumeLink: UserConfig.about_me.resume_link,
+      },
+
+      projects: UserConfig.project_shelf,
+      experience: UserConfig.experience,
+
+      socialLinks: {
+        enable: UserConfig.social_links.enable,
+        links: UserConfig.social_links.links,
+      },
+
+      robotsTxt: {
+        enable: UserConfig.robots_txt,
+        rules: [{ disallow: ["/notes/", "/tasks/"] }],
+        customLines: [],
+      },
+
+      tasksPage: {
+        enable: UserConfig.tasks_page.enable,
+        title: UserConfig.tasks_page.title,
+        description: UserConfig.tasks_page.description,
+        taskList: UserConfig.tasks_page.tasks,
+      },
+
+      corsProxyList: [
+        ...[].concat(UserConfig.cors_proxy || []),
+        "https://cors-proxy.soymadip.workers.dev/?url=",
+        "https://api.allorigins.win/raw?url=",
+      ].filter(Boolean),
+    },
+
+    presets: [
+      [
+        require.resolve("@docusaurus/preset-classic", {
+          paths: [UserRoot, PortoRoot],
+        }),
+        {
+          docs: {
+            routeBasePath: "notes",
+            path: UserNotesDir,
+            sidebarPath,
+            admonitions: {
+              keywords: [
+                "note",
+                "tip",
+                "info",
+                "warning",
+                "danger",
+                "question",
+              ],
+              extendDefaults: true,
+            },
+          },
+          blog: {
+            path: UserBlogDir,
+            feedOptions: UserConfig.rss
+              ? { type: ["rss", "atom"], xslt: true }
+              : undefined,
+            showReadingTime: false,
+            onInlineTags: "warn",
+            onInlineAuthors: "warn",
+            onUntruncatedBlogPosts: "warn",
+          },
+          theme: {
+            customCss: PortoCustomCss,
+          },
+          pages: {
+            path: PortoPagesDir,
+          },
+        },
+      ],
+    ],
+
+    // Register portosaurus's src/theme/overrides as a theme directory
+    // so Root.js and MDXComponents are natively transpiled by Docusaurus.
+    themes: [
+      [
+        path.resolve(PortoRoot, "src/core/plugins/themePlugin.mjs"),
+        {
+          themeDir: PortoThemeDir,
+        },
+      ],
+    ],
+
+    markdown: {
+      mermaid: true,
+      hooks: {
+        onBrokenMarkdownLinks: "warn",
+      },
+    },
+
+    themeConfig: {
+      image: resolveStaticAsset(UserConfig.social_card, "img/social-card.jpeg"),
+      docs: {
+        sidebar: {
+          hideable: UserConfig.collapsable_sidebar,
+        },
+      },
+      imageZoom: {
+        options: {
+          margin: 2,
+          background: "rgba(var(--ifm-background-color-rgb), 0.9)",
+        },
+      },
+      colorMode: {
+        defaultMode: UserConfig.dark_mode ? "dark" : "light",
+        disableSwitch: UserConfig.disable_theme_switch,
+      },
+      navbar: {
+        title: UserProjName,
+        hideOnScroll: UserConfig.hide_navbar_on_scroll,
+        logo: {
+          alt: "Site Logo",
+          src: resolveStaticAsset(UserConfig.favicon, "favicon/favicon.ico"),
+        },
+        items: useEnabled([
+          {
+            type: "search",
+            position: "right",
+            className: "navbar-search-bar",
+          },
+          {
+            enable: UserConfig.about_me.enable,
+            value: {
+              label: "About Me",
+              to: "/#about",
+              position: "right",
+              activeBaseRegex: "^/#about",
+            },
+          },
+          {
+            enable: UserConfig.project_shelf.enable,
+            value: {
+              label: "Projects",
+              to: "/#projects",
+              position: "right",
+              activeBaseRegex: "^/#projects",
+            },
+          },
+          {
+            enable: UserConfig.experience.enable,
+            value: {
+              label: "Experience",
+              to: "/#experience",
+              position: "right",
+              activeBaseRegex: "^/#experience",
+            },
+          },
+          {
+            enable: UserConfig.social_links.enable,
+            value: {
+              label: "Contact",
+              to: "/#contact",
+              position: "right",
+              activeBaseRegex: "^/$contact",
+            },
+          },
+          {
+            type: "dropdown",
+            label: "More",
+            position: "right",
+            className: "_navbar-more-items",
+            items: useEnabled([
+              { label: "Notes", to: "/notes" },
+              { label: "Blog", to: "/blog" },
+              {
+                enable: UserConfig.tasks_page.enable,
+                value: { label: "Tasks", to: "/tasks" },
+              },
+              {
+                enable: !UserConfig.disable_branding,
+                value: {
+                  label: `Portosaurus v${version}`,
+                  className: "_nav-protosaurus-version",
+                  to: "https://github.com/soymadip/portosaurus",
+                },
+              },
+            ]),
+          },
+        ]),
+      },
+      tableOfContents: {
+        minHeadingLevel: 2,
+        maxHeadingLevel: 4,
+      },
+      prism: {
+        theme: catppuccinLatte,
+        darkTheme: catppuccinMocha,
+        additionalLanguages: ["java", "php", "bash"],
+      },
+      footer: {},
+    },
+
+    plugins: [
+      function portosaurusWebpackTranspiler() {
+        return {
+          name: "portosaurus-transpile",
+          configureWebpack(_, isServer, utils) {
+            const jsLoader = utils.getJSLoader({ isServer });
+            jsLoader.options = { ...jsLoader.options, ignore: [] };
+
+            return {
+              mergeStrategy: { "module.rules": "prepend" },
+              resolve: {
+                alias: {
+                  "@porto": path.resolve(PortoRoot, "src"),
+                  portosaurus: PortoRoot,
+                },
+              },
+              module: {
+                rules: [
+                  {
+                    test: /\\.[jt]sx?$/,
+                    include: [path.resolve(PortoRoot, "src")],
+                    use: [jsLoader],
+                  },
+                ],
+              },
+            };
+          },
+        };
+      },
+      path.resolve(PortoRoot, "src/utils/build/generateFavicon.mjs"),
+      path.resolve(PortoRoot, "src/utils/build/generateRobotsTxt.mjs"),
+      [
+        require.resolve("@easyops-cn/docusaurus-search-local", {
+          paths: [UserRoot, PortoRoot],
+        }),
+        {
+          hashed: true,
+          indexDocs: true,
+          docsDir: UserNotesDir,
+          docsRouteBasePath: "notes",
+          searchContextByPaths: ["notes", "blog"],
+          highlightSearchTermsOnTargetPage: true,
+          explicitSearchResultPath: true,
+          hideSearchBarWithNoSearchContext: true,
+          language: ["en"],
+        },
+      ],
+      "plugin-image-zoom",
+    ],
+
+    staticDirectories: StaticDirs,
+  };
+
+  return config;
+}

package/src/core/{themePlugin.mjs → plugins/themePlugin.mjs}

@@ -11,7 +11,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
  * from inside the portosaurus package without the user needing
  * to have them in their own project.
  */
-export default function themePlugin(context, options) {
+export default function themePlugin(_context, options) {
   return {
     name: "portosaurus-theme",