portosaurus 1.15.1 → 1.16.0

package/README.md

@@ -37,10 +37,10 @@ npx portosaurus init my-portfolio
 
 **Options:**
 
-- `-gh`: Automatically sets up GitHub Actions workflow for deployment.
-- `--install`: Installs dependencies automatically.
+- `-ngh, --no-github-pages`: Skip setting up GitHub Actions workflow for deployment.
+- `-ni, --no-install`: Skip automatic dependency installation.
 
-### 2. Start Development
+### 2. Start Development Server
 
 Navigate to your project and start the development server:
 
@@ -58,6 +58,26 @@ Your site will be available at `http://localhost:3000`.
 
 ### 3. Build & Deploy
 
+#### GitHub Pages
+
+1. Create a repository on GitHub named `yourUsername.github.io`.
+2. Go to the repo's `Settings` > `Pages` > `Build and deployment` > `Source` > **`GitHub Actions`**.
+3. Push your code:
+   ```bash
+   git remote add origin https://github.com/yourUsername/yourUsername.github.io.git
+   git branch -M main
+   git push -u origin main
+   ```
+
+#### Other Providers
+
+A portosaurus project can be deployed to any static hosting provider like:
+
+- Netlify
+- Vercel
+- Cloudflare Pages
+- Other static providers
+
 To generate the static site for production:
 
 ```bash
@@ -70,18 +90,15 @@ npm run build
 
 The output will be in the `build/` directory.
 
-#### GitHub Pages (Automated)
+To preview the production build locally:
 
-If you used the `-gh` flag during init, just push to your repository:
+```bash
+# With Bun
+bun run serve
 
