portosaurus 3.0.2 → 4.0.0

package/src/core/buildDocuConfig.mjs

@@ -1,206 +1,296 @@
 import fs from "fs";
 import path from "path";
-import { createRequire } from "module";
-
+import { PortoRoot, Paths, PortoPkg } from "./constants.mjs";
+import {
+  loadPkg,
+  getGitDate,
+  useEnabled,
+  getNestedValue,
+} from "../utils/systemUtils.mjs";
 import {
-  deepMerge,
   resolveVars,
   resolveSiteUrl,
   resolveBasePath,
-  getVersion,
-  useEnabled,
   createStaticAssetResolver,
+  buildHeadTags,
 } from "../utils/configUtils.mjs";
-import { PortoRoot } from "./constants.mjs";
-
-// ─── 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);
-
-  // 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, {
-    siteRoot: UserRoot,
-    portoRoot: PortoRoot,
-    docuRoot: docuRoot,
-  });
 
-  // 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 = "notes";
-  const UserBlogDir = "blog";
+export function buildDocuConfig(UserConfigRaw, UserRoot) {
+  // Get user Project Version
+  const usrProjectVer = loadPkg(UserRoot).version || "0.0.0";
 
-  const PortoFaviconCacheDir = path.resolve(
-    UserRoot,
-    ".docusaurus/portosaurus/favicon",
-  );
+  const portoVersion = PortoPkg.version || "0.0.0";
+  const portoRepo = (PortoPkg.repository?.url || "").replace(/\.git$/, "");
+  const lastUpdated = getGitDate(UserRoot);
 
-  const StaticDirs = [
-    UserStaticDir,
-    PortoAssetDir,
-    PortoFaviconCacheDir,
-  ].filter((d) => fs.existsSync(d));
-
-  /**
-   * Validates a static asset path with fallback.
-   *   - Remote URLs (http/https) pass through as-is.
-   *   - Local paths are checked against UserStaticDir, then PortoAssetDir.
-   */
+  // Static directories
+  const UserStaticDir = path.resolve(UserRoot, "static");
+  const PortoAssetDir = Paths.assets;
+
+  // Resolve static asset path with fallback
   const resolveStaticAsset = createStaticAssetResolver(
+    UserRoot,
     UserStaticDir,
     PortoAssetDir,
   );
 
-  // Pages
-  const PortoPagesDir = path.resolve(PortoRoot, "src/theme/pages");
+  // Resolve SiteURL and BasePath for Docusaurus Root
+  const usrSiteUrl = resolveSiteUrl(UserConfigRaw.site?.url || "auto");
+  const ursSitePath = resolveBasePath(UserConfigRaw.site?.path || "auto");
 
-  // Theme overrides
-  const PortoThemeDir = path.resolve(PortoRoot, "src/theme");
+  // Resolve {{...}} template variables in user config
+  const UserConfig = resolveVars(UserConfigRaw, UserConfigRaw, {
+    siteRoot: UserRoot,
+    portoRoot: PortoRoot,
+    compileYear: new Date().getFullYear(),
+    compileDate: new Date().toLocaleDateString(),
+    portoVersion,
+    projectVersion: usrProjectVer,
+    siteUrl: usrSiteUrl,
+    baseUrl: ursSitePath,
+    lastUpdated,
+    isProd: process.env.NODE_ENV === "production",
+    isDev: process.env.NODE_ENV === "development",
+    nodeEnv: process.env.NODE_ENV || "development",
+    custom: UserConfigRaw.custom || {},
+  });
 
-  // Sidebar config
-  const sidebarPath = path.resolve(PortoRoot, "src/theme/config/sidebar.js");
+  // Helper to get nested values with fallbacks
+  const get = (...args) => getNestedValue(UserConfig, ...args);
 
-  // CSS
-  const PortoCustomCss = path.resolve(PortoRoot, "src/theme/css/custom.css");
+  // ─────────────────────── Build the Docusaurus config ───────────────────────
 
-  // ───────────────────────Build the Docusaurus config ───────────────────────
+  /** The primary title of your website (e.g., your name or brand) */
+  const siteName = get("site.title", "Your Name");
+  const siteUrl = usrSiteUrl;
+  const sitePath = ursSitePath;
+
+  const UserNotesDir = "notes";
+  const UserBlogDir = "blog";
+  const UserTasksDir = "tasks";
 
   const config = {
-    projectName: UserConfig.hero_section.title,
-    title: UserConfig.hero_section.title,
-    tagline: UserConfig.hero_section.description,
+    projectName: siteName,
+    title: siteName,
+
+    /** A short, catchy description shown below the title on the home page */
+    tagline: get(
+      "site.tagline",
+      "Short description about you, your passion, your goals etc.",
+    ),
+
+    url: siteUrl,
+    baseUrl: sitePath,
+
+    // Checks user's given favicon path -> internal favicon/favicon.ico -> img/icon.png
     favicon: resolveStaticAsset(
-      UserConfig.favicon,
+      get("site.favicon", ""),
       resolveStaticAsset("favicon/favicon.ico", "img/icon.png"),
     ),
-    url: siteUrl,
-    baseUrl: basePath,
 
-    organizationName: UserConfig.hero_section.title,
-    deploymentBranch: "gh-pages",
-    onBrokenAnchors: "ignore",
-    onBrokenLinks: "warn",
+    organizationName: siteName,
+
+    /** Behavior when a broken anchor link is found (throw, warn, ignore) */
+    onBrokenAnchors: get("site.on_broken_anchors", "throw"),
+
+    /** Behavior when a broken internal link is found (throw, warn, ignore) */
+    onBrokenLinks: get("site.on_broken_links", "throw"),
 
+    // TODO: research & allow to configure this
     i18n: {
       defaultLocale: "en",
       locales: ["en"],
     },
 
-    headTags: PortoMetaTags,
+    headTags: buildHeadTags([
+      {
+        meta: {
+          name: "msapplication-TileColor",
+          content: "var(--ifm-background-color)",
+        },
+      },
+      {
+        meta: {
+          name: "theme-color",
+          content: "var(--ifm-background-color)",
+        },
+      },
+      ...get("site.head_tags", []),
+    ]),
 
     customFields: {
-      version,
+      portoVersion,
+
+      corsProxyList: [
+        ...[].concat(get("site.cors_proxy", [])),
+        "https://cors-proxy.soymadip.workers.dev/?url=",
+        "https://api.allorigins.win/raw?url=",
+      ].filter(Boolean),
 
       heroSection: {
         profilePic: resolveStaticAsset(
-          UserConfig.hero_section.profile_pic,
+          get("home_page.hero.profile_pic", "site.favicon", ""),
           "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,
+        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",
+          "site.tagline",
+          "Welcome to my portfolio.",
+        ),
+        learnMoreButtonTxt: get(
+          "home_page.hero.learn_more_btn_txt",
+          "Learn More",
+        ),
+        social: get("home_page.hero.social", null),
       },
 
       aboutMe: {
-        enable: UserConfig.about_me.enable,
+        /** Enable or disable the About Me section entirely */
+        enable: get("home_page.about.enable", true),
+
+        /** Heading text for the About section */
+        heading: get("home_page.about.heading", "About Me"),
+
+        /** The main image for the About section */
         image: resolveStaticAsset(
-          UserConfig.about_me.image ?? UserConfig.hero_section.profile_pic,
+          get(
+            "home_page.about.image",
+            "home_page.hero.profile_pic",
+            "site.favicon",
+            "",
+          ),
           "img/icon.png",
         ),
-        description: UserConfig.about_me.description,
-        skills: UserConfig.about_me.skills,
-        resumeLink: UserConfig.about_me.resume_link,
+        /** A detailed bio or description about yourself (Array of strings for paragraphs) */
+        bio: get("home_page.about.bio", [
+          "I am a developer who loves turning ideas into reality.",
+          "With background in computer science and a passion for design, I bridge the gap between aesthetics and functionality.",
+          "Driven by curiosity and a commitment to excellence.",
+        ]),
+
+        /** A list of your professional skills or technologies */
+        skills: get("home_page.about.skills", [
+          "skill1",
+          "skill2",
+          "skill3",
+          "skill4",
+        ]),
+        /** The title shown above the skills list */
+        skillsHeading: get("home_page.about.skills_heading", "My Skills"),
+        /** Path to your professional resume (PDF or external link) */
+        resume: resolveStaticAsset(get("home_page.about.resume", null), null),
+      },
+
+      projects: {
+        /** Enable or disable the Projects section */
+        enable: get("home_page.project_shelf.enable", true),
+
+        /** Heading for the projects section */
+        heading: get("home_page.project_shelf.heading", "My Projects"),
+
+        /** Sub-heading or description for your project shelf */
+        subheading: get(
+          "home_page.project_shelf.subheading",
+          "A collection of all my works, with featured projects highlighted",
+        ),
+        /** Enable automatic scrolling for the project cards */
+        autoplay: get("home_page.project_shelf.autoplay", true),
+
+        /** The list of projects to display (Array of project objects) */
+        projects: get("home_page.project_shelf.projects", [
+          {
+            title: "Project One",
+            desc: "A brief description of your project and the tech used.",
+            tags: ["React", "Portosaurus"],
+            state: "active",
+            website: "https://example.com",
+            repo: "https://github.com/",
+            demo: "https://example.com/demo",
+          },
+          {
+            title: "Project Two",
+            icon: PortoRoot + "/img/icon.png",
+            featured: true,
+            desc: "Another awesome project you've built recently.",
+            tags: ["python", "tag2"],
+            state: "completed",
+            website: "https://example.com",
+            repo: "https://github.com/",
+          },
+        ]).map((p) => ({
+          ...p,
+          icon: resolveStaticAsset(p.icon, ""),
+        })),
       },
 
-      projects: UserConfig.project_shelf,
-      experience: UserConfig.experience,
+      // TODO
+      experience: {
+        /** Enable or disable the Experience timeline */
+        enable: get("home_page.experience.enable", false),
+
+        /** Heading for the experience section */
+        heading: get("home_page.experience.heading", "Experience"),
+
+        /** Sub-heading for your professional journey */
+        subheading: get(
+          "home_page.experience.subheading",
+          "My professional journey and work experience",
+        ),
+        /** List of work history items */
+        list: get("home_page.experience.list", []),
+      },
 
       socialLinks: {
-        enable: UserConfig.social_links.enable,
-        links: UserConfig.social_links.links,
+        /** Enable or disable the Social Links / Contact section */
+        enable: get("home_page.social.enable", true),
+
+        /** Heading for the contact section */
+        heading: get("home_page.social.heading", "Get In Touch"),
+
+        /** Brief call-to-action or invitation to contact you */
+        subheading: get(
+          "home_page.social.subheading",
+          "Feel free to reach out for collaborations, questions, or just to say hello!",
+        ),
+        /** List of social media profiles and contact methods */
+        links: get("home_page.social.links", [
+          {
+            name: "Email",
+            desc: "Send me an email",
+            url: "mailto://you@yourdomain.com",
+          },
+          {
+            name: "LinkedIn",
+            desc: "Connect on LinkedIn",
+            url: "https://www.linkedin.com/in/yourusername",
+          },
+        ]),
       },
 
       robotsTxt: {
-        enable: UserConfig.robots_txt,
-        rules: [{ disallow: ["/notes/", "/tasks/"] }],
-        customLines: [],
+        /** Enable generation of robots.txt file */
+        enable: get("site.robots_txt.enable", true),
+        rules: [{ disallow: [`/${UserNotesDir}/`, `/${UserTasksDir}/`] }],
+
+        /** Additional custom lines to add to robots.txt */
+        customLines: get("site.robots_txt.custom_lines", []),
       },
 
       tasksPage: {
-        enable: UserConfig.tasks_page.enable,
-        title: UserConfig.tasks_page.title,
-        description: UserConfig.tasks_page.description,
-        taskList: UserConfig.tasks_page.tasks,
-      },
+        /** Enable or disable the Tasks/TODO page */
+        enable: get("tasks.enable", false),
 
-      corsProxyList: [
-        ...[].concat(UserConfig.cors_proxy || []),
-        "https://cors-proxy.soymadip.workers.dev/?url=",
-        "https://api.allorigins.win/raw?url=",
-      ].filter(Boolean),
+        /** Title for the Tasks page */
+        title: get("tasks.title", "Tasks"),
+
+        /** Subtitle for the Tasks page */
+        subtitle: get("tasks.subtitle", "My current focus and todo list"),
+        taskList: get("tasks.list", []),
+      },
     },
 
     presets: [
@@ -210,24 +300,24 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
         }),
         {
           docs: {
-            routeBasePath: "notes",
+            routeBasePath: UserNotesDir,
             path: UserNotesDir,
-            sidebarPath,
+            sidebarPath: path.resolve(PortoRoot, "src/theme/config/sidebar.js"),
             admonitions: {
-              keywords: [
-                "note",
-                "tip",
-                "info",
-                "warning",
-                "danger",
-                "question",
-              ],
               extendDefaults: true,
+              // keywords: [
+              //   "note",
+              //   "tip",
+              //   "info",
+              //   "warning",
+              //   "danger",
+              //   "question",
+              // ],
             },
           },
           blog: {
             path: UserBlogDir,
-            feedOptions: UserConfig.rss
+            feedOptions: get("site.rss", true)
               ? { type: ["rss", "atom"], xslt: true }
               : undefined,
             showReadingTime: false,
@@ -236,10 +326,10 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
             onUntruncatedBlogPosts: "warn",
           },
           theme: {
-            customCss: PortoCustomCss,
+            customCss: path.resolve(PortoRoot, "src/theme/css/custom.css"),
           },
           pages: {
-            path: PortoPagesDir,
+            path: path.resolve(PortoRoot, "src/theme/pages"),
           },
         },
       ],
