feat: og-images: Implement caching for OG image generation

This commit introduces caching to the OG image generation process to improve build times. It uses hashes of content and assets to determine when to regenerate images, skipping unchanged ones. Stale images are also removed.

Author: neural-loop

.github/workflows/main.yml

@@ -2,7 +2,7 @@ name: Deploy Hugo site to Pages
 
 on:
   push:
-    branches: ["main", "design-adjustments"]
+    branches: ["main", "cache-images"]
 
 permissions:
   contents: read
@@ -17,23 +17,19 @@ env:
 
 jobs:
   build:
-    # Switched to a standard x86_64 runner for better package compatibility
     runs-on: ubuntu-24.04
     steps:
       - name: Install Hugo
         run: |
-          # Updated to use amd64 for the new runner
           wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
           && sudo dpkg -i ${{ runner.temp }}/hugo.deb
 
       - name: Install Go
         run: |
-          # Updated to use amd64 for the new runner
           wget -O ${{ runner.temp }}/go.tar.gz https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz \
           && sudo tar -C /usr/local -xzf ${{ runner.temp }}/go.tar.gz \
           && sudo ln -s /usr/local/go/bin/go /usr/local/bin/go
 
-
       - name: Checkout
         uses: actions/checkout@v4.2.2
         with:
@@ -44,15 +40,29 @@ jobs:
         id: pages
         uses: actions/configure-pages@v5
 
-      # Best practice: Use setup-node with caching
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: ${{ env.NODE_VERSION }}
           cache: 'npm'
 
       - name: Install npm dependencies
-        run: npm ci # Use npm ci for faster, more reliable CI builds
+        run: npm ci
+
+      - name: Cache and Restore OG Images
+        uses: actions/cache@v4
+        id: og-cache
+        with:
+          path: |
+            content/**/*-og.jpg
+            static/images/og-image.jpg
+            tmp/og-cache-manifest.json
+          key: ${{ runner.os }}-og-images-${{ hashFiles('**/content/**/index.md', '**/content/**/_index.md', 'assets/og-template/template.html', 'assets/images/ONM-logo.png') }}
+          restore-keys: |
+            ${{ runner.os }}-og-images-
+
+      - name: Generate OG Images
+        run: npm run og-images
 
       - name: Determine Base URL
         id: base_url
@@ -63,7 +73,6 @@ jobs:
             BASE_URL="https://open-neuromorphic.github.io/refactor-preview/" # Example preview URL
           else
             REPO_NAME=$(echo "${{ github.repository }}" | cut -d '/' -f 2)
-            # For forks or other repositories, adjust as needed
             BASE_URL="https://${{ github.repository_owner }}.github.io/${REPO_NAME}/"
           fi
           echo "BASE_URL=$BASE_URL" >> $GITHUB_ENV
@@ -75,12 +84,12 @@ jobs:
           sed -i "s|baseURL = .*|baseURL = \"$BASE_URL\"|" hugo.toml
           echo "hugo.toml after modification:"
           cat hugo.toml
-
-      - name: Build site
+      
+      - name: Build Hugo Site
         run: |
-          echo "Starting site build..."
-          npm run build
-          echo "Site build completed."
+          echo "Starting Hugo site build..."
+          npm run hugo-build
+          echo "Hugo site build completed."
           echo "Contents of public directory after build:"
           ls -la public
 
@@ -132,7 +141,6 @@ jobs:
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    # Switched to a standard x86_64 runner for consistency
     runs-on: ubuntu-24.04
     needs: build
     steps:

.gitignore

@@ -20,3 +20,8 @@ yarn.lock
 /tmp/ogImageData.json
 /tmp/output_full.txt
 /tmp/
+
+# Ignore generated OG images and cache files
+content/**/*-og.jpg
+static/images/og-image.jpg
+tmp/og-cache-manifest.json

package.json

@@ -6,7 +6,8 @@
   "author": "VisionInit.dev",
   "scripts": {
     "dev": "hugo serve --buildFuture",
-    "build": "npm run og-images && rm public -fr && hugo --gc --minify --buildFuture --templateMetrics --templateMetricsHints --forceSyncStatic -e production",
+    "hugo-build": "hugo --gc --minify --buildFuture --templateMetrics --templateMetricsHints --forceSyncStatic -e production",
+    "build": "npm run og-images && npm run hugo-build",
     "build-preview": "hugo server --disableFastRender --buildFuture --navigateToChanged --templateMetrics --templateMetricsHints  --forceSyncStatic -e production --minify",
     "og-images": "node scripts/collectOgData.js && node scripts/generateOgImages.js"
   },

scripts/collectOgData.js

@@ -2,6 +2,7 @@
 const { join, dirname, basename } = require('path');
 const { readdir, readFile, stat, mkdir, writeFile } = require('fs/promises');
 const mimeTypes = require('mime-types');