-1. Create a repository on GitHub.
-2. Push your code:
-   ```bash
-   git remote add origin https://github.com/username/repo.git
-   git branch -M main
-   git push -u origin main
-   ```
-3. Go to GitHub Settings > Pages > Build and deployment > Source > **GitHub Actions**.
+# With npm
+npm run serve
+```
 
 <br>
 

package/bin/portosaurus.js

@@ -18,8 +18,8 @@ import { fileURLToPath } from "url";
 import { spawn, execSync } from "child_process";
 import { createRequire } from "module";
 
-import { logger } from "../utils/logger.js";
-import { createConfig } from "../utils/createConfig.js";
+import { logger } from "../src/utils/logger.js";
+import { createConfig } from "../src/utils/createConfig.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -32,10 +32,18 @@ const program = new Command();
 program
   .name("portosaurus")
   .description("CLI for Portosaurus - The complete portfolio solution")
-  .version(packageJson.version);
+  .version(packageJson.version, "-v, --version", "output the current version");
 
 // ----------- HELPERS -------------
 
+// Helper to clean up internal index.md from user notes
+function cleanUserNotesIndex(projectRoot) {
+  const userNotesIndex = path.join(projectRoot, "notes", "index.md");
+  if (existsSync(userNotesIndex)) {
+    removeSync(userNotesIndex);
+  }
+}
+
 async function prepareDocusaurusRun(projectRoot) {
   const configPath = path.join(projectRoot, "config.js");
 
@@ -48,22 +56,34 @@ async function prepareDocusaurusRun(projectRoot) {
   }
 
   // Ensure internal files are synced to .portosaurus
-  const internalSrc = path.join(__dirname, "../internal/src");
-  const internalSidebars = path.join(__dirname, "../internal/sidebars.js");
-  const internalNotesIndex = path.join(__dirname, "../internal/notes/index.md");
-
+  const internalDir = path.join(__dirname, "../src/internal");
   const dotPorto = path.join(projectRoot, ".portosaurus");
-  const userSrc = path.join(dotPorto, "src");
-  const userSidebars = path.join(dotPorto, "sidebars.js");
 
-  // Ensure .portosaurus exists
-  fs.ensureDirSync(dotPorto);
+  // Ensure .portosaurus exists and is clean
+  fs.emptyDirSync(dotPorto);
 
-  // Always copy/overwrite src/
-  fs.copySync(internalSrc, userSrc);
+  // 1. Copy everything from internal to .portosaurus
+  fs.copySync(internalDir, dotPorto);
 
-  // Always copy/overwrite sidebars.js
-  fs.copySync(internalSidebars, userSidebars);
+  // 2. Overwrite with user files if they exist in project root
+  const internalFiles = readdirSync(internalDir);
+
+  for (const file of internalFiles) {
+    const userFile = path.join(projectRoot, file);
+
+    if (existsSync(userFile)) {
+      fs.copySync(userFile, path.join(dotPorto, file), {
+        overwrite: true,
+        filter: (src) => {
+          // Ignore notes/index.md
+          if (src.endsWith(path.join("notes", "index.md"))) {
+            return false;
+          }
+          return true;
+        },
+      });
+    }
+  }
 
   // Ensure user has essential folders
   const userRootNotes = path.join(projectRoot, "notes");
@@ -74,12 +94,6 @@ async function prepareDocusaurusRun(projectRoot) {
   fs.ensureDirSync(userRootBlog);
   fs.ensureDirSync(userRootStatic);
 
-  // Always ensure index.md exists (framework-managed file)
-  const userNotesIndex = path.join(userRootNotes, "index.md");
-  if (!fs.existsSync(userNotesIndex)) {
-    fs.copySync(internalNotesIndex, userNotesIndex);
-  }
-
   // Load user config
   const require = createRequire(import.meta.url);
 
@@ -119,7 +133,7 @@ module.exports = ${JSON.stringify(docusaurusConfig, null, 2)};`;
 
 async function runDocusaurus(command, args, dotPorto, projectRoot) {
   // Detect package manager and find docusaurus binary
-  const { findDocusaurusBin } = await import("../utils/packageManager.js");
+  const { findDocusaurusBin } = await import("../src/utils/packageManager.js");
   const docusaurus = findDocusaurusBin(projectRoot || process.cwd());
 
   logger.info(
@@ -176,7 +190,7 @@ program
       mkdirSync(projectPath);
 
       // Copy template files
-      const templatePath = path.resolve(__dirname, "../template");
+      const templatePath = path.resolve(__dirname, "../src/template");
 
       // Check if template exists (it might not be populated yet)
       if (!existsSync(templatePath)) {
@@ -209,6 +223,7 @@ program
         scripts: {
           dev: "portosaurus dev",
           start: "portosaurus start",
+          serve: "portosaurus serve",
           build: "portosaurus build",
         },
         dependencies: {
@@ -251,7 +266,7 @@ program
 
       // Detect package manager for install instructions
       const { detectPackageManager } =
-        await import("../utils/packageManager.js");
+        await import("../src/utils/packageManager.js");
       const pm = detectPackageManager(projectPath) || "npm";
       const installCmd = pm === "npm" ? "npm install" : `${pm} install`;
       const runCmd = pm === "npm" ? "npm run" : `${pm} run`;
@@ -287,6 +302,8 @@ program
     }
   });
 
+
+
 // --- START COMMAND ---
 
 program
@@ -302,6 +319,8 @@ program
     } catch (error) {
       logger.error(`Failed to start: ${error.message}`);
       process.exit(1);
+    } finally {
+      cleanUserNotesIndex(projectRoot);
     }
   });
 