@@ -251,44 +341,51 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
       [
         path.resolve(PortoRoot, "src/plugins/theme.mjs"),
         {
-          themeDir: PortoThemeDir,
+          themeDir: path.resolve(PortoRoot, "src/theme"),
         },
       ],
     ],
 
     markdown: {
-      mermaid: true,
+      mermaid: get("theme.markdown.mermaid", true),
       hooks: {
-        onBrokenMarkdownLinks: "warn",
+        onBrokenMarkdownLinks: get("theme.markdown.on_broken_links", "throw"),
+        onBrokenMarkdownImages: get("theme.markdown.on_broken_images", "throw"),
       },
     },
 
     themeConfig: {
-      image: resolveStaticAsset(UserConfig.social_card, "img/social-card.jpeg"),
+      image: resolveStaticAsset(
+        get("site.social_card", ""),
+        "img/social-card.jpeg",
+      ),
+
       docs: {
         sidebar: {
-          hideable: UserConfig.collapsable_sidebar,
+          hideable: get("theme.navigation.collapsable_sidebar", true),
         },
       },
+
       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,
+        defaultMode: get("theme.appearance.dark_mode", true) ? "dark" : "light",
+        disableSwitch: get("theme.appearance.disable_switch", false),
       },
       navbar: {
-        title: UserProjName,
-        hideOnScroll: UserConfig.hide_navbar_on_scroll,
+        title: get("site.title", "Your Portfolio"),
+        hideOnScroll: get("theme.navigation.hide_navbar_on_scroll", true),
         logo: {
           alt: "Site Logo",
           src: resolveStaticAsset(
-            UserConfig.favicon,
+            get("site.favicon", ""),
             resolveStaticAsset(
-              UserConfig.hero_section.profile_pic,
+              get("home_page.hero.profile_pic", ""),
               "img/icon.png",
             ),
           ),
@@ -300,7 +397,7 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
             className: "navbar-search-bar",
           },
           {
-            enable: UserConfig.about_me.enable,
+            enable: get("home_page.about.enable", true),
             value: {
               label: "About Me",
               to: "/#about",
@@ -309,7 +406,7 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
             },
           },
           {
-            enable: UserConfig.project_shelf.enable,
+            enable: get("home_page.project_shelf.enable", true),
             value: {
               label: "Projects",
               to: "/#projects",
@@ -318,7 +415,7 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
             },
           },
           {
-            enable: UserConfig.experience.enable,
+            enable: get("home_page.experience.enable", false),
             value: {
               label: "Experience",
               to: "/#experience",
@@ -327,7 +424,7 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
             },
           },
           {
-            enable: UserConfig.social_links.enable,
+            enable: get("home_page.social.enable", true),
             value: {
               label: "Contact",
               to: "/#contact",
@@ -341,18 +438,20 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
             position: "right",
             className: "_navbar-more-items",
             items: useEnabled([
-              { label: "Notes", to: "/notes" },
-              { label: "Blog", to: "/blog" },
+              { label: "Notes", to: `/${UserNotesDir}` },
+              { label: "Blog", to: `/${UserBlogDir}` },
               {
-                enable: UserConfig.tasks_page.enable,
-                value: { label: "Tasks", to: "/tasks" },
+                /** Toggle the Tasks page visibility */
+                enable: get("home_page.tasks.enable", false),
+                value: { label: "Tasks", to: `/${UserTasksDir}` },
               },
               {
-                enable: !UserConfig.disable_branding,
+                /** Hide the 'Powered by Portosaurus' branding in the menu */
+                enable: !get("theme.appearance.disable_branding", false),
                 value: {
-                  label: `Portosaurus v${version}`,
+                  label: `Portosaurus v${portoVersion}`,
                   className: "_nav-protosaurus-version",
-                  to: "https://github.com/soymadip/portosaurus",
+                  to: portoRepo,
                 },
               },
             ]),
@@ -364,9 +463,23 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
         maxHeadingLevel: 4,
       },
       prism: {
-        theme: catppuccinLatte,
-        darkTheme: catppuccinMocha,
-        additionalLanguages: ["java", "php", "bash"],
+        theme: (function () {
+          try {
+            return require(path.resolve(PortoRoot, "src/theme/config/prism.js"))
+              .catppuccinLatte;
+          } catch {
+            return {};
+          }
+        })(),
+        darkTheme: (function () {
+          try {
+            return require(path.resolve(PortoRoot, "src/theme/config/prism.js"))
+              .catppuccinMocha;
+          } catch {
+            return {};
+          }
+        })(),
+        additionalLanguages: ["java", "php", "bash", "diff"],
       },
       footer: {},
     },
@@ -410,8 +523,8 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
           hashed: true,
           indexDocs: true,
           docsDir: UserNotesDir,
-          docsRouteBasePath: "notes",
-          searchContextByPaths: ["notes", "blog"],
+          docsRouteBasePath: UserNotesDir,
+          searchContextByPaths: [UserNotesDir, UserBlogDir],
           highlightSearchTermsOnTargetPage: true,
           explicitSearchResultPath: true,
           hideSearchBarWithNoSearchContext: true,
@@ -421,7 +534,11 @@ export function buildDocuConfig(rawUserConfig, UserRoot) {
       "plugin-image-zoom",
     ],
 
-    staticDirectories: StaticDirs,
+    staticDirectories: [
+      UserStaticDir,
+      PortoAssetDir,
+      path.resolve(UserRoot, ".docusaurus/portosaurus/favicon"),
+    ].filter((d) => fs.existsSync(d)),
   };
 
   return config;