fossbook 0.0.2

package/README.md

@@ -0,0 +1,246 @@
+# Fossbook
+
+A lightweight static blog site generator for GitHub Pages, similar to Hugo but built with Node.js.
+
+## Features
+
+- **Markdown-based** — Write posts in Markdown with YAML front-matter
+- **Pagination** — Automatic home page pagination
+- **Tags** — Tag-based categorization with tag index and per-tag listing pages
+- **Theming** — Bundled Archie theme with support for custom themes
+- **SEO** — Open Graph and Twitter Card meta tags out of the box
+- **GitHub Pages** — Built-in CNAME support for custom domains
+- **Dev server** — Local preview server with Express
+- **Syntax highlighting** — Code block highlighting via highlight.js
+
+## Quick Start
+
+### Install globally
+
+```bash
+npm install -g fossbook
+```
+
+### Create a new site
+
+```bash
+mkdir my-blog && cd my-blog
+fossbook init
+```
+
+This creates the following structure:
+
+```
+my-blog/
+├── content/
+│   ├── about.md
+│   └── posts/
+├── static/
+│   └── images/
+├── fossbook.config.js
+└── package.json
+```
+
+### Create a new post
+
+```bash
+fossbook new "My First Post"
+```
+
+This creates `content/posts/My First Post/index.md` with pre-filled front-matter and an `images/` directory.
+
+### Build the site
+
+```bash
+fossbook build
+```
+
+### Preview locally
+
+```bash
+fossbook serve
+```
+
+Open http://localhost:3000 to view your site.
+
+## Configuration
+
+Create a `fossbook.config.js` in your project root:
+
+```js
+module.exports = {
+  blogName: "My Blog",
+  authorName: "Your Name",
+  authorDescription: "A short bio",
+  authorWebsite: "https://example.com",
+  blogDescription: "A blog about things",
+  blogsite: "https://example.com",
+
+  // Optional
+  githubCNAME: "example.com",
+  googleAnalyticsID: "",
+  authorTwitter: "@you",
+  siteTwitter: "@yourblog",
+  githubRepository: "https://github.com/you/your-blog",
+  image: "https://example.com/default-image.png",
+  theme: "archie",
+
+  // Directory overrides (defaults shown)
+  content: "./content",
+  postsDir: "./content/posts",
+  outputDir: "./public",
+  staticDir: "./static",
+  themesDir: "./themes",
+};
+```
+
+## Content Format
+
+### Post front-matter
+
+```markdown
+---
+title: My Post Title
+date: 2026-02-17
+description: "A brief summary of the post"
+image: "feature.png"
+tags: "JavaScript, Node.js, Static Site"
+---
+
+Your Markdown content here...
+```
+
+### Directory structure
+
+```
+content/posts/My Post Title/
+├── index.md
+└── images/
+    └── feature.png
+```
+
+## CLI Reference
+
+```
+Usage: fossbook <command> [options]
+
+Commands:
+  build          Build the static site
+  serve          Build and start a local dev server
+  new <title>    Create a new post
+  init           Create a new fossbook site project
+
+Options:
+  -c, --config   Path to config file (default: ./fossbook.config.js)
+  -o, --output   Output directory (default: ./public)
+  -p, --port     Dev server port (default: 3000)
+  -v, --version  Show version number
+  -h, --help     Show help
+```
+
+## Theming
+
+Fossbook ships with the Archie theme by default. To use a custom theme:
+
+1. Create a `themes/<your-theme>/` directory in your project
+2. Add `layouts/` (HTML templates) and `assets/` (CSS, fonts, images)
+3. Set `theme: "your-theme"` in `fossbook.config.js`
+
+Theme resolution order: user project `themes/` → built-in `themes/`.
+
+### Required layout files
+
+```
+layouts/
+├── home.html        # Home page with pagination
+├── post.html        # Individual post page
+├── page.html        # Static pages (e.g., about)
+├── all_posts.html   # All posts listing
+├── tag.html         # Per-tag listing
+├── tag_list.html    # Tag index page
+└── partials/
+    └── footer.html  # Footer partial
+```
+
+## Deploying to GitHub Pages
+
+Fossbook can automatically deploy your blog to GitHub Pages using GitHub Actions.
+
+### Prerequisites: Install GitHub CLI (`gh`)
+
+The `fossbook deploy` command uses the GitHub CLI to create repositories and monitor deployments.
+
+**Linux (Debian/Ubuntu):**
+
+```bash
+sudo apt install gh
+```
+
+**macOS:**
+
+```bash
+brew install gh
+```
+
+**Windows:**
+
+```bash
+winget install GitHub.cli
+```
+
+Then authenticate with your GitHub account:
+
+```bash
+gh auth login
+```
+
+Follow the prompts to log in via browser or token.
+
+### Initialize with GitHub
+
+```bash
+mkdir my-blog && cd my-blog
+fossbook init --github
+```
+
+This will:
+1. Scaffold the site project (config, content directories)
+2. Create a GitHub repository for your blog
+3. Generate `.github/workflows/deploy.yml` for automatic deployments
+4. Push the initial commit to GitHub
+
+### Publish a post
+
+```bash
+fossbook new "My New Article"
+# ... edit content/posts/My New Article/index.md ...
+fossbook deploy
+```
+
+Fossbook will build the site, commit, push to GitHub, wait for the CI/CD pipeline to finish, and display the live URL:
+
+```
+Building site... done.
+Committing: "Publish: My New Article"
+Pushing to origin/main...
+Waiting for GitHub Pages deployment... ✓
+
+✅ Published! View your article at:
+   https://username.github.io/my-blog/My%20New%20Article/
+```
+
+**Deploy options:**
+
+```bash
+fossbook deploy --message "Update homepage"   # Custom commit message
+fossbook deploy --no-wait                     # Push without waiting for CI
+```
+
+## License
+
+- Generator code: [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause)
+- Archie theme: [MIT License](https://github.com/athul/archie?tab=MIT-1-ov-file#readme)
+
+## Credits
+
+Adapted from [kartiknair's blog](https://github.com/kartiknair/blog) and styled using the [Archie theme](https://github.com/athul/archie).

package/bin/fossbook.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+const path = require("path");
+const { loadConfig } = require("../lib/mod/config");
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function printHelp() {
+  console.log(`
+Usage: fossbook <command> [options]
+
+Commands:
+  build          Build the static site
+  serve          Build and start a local dev server
+  new <title>    Create a new post
+  init           Create a new fossbook site project
+  deploy         Build, commit, push, and monitor deployment
+
+Options:
+  -c, --config   Path to config file (default: ./fossbook.config.js)
+  -o, --output   Output directory (default: ./public)
+  -p, --port     Dev server port (default: 3000)
+  --clean        Remove output directory before build (default: true)
+  --github       (init) Also create a GitHub repo and push
+  -m, --message  (deploy) Custom commit message
+  --no-wait      (deploy) Push without waiting for CI status
+  --draft        (deploy) Commit locally without pushing
+  -v, --version  Show version number
+  -h, --help     Show help
+`);
+}
+
+function getOption(flag, alias) {
+  const idx = args.indexOf(flag);
+  const aliasIdx = alias ? args.indexOf(alias) : -1;
+  const foundIdx = idx !== -1 ? idx : aliasIdx;
+  if (foundIdx !== -1 && foundIdx + 1 < args.length) {
+    return args[foundIdx + 1];
+  }
+  return null;
+}
+
+function hasFlag(flag, alias) {
+  return args.includes(flag) || (alias && args.includes(alias));
+}
+
+if (hasFlag("-v", "--version")) {
+  const pkg = require("../package.json");
+  console.log(`fossbook v${pkg.version}`);
+  process.exit(0);
+}
+
+if (hasFlag("-h", "--help") || !command) {
+  printHelp();
+  process.exit(0);
+}
+
+const configPath = getOption("-c", "--config");
+
+switch (command) {
+  case "build": {
+    const config = loadConfig(configPath);
+    const outputOverride = getOption("-o", "--output");
+    if (outputOverride) config.dev.outdir = outputOverride;
+
+    const { build } = require("../lib/index");
+    build(config);
+    break;
+  }
+
+  case "serve": {
+    const config = loadConfig(configPath);
+    const outputOverride = getOption("-o", "--output");
+    if (outputOverride) config.dev.outdir = outputOverride;
+    const port = getOption("-p", "--port") || 3000;
+
+    const { build } = require("../lib/index");
+    build(config);
+
+    const { serve } = require("../lib/server");
+    serve(config, Number(port));
+    break;
+  }
+
+  case "new": {
+    const title = args[1];
+    if (!title) {
+      console.error('Error: Please provide a post title. Usage: fossbook new "My Post Title"');
+      process.exit(1);
+    }
+    const config = loadConfig(configPath);
+    const { createPost } = require("../lib/new");
+    createPost(config, title);
+    break;
+  }
+
+  case "init": {
+    const { initProject } = require("../lib/init");
+    initProject({ github: hasFlag("--github") });
+    break;
+  }
+
+  case "deploy": {
+    const config = loadConfig(configPath);
+    const { deploy } = require("../lib/deploy");
+    deploy(config, {
+      message: getOption("-m", "--message"),
+      noWait: hasFlag("--no-wait"),
+      draft: hasFlag("--draft"),
+    });
+    break;
+  }
+
+  default:
+    console.error(`Unknown command: ${command}`);
+    printHelp();
+    process.exit(1);
+}

package/lib/all_posts.js

@@ -0,0 +1,32 @@
+const fs = require("fs");
+const path = require("path");
+const PageBase = require("./mod/page_base");
+
+module.exports = class AllPostsPage extends PageBase {
+  constructor(config) {
+    super(config);
+  }
+
+  // posts: array of Page objects
+  generateContent(posts) {
+    const pageTitle = "All posts";
+    if (!fs.existsSync(`${this.config.dev.outdir}/all_posts/`))
+      fs.mkdirSync(`${this.config.dev.outdir}/all_posts/`);
+
+    const data = { posts: posts, pageTitle: pageTitle };
+    this.url = `${this.config.blogsite}/posts.html`;
+    this.title = `${this.config.blogName}: ${data.pageTitle}`;
+    this.description = "All posts";
+    this.imageURL = this.config.image;
+
+    const templatePath = path.join(this.config.themePath, "layouts", "all_posts.html");
+    fs.writeFileSync(
+      `${this.config.dev.outdir}/all_posts/index.html`,
+      this.generateHTML(templatePath, data),
+      (e) => {
+        if (e) throw e;
+        console.log(`posts.html was created successfully`);
+      },
+    );
+  }
+};

package/lib/assets/placeholder.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="800" height="400" viewBox="0 0 800 400">
+  <rect width="800" height="400" fill="#f0f0f0"/>
+  <text x="400" y="200" font-family="Arial, sans-serif" font-size="32" fill="#999" text-anchor="middle" dominant-baseline="middle">Your Image Here</text>
+</svg>

package/lib/deploy.js

@@ -0,0 +1,202 @@
+const fs = require("fs");
+const path = require("path");
+const { execSync, exec } = require("child_process");
+const { build } = require("./index");
+
+/**
+ * Deploy the blog: build → commit → push → poll CI → show URL.
+ */
+async function deploy(config, options = {}) {
+  const cwd = process.cwd();
+  const deployConfig = config.deploy || {};
+  const branch = deployConfig.branch || "main";
+  const remote = deployConfig.remote || "origin";
+
+  // 1. Build the site
+  console.log("Building site...");
+  build(config);
+  console.log("Build complete.\n");
+
+  // 2. Check git is initialized
+  if (!fs.existsSync(path.join(cwd, ".git"))) {
+    console.error("Error: Not a git repository. Run 'fossbook init --github' first.");
+    process.exit(1);
+  }
+
+  // 3. Stage all changes
+  execSync("git add -A", { cwd, stdio: "inherit" });
+
+  // 4. Check if there are changes to commit
+  try {
+    execSync("git diff --cached --quiet", { cwd });
+    console.log("No changes to commit.");
+    return;
+  } catch {
+    // There are staged changes — continue
+  }
+
+  // 5. Determine commit message
+  let commitMessage = options.message;
+  if (!commitMessage) {
+    commitMessage = detectNewPost(config) || "Update blog";
+  }
+
+  // 6. Commit
+  console.log(`Committing: "${commitMessage}"`);
+  execSync(`git commit -m "${commitMessage.replace(/"/g, '\\"')}"`, {
+    cwd,
+    stdio: "inherit",
+  });
+
+  // 7. If --draft, stop here
+  if (options.draft) {
+    console.log("\nDraft committed locally. Run 'fossbook deploy' again to push.");
+    return;
+  }
+
+  // 8. Push
+  console.log(`\nPushing to ${remote}/${branch}...`);
+  try {
+    execSync(`git push ${remote} ${branch}`, { cwd, stdio: "inherit" });
+  } catch (e) {
+    console.error(`Error: Failed to push to ${remote}/${branch}.`);
+    console.error("Make sure the remote exists and you have push access.");
+    process.exit(1);
+  }
+
+  // 9. Wait for CI/CD and show URL
+  if (options.noWait) {
+    console.log("\nPushed! Skipping CI/CD status check (--no-wait).");
+    printSiteUrl(config);
+    return;
+  }
+
+  await waitForDeployment(cwd, config);
+}
+
+/**
+ * Detect if a new post was added and return a commit message.
+ */
+function detectNewPost(config) {
+  try {
+    const diffOutput = execSync("git diff --cached --name-only", {
+      encoding: "utf-8",
+    });
+    const postsDir = config.postsDir || "./content/posts";
+    const newPosts = diffOutput
+      .split("\n")
+      .filter((f) => f.startsWith(postsDir.replace("./", "")) && f.endsWith("index.md"))
+      .map((f) => {
+        // Extract post title from path like "content/posts/My Post/index.md"
+        const parts = f.split("/");
+        return parts[parts.length - 2];
+      });
+
+    if (newPosts.length === 1) {
+      return `Publish: ${newPosts[0]}`;
+    } else if (newPosts.length > 1) {
+      return `Publish ${newPosts.length} new posts`;
+    }
+  } catch {
+    // Fall through
+  }
+  return null;
+}
+
+/**
+ * Wait for GitHub Actions deployment to complete, then show the URL.
+ */
+async function waitForDeployment(cwd, config) {
+  // Check if gh is available
+  const hasGh = isGhAvailable();
+
+  if (!hasGh) {
+    console.log("\nGitHub CLI (gh) not found. Cannot monitor deployment status.");
+    console.log("Install it to see live deployment progress: https://cli.github.com/");
+    printSiteUrl(config);
+    return;
+  }
+
+  console.log("\nWaiting for GitHub Pages deployment...");
+
+  try {
+    // Wait a moment for the workflow to be triggered
+    await sleep(3000);
+
+    // Get the latest workflow run
+    const runJson = execSync(
+      'gh run list --workflow=deploy.yml --limit=1 --json databaseId,status,conclusion',
+      { cwd, encoding: "utf-8" }
+    );
+    const runs = JSON.parse(runJson);
+
+    if (runs.length === 0) {
+      console.log("No workflow runs found. The deployment may not be configured yet.");
+      console.log("Enable GitHub Pages: Settings → Pages → Source → GitHub Actions");
+      return;
+    }
+
+    const runId = runs[0].databaseId;
+
+    // Watch the run
+    console.log(`Monitoring workflow run #${runId}...`);
+    execSync(`gh run watch ${runId}`, { cwd, stdio: "inherit" });
+
+    // Check result
+    const resultJson = execSync(
+      `gh run view ${runId} --json conclusion`,
+      { cwd, encoding: "utf-8" }
+    );
+    const result = JSON.parse(resultJson);
+
+    if (result.conclusion === "success") {
+      console.log("\n✅ Deployment successful!");
+      printSiteUrl(config);
+    } else {
+      console.error(`\n❌ Deployment failed (conclusion: ${result.conclusion}).`);
+      console.log(`View details: gh run view ${runId} --log`);
+      process.exit(1);
+    }
+  } catch (e) {
+    console.warn("\nCould not monitor deployment status.");
+    console.log("Check your deployment at: https://github.com → Actions tab");
+    printSiteUrl(config);
+  }
+}
+
+/**
+ * Print the site URL based on config.
+ */
+function printSiteUrl(config) {
+  const siteUrl = config.blogsite || config.githubCNAME;
+  if (siteUrl && siteUrl !== "http://localhost:3000") {
+    console.log(`\nView your site at: ${siteUrl}`);
+  } else {
+    // Try to infer from git remote
+    try {
+      const remoteUrl = execSync("git remote get-url origin", { encoding: "utf-8" }).trim();
+      const match = remoteUrl.match(/github\.com[:/](.+?)(?:\.git)?$/);
+      if (match) {
+        const [owner, repo] = match[1].split("/");
+        console.log(`\nView your site at: https://${owner}.github.io/${repo}/`);
+      }
+    } catch {
+      console.log("\nYour site will be available on GitHub Pages once deployment completes.");
+    }
+  }
+}
+
+function isGhAvailable() {
+  try {
+    execSync("gh --version", { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+module.exports = { deploy };

package/lib/home.js

@@ -0,0 +1,59 @@
+const fs = require("fs");
+const path = require("path");
+const PageBase = require("./mod/page_base");
+
+module.exports = class Pagination extends PageBase {
+  constructor(config) {
+    super(config);
+  }
+
+  generateContent(posts) {
+    const postsPerPage = 5;
+    const numPages = Math.ceil(posts.length / postsPerPage);
+
+    if (fs.existsSync(`${this.config.dev.outdir}/page`))
+      fs.rmSync(`${this.config.dev.outdir}/page`, { recursive: true });
+
+    fs.mkdirSync(`${this.config.dev.outdir}/page`);
+
+    // copy content/page/1.html to outdir/page/1.html
+    const contentPagePath = path.join(this.config.dev.content, "page", "1.html");
+    if (fs.existsSync(contentPagePath))
+      fs.copyFileSync(
+        contentPagePath,
+        `${this.config.dev.outdir}/page/1.html`,
+      );
+
+    for (let i = 0; i < numPages; i++) {
+      const pagePosts = posts.slice(i * postsPerPage, (i + 1) * postsPerPage);
+
+      let filePath;
+      let url;
+      if (i === 0) {
+        filePath = `${this.config.dev.outdir}/index.html`;
+        url = this.config.blogsite;
+      } else {
+        filePath = `${this.config.dev.outdir}/page/${i + 1}.html`;
+        url = `${this.config.blogsite}/page/${i + 1}.html`;
+      }
+      const prev = i - 1 >= 0 ? i : null;
+      const next = i + 1 < numPages ? i + 2 : null;
+
+      console.log("prev", prev, "next", next);
+      this.url = url;
+      this.title = `${this.config.blogName}`;
+      this.imageURL = this.config.image;
+      const data = { posts: pagePosts, prev: prev, next: next };
+
+      const templatePath = path.join(this.config.themePath, "layouts", "home.html");
+      fs.writeFile(
+        `${filePath}`,
+        this.generateHTML(templatePath, data),
+        (e) => {
+          if (e) throw e;
+          console.log(`page/${i + 1}.html was created successfully`);
+        },
+      );
+    }
+  }
+};