@@ -334,6 +353,37 @@ program
     } catch (error) {
       logger.error(`Failed to build: ${error.message}`);
       process.exit(1);
+    } finally {
+      cleanUserNotesIndex(projectRoot);
+    }
+  });
+
+// --- SERVE COMMAND ---
+
+program
+  .command("serve")
+  .description("Serve the built static site locally")
+  .action(async () => {
+    const projectRoot = process.cwd();
+    logger.info("Serving Portosaurus site...");
+
+    try {
+      const { dotPorto } = await prepareDocusaurusRun(projectRoot);
+      const buildDir = path.join(projectRoot, "build");
+
+      if (!existsSync(buildDir)) {
+        logger.error(
+          "Build directory not found. Run 'portosaurus build' first.",
+        );
+        process.exit(1);
+      }
+
+      await runDocusaurus("serve", ["--dir", buildDir], dotPorto, projectRoot);
+    } catch (error) {
+      logger.error(`Failed to serve: ${error.message}`);
+      process.exit(1);
+    } finally {
+      cleanUserNotesIndex(projectRoot);
     }
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portosaurus",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "author": "soymadip",
   "license": "GPL-3.0-only",
   "description": "Complete portfolio cum personal website solution for your digital personality.",
@@ -26,9 +26,9 @@
   },
   "files": [
     "bin/",
-    "internal/",
-    "template/",
-    "utils/"
+    "src/internal/",
+    "src/template/",
+    "src/utils/"
   ],
   "dependencies": {
     "@docusaurus/core": "^3.9.2",

package/src/internal/README.md

@@ -0,0 +1,3 @@
+# Inernals
+
+Everything in this dir will copied at runtime at portusaurus working dir and will be overriten if user has any duplicate file.

package/src/template/README.md

@@ -0,0 +1,82 @@
+<br>
+<div align="center">
+    <img src="https://raw.githubusercontent.com/soymadip/portosaurus/refs/heads/compiler/static/img/icon.png" width=90>
+    <h1>My Portfolio Site</h1>
+    <p>
+        Complete portfolio cum personal website for my digital personality
+        <br>
+        <small>Made with <a href="https://github.com/soymadip/portosaurus">Portosaurus</a></small>
+    </p>
+</div>
+
+## Project Structure
+
+```
+.
+├── config.js          # Site configuration
+├── blog/              # Blog posts    (Markdown/MDX)
+├── notes/             # Documentation (Markdown/MDX)
+├── static/            # Static assets (images, files, binaries)
+└── package.json       # Dependencies
+```
+
+## Configuration
+
+Edit [`config.js`](./config.js) to customize your site. See the [Portosaurus documentation](https://github.com/soymadip/portosaurus#configuration) for all available options.
+
+## Development
+
+Start the development server:
+
+```bash
+# With Bun
+bun run dev
+
+# With npm
+npm run dev
+```
+
+The site will be available at `http://localhost:3000`.
+
+## Build & Deploy
+
+### GitHub Pages
+
+1. Create a repository on GitHub named `yourUsername.github.io`.
+2. Go to the repo's `Settings` > `Pages` > `Build and deployment` > `Source` > **`GitHub Actions`**.
+3. Push your code:
+   ```bash
+   git remote add origin https://github.com/yourUsername/yourUsername.github.io.git
+   git branch -M main
+   git push -u origin main
+   ```
+
+### Other Providers
+
+A portosaurus project can be deployed to any static hosting provider like:
+
+- Netlify
+- Vercel
+- Cloudflare pages
+- Other static providers
+
+To generate the static site for production:
+
+```bash
+# With Bun
+bun run build
+
+# With npm
+npm run build
+```
+
+The output will be in the `build/` directory.
+
+---
+
+<div align="center">
+
+Made with [Portosaurus](https://github.com/soymadip/portosaurus)
+
+<br>
+</div>

package/src/template/blog/authors.yml

@@ -0,0 +1,5 @@
+you:
+  name: Your Name
+  title: Maintainer
+  url: https://github.com/yourUsername
+  image_url: https://github.com/yourUsername.png

package/{template → src/template}/blog/welcome.md

@@ -1,7 +1,7 @@
 ---
 slug: welcome
 title: Welcome
-authors: [soymadip]
+authors: [you]
 tags: [hello, portosaurus]
 ---
 

package/{template/notes/getting-started.md → src/template/notes/welcome.md}

@@ -1,4 +1,5 @@
 ---
+title: getting-started
 sidebar_position: 1
 ---
 

package/{utils → src/utils}/createConfig.js

@@ -66,10 +66,11 @@ export function createConfig(userConfig, projectRoot = process.cwd()) {
   const title = usrConf.hero_section?.title || projName;
   const tagline = usrConf.hero_section?.description || projDesc;
 
-  // Resolve paths relative to project root (where config.js is)
-  const notesPath = path.resolve(projectRoot, "notes");
-  const blogPath = path.resolve(projectRoot, "blog");
-  const staticPath = path.resolve(projectRoot, "static");
+  // Resolve paths relative to .portosaurus (the build context)
+  const dotPorto = path.resolve(projectRoot, ".portosaurus");
+  const notesPath = path.resolve(dotPorto, "notes");
+  const blogPath = path.resolve(dotPorto, "blog");
+  const staticPath = path.resolve(dotPorto, "static");
 
   // ---------- Docusaurus Config -----------
   const config = {
@@ -109,7 +110,7 @@ export function createConfig(userConfig, projectRoot = process.cwd()) {
           docs: {
             path: notesPath,
             routeBasePath: "notes",
-            sidebarPath: "./sidebars.js", // Inside .portosaurus
+            sidebarPath: "./src/config/sidebars.js", // Inside .portosaurus
             // editUrl: '...',
           },
           blog: {

package/{utils → src/utils}/packageManager.js

@@ -34,7 +34,7 @@ export function detectPackageManager(projectRoot) {
     }
   }
 
-  return "npm"; // Ultimate fallback
+  return "npm"; // fallback
 }
 
 /**
@@ -44,6 +44,7 @@ export function detectPackageManager(projectRoot) {
 export function getRunCommand(packageManager, binaryName, args = []) {
   switch (packageManager) {
     case "bun":
+
       // Bun can run binaries directly with `bun run`
       return {
         command: "bun",

package/internal/src/config/sidebar.js

@@ -1,20 +0,0 @@
-
-const sidebar = {
-  
-  notes: [
-    {
-      type: 'category',
-      label: 'Notes',
-      link: { type: 'doc', id: 'index' },
-      items: [
-        {
-          type: 'autogenerated',
-          dirName: '.'
-        }
-      ]
-    }
-  ]
-};
-
-
-module.exports = sidebar;

package/template/README.md

@@ -1,70 +0,0 @@
-# Portosaurus Project
-
-A portfolio website built with [Portosaurus](https://github.com/soymadip/portosaurus).
-
-## Getting Started
-
-### Development
-
-Start the development server:
-
-```bash
-# With Bun
-bun run dev
-
-# With npm
-npm run dev
-```
-
-The site will be available at `http://localhost:3000`.
-
-### Build
-
-Build the static site:
-
-```bash
-# With Bun
-bun run build
-
-# With npm
-npm run build
-```
-
-The output will be in the `build/` directory.
-
-## Project Structure
-
-```
-.
-├── config.js          # Site configuration
-├── blog/              # Blog posts (Markdown)
-├── notes/             # Documentation (Markdown)
-├── static/            # Static assets (images, files)
-└── package.json       # Dependencies
-```
-
-## Configuration
-
-Edit `config.js` to customize your site. See the [Portosaurus documentation](https://github.com/soymadip/portosaurus) for all available options.
-
-## Deployment
-
-### GitHub Pages
-
-1. Push your project to GitHub
-2. Go to Settings > Pages
-3. Set Source to "GitHub Actions"
-4. The site will deploy automatically on push
-
-### Other Platforms
-
-The `build/` directory contains a static site that can be deployed to:
-
-- Vercel
-- Netlify
-- Cloudflare Pages
-- Any static hosting service
-
----
-
-Made with [Portosaurus](https://github.com/soymadip/portosaurus)

package/template/blog/authors.yml

@@ -1,5 +0,0 @@
-soymadip:
-  name: soymadip
-  title: Maintainer
-  url: https://github.com/soymadip
-  image_url: https://github.com/soymadip.png