+const crypto = require('crypto');
 
 // --- Configuration ---
 const PROJECT_ROOT = process.cwd();
@@ -12,7 +13,8 @@ const TMP_DIR = join(PROJECT_ROOT, 'tmp');
 const OUTPUT_JSON_PATH = join(TMP_DIR, 'ogImageData.json');
 const OUTPUT_FORMAT = 'jpg';
 const LOGO_PATH_IN_ASSETS = 'images/ONM-logo.png';
-const BACKGROUND_IMAGE_PATH_IN_ASSETS = 'images/ONM.png'; // Added this line
+const BACKGROUND_IMAGE_PATH_IN_ASSETS = 'images/ONM.png';
+const OG_TEMPLATE_PATH = join(PROJECT_ROOT, 'assets', 'og-template', 'template.html');
 const HOMEPAGE_TITLE = "Advancing Neuromorphic Computing, Together.";
 const HOMEPAGE_DESCRIPTION = "Open Neuromorphic (ONM) is a global community fostering education, research, and open-source collaboration in brain-inspired AI and hardware.";
 
@@ -30,6 +32,10 @@ async function ensureDir(dirPath) {
   catch (err) { if (err.code !== 'EEXIST') throw err; }
 }
 
+function createHash(data) {
+    return crypto.createHash('sha256').update(data).digest('hex');
+}
+
 async function findMarkdownFiles(dir) {
   let entries;
   try { entries = await readdir(dir); } catch (err) { console.warn(`Could not read directory ${dir}: ${err.message}`); return []; }
@@ -83,37 +89,41 @@ async function getImageDataUri(filePath) {
 
 // --- Main Script ---
 async function collectData() {
-  console.log('📊 Collecting OG image data...');
+  console.log('📊 Collecting OG image data and calculating hashes...');
   await ensureDir(TMP_DIR);
 
+  const templateBuffer = await readFile(OG_TEMPLATE_PATH);
+  const logoBuffer = await readFile(join(ASSETS_DIR, LOGO_PATH_IN_ASSETS));
+  const backgroundBuffer = await readFile(join(ASSETS_DIR, BACKGROUND_IMAGE_PATH_IN_ASSETS));
+  const globalHash = createHash(Buffer.concat([templateBuffer, logoBuffer, backgroundBuffer]));
+
   const absoluteLogoPath = join(ASSETS_DIR, LOGO_PATH_IN_ASSETS);
   const logoDataUri = await getImageDataUri(absoluteLogoPath);
   if (!logoDataUri) {
     console.error(`❌ Critical: Could not load logo from ${absoluteLogoPath}. Cannot proceed.`);
     process.exit(1);
   }
 
-  // --- Add logic for background image ---
   const absoluteBackgroundPath = join(ASSETS_DIR, BACKGROUND_IMAGE_PATH_IN_ASSETS);
   const backgroundDataUri = await getImageDataUri(absoluteBackgroundPath);
-  if (!backgroundDataUri) {
-      console.warn(`⚠️ Background image not found at ${absoluteBackgroundPath}, will proceed without it.`);
-  }
 
   const outputData = {
+    globalHash,
     logoDataUri,
-    backgroundDataUri: backgroundDataUri || '', // Add background URI
+    backgroundDataUri: backgroundDataUri || '',
     pages: [],
   };
 
   // 1. Add Homepage Data
+  const homepageContentHash = createHash(HOMEPAGE_TITLE + HOMEPAGE_DESCRIPTION);
+  const homepageFinalHash = createHash(homepageContentHash + globalHash);
   const homepageOgDir = join(STATIC_DIR, 'images');
   await ensureDir(homepageOgDir);
   outputData.pages.push({
     title: HOMEPAGE_TITLE,
     description: HOMEPAGE_DESCRIPTION,
     outputPath: join(homepageOgDir, `og-image.${OUTPUT_FORMAT}`),
-    tempHtmlPath: join(TMP_DIR, `homepage-temp-og.html`),
+    finalHash: homepageFinalHash
   });
 
   // 2. Process Content Pages
@@ -128,14 +138,17 @@ async function collectData() {
         continue;
       }
 
+      const contentHash = createHash(title + description);
+      const finalHash = createHash(contentHash + globalHash);
+
       const parentDirName = basename(pageDirectory);
       const ogImageFilename = `${parentDirName}-og.${OUTPUT_FORMAT}`;
 
       outputData.pages.push({
         title,
         description,
         outputPath: join(pageDirectory, ogImageFilename),
-        tempHtmlPath: join(TMP_DIR, `${parentDirName}-${Date.now()}-temp-og.html`),
+        finalHash
       });
     } catch (err) {
       console.error(`❌ Error processing ${mdFile}: ${err.message}`);

scripts/generateOgImages.js

@@ -1,3 +1,4 @@
+// scripts/generateOgImages.js
 const puppeteer = require('puppeteer');
 const { join } = require('path');
 const { readFile, writeFile, unlink, stat } = require('fs/promises');
@@ -7,14 +8,15 @@ const PROJECT_ROOT = process.cwd();
 const TMP_DIR = join(PROJECT_ROOT, 'tmp');
 const TEMPLATE_PATH = join(PROJECT_ROOT, 'assets', 'og-template', 'template.html');
 const INPUT_JSON_PATH = join(TMP_DIR, 'ogImageData.json');
+const CACHE_MANIFEST_PATH = join(TMP_DIR, 'og-cache-manifest.json');
 const JPEG_QUALITY = 90;
 
 async function pathExists(path) {
   try { await stat(path); return true; } catch { return false; }
 }
 
 async function generateImages() {
-  console.log('🖼️  Starting OG Image Generation with Puppeteer...');
+  console.log('🖼️  Starting OG Image Generation with Caching...');
 
   // --- Pre-flight checks ---
   if (!(await pathExists(INPUT_JSON_PATH))) {
@@ -24,9 +26,18 @@ async function generateImages() {
     throw new Error(`❌ OG template not found: ${TEMPLATE_PATH}`);
   }
 
-  // --- Read data and template ---
+  // --- Read data, template, and cache manifest ---
   const templateContent = await readFile(TEMPLATE_PATH, 'utf8');
   const jsonData = JSON.parse(await readFile(INPUT_JSON_PATH, 'utf8'));
+  
+  let oldCache = {};
+  try {
+    oldCache = JSON.parse(await readFile(CACHE_MANIFEST_PATH, 'utf8'));
+  } catch (e) {
+    console.log('ℹ️ No existing cache manifest found. Will generate all images.');
+  }
+  
+  const newCache = {};
 
   if (!jsonData || !jsonData.pages || jsonData.pages.length === 0) {
     console.warn('⚠️ No pages to process.');
@@ -41,16 +52,25 @@ async function generateImages() {
 
   let successCount = 0;
   let errorCount = 0;
+  let skippedCount = 0;
 
   // --- Process each page ---
   for (const pageData of jsonData.pages) {
-    const { title, description, outputPath } = pageData;
+    const { title, description, outputPath, finalHash } = pageData;
 
     try {
+      const fileAlreadyExists = await pathExists(outputPath);
+      const isCacheValid = oldCache[outputPath] === finalHash;
+
+      if (fileAlreadyExists && isCacheValid) {
+        skippedCount++;
+        newCache[outputPath] = finalHash; // Keep valid entry in new cache
+        continue;
+      }
+      
       const page = await browser.newPage();
       await page.setViewport({ width: 1200, height: 630 });
 
-      // Populate the template with page data
       const htmlContent = templateContent
         .replace('LOGO_SRC', jsonData.logoDataUri)
         .replace('BACKGROUND_URL', jsonData.backgroundDataUri || '')
@@ -59,7 +79,6 @@ async function generateImages() {
 
       await page.setContent(htmlContent, { waitUntil: 'networkidle0' });
 
-      // Take the screenshot
       await page.screenshot({
         path: outputPath,
         type: 'jpeg',
@@ -69,6 +88,7 @@ async function generateImages() {
       const stats = await stat(outputPath);
       console.log(`✅ Generated: ${outputPath.replace(PROJECT_ROOT, '')} (${(stats.size / 1024).toFixed(1)} KB)`);
       successCount++;
+      newCache[outputPath] = finalHash; // Add new entry to cache
 
       await page.close();
     } catch (err) {
@@ -77,9 +97,28 @@ async function generateImages() {
       errorCount++;
     }
   }
-
+  
   await browser.close();
-  console.log(`\n✨ Generation complete! Succeeded: ${successCount}, Failed: ${errorCount}.`);
+
+  // --- Cleanup stale images and cache entries ---
+  const validOutputPaths = new Set(jsonData.pages.map(p => p.outputPath));
+  let cleanedCount = 0;
+  for (const oldPath in oldCache) {
+    if (!validOutputPaths.has(oldPath)) {
+      if (await pathExists(oldPath)) {
+        await unlink(oldPath);
+        cleanedCount++;
+      }
+    }
+  }
+  if (cleanedCount > 0) {
+      console.log(`🗑️  Cleaned up ${cleanedCount} stale OG image(s).`);
+  }
+
+  // --- Write the new cache manifest ---
+  await writeFile(CACHE_MANIFEST_PATH, JSON.stringify(newCache, null, 2));
+
+  console.log(`\n✨ Generation complete! Succeeded: ${successCount}, Skipped: ${skippedCount}, Failed: ${errorCount}.`);
   if (errorCount > 0) process.exit(1);
 }