fossbook 0.2.15 → 0.2.16

package/bin/fossbook.js

@@ -60,74 +60,85 @@ if (hasFlag("-h", "--help") || !command) {
 
 const configPath = getOption("-c", "--config");
 
-switch (command) {
-  case "build": {
-    const config = loadConfig(configPath);
-    const outputOverride = getOption("-o", "--output");
-    if (outputOverride) config.dev.outdir = outputOverride;
-    config.includeDrafts = hasFlag("--include-drafts");
-
-    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;
-    config.includeDrafts = hasFlag("--include-drafts");
-    const port = getOption("-p", "--port") || 3000;
+async function run() {
+  switch (command) {
+    case "build": {
+      const config = loadConfig(configPath);
+      const outputOverride = getOption("-o", "--output");
+      if (outputOverride) config.dev.outdir = outputOverride;
+      config.includeDrafts = hasFlag("--include-drafts");
+
+      const { build } = require("../lib/index");
+      await build(config);
+      break;
+    }
 
-    const { build } = require("../lib/index");
-    build(config);
+    case "serve": {
+      const config = loadConfig(configPath);
+      const outputOverride = getOption("-o", "--output");
+      if (outputOverride) config.dev.outdir = outputOverride;
+      config.includeDrafts = hasFlag("--include-drafts");
+      const port = getOption("-p", "--port") || 3000;
 
-    const { serve } = require("../lib/server");
-    serve(config, Number(port));
-    break;
-  }
+      const { build } = require("../lib/index");
+      await build(config);
 
-  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 { serve } = require("../lib/server");
+      serve(config, Number(port));
+      break;
     }
-    if (hasFlag("--lang") && !getOption("--lang")) {
-      console.error("Error: Please provide at least one language after --lang");
-      process.exit(1);
+
+    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);
+      }
+      if (hasFlag("--lang") && !getOption("--lang")) {
+        console.error(
+          "Error: Please provide at least one language after --lang",
+        );
+        process.exit(1);
+      }
+      const config = loadConfig(configPath);
+      const { createPost } = require("../lib/new");
+      try {
+        createPost(config, title, getOption("--lang"));
+      } catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+      }
+      break;
     }
-    const config = loadConfig(configPath);
-    const { createPost } = require("../lib/new");
-    try {
-      createPost(config, title, getOption("--lang"));
-    } catch (error) {
-      console.error(`Error: ${error.message}`);
-      process.exit(1);
+
+    case "init": {
+      const { initProject } = require("../lib/init");
+      const projectName = !args[1] || args[1].startsWith("--") ? null : args[1];
+      initProject({ github: hasFlag("--github"), name: projectName });
+      break;
     }
-    break;
-  }
 
-  case "init": {
-    const { initProject } = require("../lib/init");
-    const projectName = !args[1] || args[1].startsWith("--") ? null : args[1];
-    initProject({ github: hasFlag("--github"), name: projectName });
-    break;
-  }
+    case "deploy": {
+      const config = loadConfig(configPath);
+      const { deploy } = require("../lib/deploy");
+      await deploy(config, {
+        message: getOption("-m", "--message"),
+        noWait: hasFlag("--no-wait"),
+        draft: hasFlag("--draft"),
+      });
+      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);
   }
-
-  default:
-    console.error(`Unknown command: ${command}`);
-    printHelp();
-    process.exit(1);
 }
+
+run().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/lib/deploy.js

@@ -15,7 +15,7 @@ async function deploy(config, options = {}) {
   // 1. Build the site
   console.log("Building site...");
   config.includeDrafts = false;
-  build(config);
+  await build(config);
   console.log("Build complete.\n");
 
   // 2. Check git is initialized

package/lib/index.js

@@ -6,8 +6,13 @@ const HomePagination = require("./home");
 const AllPostsPage = require("./all_posts");
 const Posts = require("./posts");
 const TagPages = require("./tag");
+const {
+  beginImageBuild,
+  finishImageBuild,
+  publishImage,
+} = require("./mod/image");
 
-function copyDirectoryRecursive(src, dest) {
+async function copyDirectoryRecursive(src, dest, config) {
   fs.mkdirSync(dest, { recursive: true });
   const entries = fs.readdirSync(src, { withFileTypes: true });
 
@@ -16,9 +21,11 @@ function copyDirectoryRecursive(src, dest) {
     const destPath = path.join(dest, entry.name);
 
     if (entry.isDirectory()) {
-      copyDirectoryRecursive(srcPath, destPath);
+      await copyDirectoryRecursive(srcPath, destPath, config);
+    } else if (path.extname(entry.name).toLowerCase() === ".png") {
+      await publishImage(srcPath, destPath, config, undefined, false);
     } else {
-      fs.copyFileSync(srcPath, destPath);
+      await fs.promises.copyFile(srcPath, destPath);
     }
   }
 }
@@ -35,9 +42,10 @@ function createPostTranslationIndex(languageConfigs) {
 
     const translations = [];
     for (const config of languageConfigs) {
-      const sourceFile = config.language === config.defaultLanguage
-        ? "index.md"
-        : `index.${config.language}.md`;
+      const sourceFile =
+        config.language === config.defaultLanguage
+          ? "index.md"
+          : `index.${config.language}.md`;
       const sourcePath = path.join(postsDir, entry.name, sourceFile);
       if (!fs.existsSync(sourcePath)) continue;
 
@@ -65,18 +73,21 @@ function createAboutTranslations(languageConfigs) {
 
   const contentDir = languageConfigs[0].dev.content;
   return languageConfigs.flatMap((config) => {
-    const sourceFile = config.language === config.defaultLanguage
-      ? "about.md"
-      : `about.${config.language}.md`;
+    const sourceFile =
+      config.language === config.defaultLanguage
+        ? "about.md"
+        : `about.${config.language}.md`;
     if (!fs.existsSync(path.join(contentDir, sourceFile))) return [];
 
-    return [{
-      language: config.language,
-      languageName: config.languageName,
-      path: `${config.basePath || "/"}about/`,
-      url: `${config.blogsite}/about/`,
-      isDefault: config.language === config.defaultLanguage,
-    }];
+    return [
+      {
+        language: config.language,
+        languageName: config.languageName,
+        path: `${config.basePath || "/"}about/`,
+        url: `${config.blogsite}/about/`,
+        isDefault: config.language === config.defaultLanguage,
+      },
+    ];
   });
 }
 
@@ -110,16 +121,16 @@ function createTagListTranslations(languageConfigs) {
   }));
 }
 
-function buildLanguage(config) {
+async function buildLanguage(config) {
   fs.mkdirSync(config.dev.outdir, { recursive: true });
 
   // Create post pages in output directory
   const posts = new Posts(config);
   const postObjects = posts.createPostObjects();
 
-  postObjects.forEach((post) => {
-    post.generateContent("post.html");
-  });
+  for (const post of postObjects) {
+    await post.generateContent("post.html");
+  }
 
   // Create home page and pagination in output/page directory
   const homePagination = new HomePagination(config);
@@ -137,31 +148,38 @@ function buildLanguage(config) {
   tagPages.generateContent(postObjects);
 
   // Create about page in output/about directory
-  const aboutFile = config.language === config.defaultLanguage
-    ? "about.md"
-    : `about.${config.language}.md`;
+  const aboutFile =
+    config.language === config.defaultLanguage
+      ? "about.md"
+      : `about.${config.language}.md`;
   const aboutPath = path.resolve(config.dev.content, aboutFile);
   if (fs.existsSync(aboutPath)) {
     const aboutPage = new Page(config);
     aboutPage.readSource(aboutPath, "about");
     aboutPage.translations = config.aboutTranslations || [];
-    aboutPage.generateContent("page.html", "about");
+    await aboutPage.generateContent("page.html", "about");
   }
 
   // Copy static directory to output directory
   const staticImagesDir = path.join(config.dev.staticDir, "images");
   if (fs.existsSync(staticImagesDir)) {
-    copyDirectoryRecursive(staticImagesDir, path.join(config.dev.outdir, "images"));
+    await copyDirectoryRecursive(
+      staticImagesDir,
+      path.join(config.dev.outdir, "images"),
+      config,
+    );
   }
 
   // Copy theme assets to output directory
   const themeAssetsDir = path.join(config.themePath, "assets");
   if (fs.existsSync(themeAssetsDir)) {
-    copyDirectoryRecursive(themeAssetsDir, config.dev.outdir);
+    await copyDirectoryRecursive(themeAssetsDir, config.dev.outdir, config);
   }
 }
 
-function build(config) {
+async function build(config) {
+  beginImageBuild();
+
   // Remove the output directory
   if (fs.existsSync(config.dev.outdir))
     fs.rmSync(config.dev.outdir, { recursive: true });
@@ -183,7 +201,10 @@ function build(config) {
     languageConfig.allPostsTranslations = allPostsTranslations;
     languageConfig.tagListTranslations = tagListTranslations;
   });
-  languageConfigs.forEach(buildLanguage);
+  for (const languageConfig of languageConfigs) {
+    await buildLanguage(languageConfig);
+  }
+  await finishImageBuild(config);
 
   // Create CNAME file for GitHub Pages
   if (config.githubCNAME)

package/lib/init.js

@@ -2,6 +2,12 @@ const fs = require("fs");
 const path = require("path");
 const { execSync } = require("child_process");
 const readline = require("readline");
+const { CACHE_SCHEMA_VERSION } = require("./mod/image");
+
+const IMAGE_CACHE_SCHEMA = `v${CACHE_SCHEMA_VERSION}`;
+const IMAGE_CACHE_IGNORE_RULE = ".fossbook-cache/";
+const IMAGE_CACHE_SAVE_CONDITION =
+  "steps.image-cache-restore.outputs.cache-hit != 'true' && steps.image-cache-status.outputs.new-entries == 'true'";
 
 const DEPLOY_WORKFLOW = `name: Deploy to GitHub Pages
 
@@ -36,9 +42,41 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Resolve Fossbook image cache
+        id: image-cache-config
+        run: node -e "require('fossbook/lib/mod/github_cache').writeGitHubCacheOutputs()"
+
+      - name: Restore Fossbook image cache
+        id: image-cache-restore
+        uses: actions/cache/restore@v4
+        continue-on-error: true
+        with:
+          path: \${{ steps.image-cache-config.outputs.cache-path }}/images
+          key: \${{ runner.os }}-\${{ runner.arch }}-fossbook-images-${IMAGE_CACHE_SCHEMA}-\${{ steps.image-cache-config.outputs.input-hash }}-\${{ github.run_id }}-\${{ github.run_attempt }}
+          restore-keys: |
+            \${{ runner.os }}-\${{ runner.arch }}-fossbook-images-${IMAGE_CACHE_SCHEMA}-\${{ steps.image-cache-config.outputs.input-hash }}-
+            \${{ runner.os }}-\${{ runner.arch }}-fossbook-images-${IMAGE_CACHE_SCHEMA}-
+
       - name: Build site
         run: npx fossbook build
 
+      - name: Read Fossbook image cache status
+        id: image-cache-status
+        continue-on-error: true
+        shell: bash
+        env:
+          FOSSBOOK_CACHE_STATUS: \${{ steps.image-cache-config.outputs.status-path }}
+        run: |
+          node -e "const fs=require('fs');let writes=0;try{writes=JSON.parse(fs.readFileSync(process.env.FOSSBOOK_CACHE_STATUS,'utf8')).writes||0}catch(error){console.warn(error.message)}fs.appendFileSync(process.env.GITHUB_OUTPUT, 'new-entries='+(writes>0)+'\\n')"
+
+      - name: Save Fossbook image cache
+        if: \${{ ${IMAGE_CACHE_SAVE_CONDITION} }}
+        uses: actions/cache/save@v4
+        continue-on-error: true
+        with:
+          path: \${{ steps.image-cache-config.outputs.cache-path }}/images
+          key: \${{ runner.os }}-\${{ runner.arch }}-fossbook-images-${IMAGE_CACHE_SCHEMA}-\${{ steps.image-cache-config.outputs.input-hash }}-\${{ github.run_id }}-\${{ github.run_attempt }}
+
       - name: Setup Pages
         uses: actions/configure-pages@v4
         with:
@@ -70,10 +108,7 @@ function initProject(options = {}) {
   }
 
   // Create directories
-  const dirs = [
-    "content/posts",
-    "static/images",
-  ];
+  const dirs = ["content/posts", "static/images"];
 
   dirs.forEach((dir) => {
     const dirPath = path.join(cwd, dir);
@@ -95,8 +130,13 @@ function initProject(options = {}) {
   // Create .gitignore
   const gitignorePath = path.join(cwd, ".gitignore");
   if (!fs.existsSync(gitignorePath)) {
-    fs.writeFileSync(gitignorePath, "node_modules/\npublic/\n");
+    fs.writeFileSync(
+      gitignorePath,
+      `node_modules/\npublic/\n${IMAGE_CACHE_IGNORE_RULE}\n`,
+    );
     console.log("Created: .gitignore");
+  } else if (ensureGitignoreRule(gitignorePath, IMAGE_CACHE_IGNORE_RULE)) {
+    console.log(`Updated: .gitignore (${IMAGE_CACHE_IGNORE_RULE})`);
   }
 
   // Create fossbook.config.js
@@ -119,6 +159,14 @@ function initProject(options = {}) {
   image: "",
   theme: "archie",
 
+  // PNG publishing optimization
+  imageOptimization: true,
+  imageMaxWidth: 1400,
+  imageMaxWidthOverride: 1200,
+  imageWebP: true,
+  imageResponsiveWidths: [600, 800, 1000],
+  cacheDir: "./.fossbook-cache",
+
   // Languages (optional)
   defaultLanguage: "en",
   defaultLanguageInSubdir: false,
@@ -192,7 +240,9 @@ Welcome to my blog!
       execSync("npm install", { cwd, stdio: "inherit" });
       console.log("Created: package-lock.json");
     } catch {
-      console.warn("Warning: npm install failed. You may need to run it manually.");
+      console.warn(
+        "Warning: npm install failed. You may need to run it manually.",
+      );
     }
   }
 
@@ -203,13 +253,13 @@ Welcome to my blog!
 
   console.log("\nSite initialized! Next steps:");
   if (!options.github) {
-    console.log('  1. Edit fossbook.config.js with your site settings');
+    console.log("  1. Edit fossbook.config.js with your site settings");
     console.log('  2. Run: fossbook new "My First Post"');
     console.log("  3. Edit your post in content/posts/");
     console.log("  4. Run: fossbook build");
     console.log("  5. Run: fossbook serve");
   } else {
-    console.log('  1. Edit fossbook.config.js with your site settings');
+    console.log("  1. Edit fossbook.config.js with your site settings");
     console.log('  2. Run: fossbook new "My First Post"');
     console.log("  3. Edit your post in content/posts/");
     console.log("  4. Run: fossbook deploy");
@@ -223,10 +273,10 @@ function initGitHub(cwd) {
   } catch {
     console.error(
       "Error: GitHub CLI (gh) is not installed.\n" +
-      "Install it: https://cli.github.com/\n" +
-      "  Linux:   sudo apt install gh\n" +
-      "  macOS:   brew install gh\n" +
-      "  Windows: winget install GitHub.cli"
+        "Install it: https://cli.github.com/\n" +
+        "  Linux:   sudo apt install gh\n" +
+        "  macOS:   brew install gh\n" +
+        "  Windows: winget install GitHub.cli",
     );
     process.exit(1);
   }
@@ -256,7 +306,9 @@ function initGitHub(cwd) {
     });
   } catch {
     // Repo may already exist — ask user what to do
-    console.warn(`\nA GitHub repository named "${repoName}" already exists on your account.`);
+    console.warn(
+      `\nA GitHub repository named "${repoName}" already exists on your account.`,
+    );
     const answer = promptSync("Push to the existing repo? (y/n): ");
     if (answer.toLowerCase() !== "y") {
       console.log("Cancelled. Your local site files are still available.");
@@ -275,11 +327,18 @@ function initGitHub(cwd) {
           stdio: ["pipe", "pipe", "ignore"],
         }).trim();
         const remoteUrl = `git@github.com:${ghUser}/${repoName}.git`;
-        execSync(`git remote add origin ${remoteUrl}`, { cwd, stdio: "inherit" });
+        execSync(`git remote add origin ${remoteUrl}`, {
+          cwd,
+          stdio: "inherit",
+        });
         console.log(`Added remote: ${remoteUrl}`);
       } catch {
-        console.warn("Warning: Could not add git remote. Add it manually with:");
-        console.warn(`  git remote add origin git@github.com:<user>/${repoName}.git`);
+        console.warn(
+          "Warning: Could not add git remote. Add it manually with:",
+        );
+        console.warn(
+          `  git remote add origin git@github.com:<user>/${repoName}.git`,
+        );
       }
     }
   }
@@ -288,14 +347,19 @@ function initGitHub(cwd) {
   console.log("Committing and pushing to GitHub...");
   execSync("git add -A", { cwd, stdio: "inherit" });
   try {
-    execSync('git commit -m "Initial fossbook site"', { cwd, stdio: "inherit" });
+    execSync('git commit -m "Initial fossbook site"', {
+      cwd,
+      stdio: "inherit",
+    });
   } catch {
     // Nothing to commit
   }
   try {
     execSync("git push -u origin main", { cwd, stdio: "inherit" });
   } catch (e) {
-    console.warn("Warning: Could not push to origin. You may need to push manually.");
+    console.warn(
+      "Warning: Could not push to origin. You may need to push manually.",
+    );
   }
 
   console.log("\nGitHub repository created and pushed!");
@@ -323,4 +387,24 @@ function promptSync(question) {
   return str.trim();
 }
 
-module.exports = { initProject };
+function shouldSaveImageCache(cacheHit, newEntries) {
+  return cacheHit !== "true" && newEntries === true;
+}
+
+function ensureGitignoreRule(gitignorePath, rule) {
+  const contents = fs.readFileSync(gitignorePath, "utf8");
+  const rules = contents.split(/\r?\n/).map((line) => line.trim());
+  if (rules.includes(rule)) return false;
+
+  const separator = contents.length > 0 && !contents.endsWith("\n") ? "\n" : "";
+  fs.appendFileSync(gitignorePath, `${separator}${rule}\n`);
+  return true;
+}
+
+module.exports = {
+  DEPLOY_WORKFLOW,
+  IMAGE_CACHE_SCHEMA,
+  ensureGitignoreRule,
+  initProject,
+  shouldSaveImageCache,
+};

package/lib/mod/config.js

@@ -19,9 +19,15 @@ const defaults = {
   defaultLanguage: "en",
   defaultLanguageInSubdir: false,
   languages: null,
-  basePath: "",  // auto-detected for GitHub Pages project sites, e.g. "/repo-name/"
-  postsPath: "posts",  // URL prefix for posts: "posts" serves articles at /posts/<slug>/; set "" for root
-  comments: null,  // { provider: "utterances", repo: "user/repo", issueTerm: "pathname", theme: "github-light" }
+  basePath: "", // auto-detected for GitHub Pages project sites, e.g. "/repo-name/"
+  postsPath: "posts", // URL prefix for posts: "posts" serves articles at /posts/<slug>/; set "" for root
+  comments: null, // { provider: "utterances", repo: "user/repo", issueTerm: "pathname", theme: "github-light" }
+  imageOptimization: true,
+  imageMaxWidth: 1400,
+  imageMaxWidthOverride: 1200,
+  imageWebP: true,
+  imageResponsiveWidths: [600, 800, 1000],
+  cacheDir: "./.fossbook-cache",
   content: "./content",
   postsDir: "./content/posts",
   outputDir: "./public",
@@ -44,7 +50,9 @@ function resolveThemePath(config) {
   if (fs.existsSync(builtinThemePath)) {
     return builtinThemePath;
   }
-  console.error(`Theme "${themeName}" not found in ${userThemePath} or ${builtinThemePath}`);
+  console.error(
+    `Theme "${themeName}" not found in ${userThemePath} or ${builtinThemePath}`,
+  );
   process.exit(1);
 }
 
@@ -76,6 +84,7 @@ function loadConfig(configPath) {
     content: path.resolve(merged.content),
     about: path.resolve(merged.content, "about.md"),
     outdir: path.resolve(merged.outputDir),
+    cacheDir: path.resolve(merged.cacheDir),
     themePath: path.dirname(themePath), // e.g. /path/to/themes
     staticDir: path.resolve(merged.staticDir),
   };
@@ -105,23 +114,36 @@ function loadConfig(configPath) {
 
 function createLanguageConfigs(config, configPath) {
   const configuredLanguages = config.languages;
-  const hasMultipleLanguages = configuredLanguages !== null && configuredLanguages !== undefined;
+  const hasMultipleLanguages =
+    configuredLanguages !== null && configuredLanguages !== undefined;
   const languages = hasMultipleLanguages
     ? configuredLanguages
     : { [config.defaultLanguage]: {} };
 
-  if (typeof languages !== "object" || Array.isArray(languages) || Object.keys(languages).length === 0) {
+  if (
+    typeof languages !== "object" ||
+    Array.isArray(languages) ||
+    Object.keys(languages).length === 0
+  ) {
     throw new Error("languages must be a non-empty object");
   }
-  if (!Object.prototype.hasOwnProperty.call(languages, config.defaultLanguage)) {
-    throw new Error(`defaultLanguage "${config.defaultLanguage}" is not defined in languages`);
+  if (
+    !Object.prototype.hasOwnProperty.call(languages, config.defaultLanguage)
+  ) {
+    throw new Error(
+      `defaultLanguage "${config.defaultLanguage}" is not defined in languages`,
+    );
   }
 
   return Object.entries(languages).map(([language, overrides]) => {
     if (!/^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/.test(language)) {
       throw new Error(`Invalid language key "${language}"`);
     }
-    if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) {
+    if (
+      !overrides ||
+      typeof overrides !== "object" ||
+      Array.isArray(overrides)
+    ) {
       throw new Error(`languages.${language} must be an object`);
     }
 
@@ -129,7 +151,8 @@ function createLanguageConfigs(config, configPath) {
       ? loadLanguageConfig(configPath, language)
       : {};
 
-    const useSubdirectory = config.defaultLanguageInSubdir || language !== config.defaultLanguage;
+    const useSubdirectory =
+      config.defaultLanguageInSubdir || language !== config.defaultLanguage;
     const languagePrefix = useSubdirectory ? language : "";
     const basePath = appendPathSegment(config.basePath, languagePrefix);
     const blogsite = appendUrlSegment(config.blogsite, languagePrefix);
@@ -141,7 +164,8 @@ function createLanguageConfigs(config, configPath) {
       defaultLanguage: config.defaultLanguage,
       defaultLanguageInSubdir: config.defaultLanguageInSubdir,
       language,
-      languageName: fileOverrides.languageName || overrides.languageName || language,
+      languageName:
+        fileOverrides.languageName || overrides.languageName || language,
       locale: fileOverrides.locale || overrides.locale || language,
       languagePrefix,
       basePath,
@@ -166,8 +190,14 @@ function loadLanguageConfig(configPath, language) {
   if (!fs.existsSync(languageConfigPath)) return {};
 
   const languageConfig = require(languageConfigPath);
-  if (!languageConfig || typeof languageConfig !== "object" || Array.isArray(languageConfig)) {
-    throw new Error(`${path.basename(languageConfigPath)} must export an object`);
+  if (
+    !languageConfig ||
+    typeof languageConfig !== "object" ||
+    Array.isArray(languageConfig)
+  ) {
+    throw new Error(
+      `${path.basename(languageConfigPath)} must export an object`,
+    );
   }
   return languageConfig;
 }