@kenjura/ursa 0.52.0 → 0.54.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+# 0.54.0
+2025-12-21
+
+- added cache-busting timestamps to static files
+- cleaned up generate.js by moving helper functions to separate files
+
+
+# 0.53.0
+2025-12-21
+
+### Menu Size Optimization
+- **External Menu JSON**: Menu data is now stored in `/public/menu-data.json` instead of being embedded in every HTML file. This dramatically reduces HTML file sizes for sites with large folder structures (e.g., from 2-3MB per file down to ~50KB).
+- **Async Menu Loading**: Menu data is fetched asynchronously after page render, showing a "Loading menu..." indicator until ready.
+- **Debug Fields Removed**: Menu JSON no longer includes debug/inactive fields, reducing JSON size further.
+- **Gzip Compression**: Development server now uses gzip compression for all responses, significantly reducing transfer size for JSON and HTML files.
+
 # 0.52.0
 2025-12-21
 

package/meta/menu.js

@@ -2,19 +2,12 @@ document.addEventListener('DOMContentLoaded', () => {
     const navMain = document.querySelector('nav#nav-main');
     if (!navMain) return;
 
-    // Load menu data from embedded JSON
-    const menuDataScript = document.getElementById('menu-data');
-    if (!menuDataScript) return;
+    // State - menu data will be loaded asynchronously
+    let menuData = null;
+    let menuDataLoaded = false;
+    let menuDataLoading = false;
     
-    let menuData;
-    try {
-        menuData = JSON.parse(menuDataScript.textContent);
-    } catch (e) {
-        console.error('Failed to parse menu data:', e);
-        return;
-    }
-
-    // Load menu config from embedded JSON (contains openMenuItems)
+    // Load menu config from embedded JSON (contains openMenuItems) - this is small, so it's embedded
     const menuConfigScript = document.getElementById('menu-config');
     let menuConfig = { openMenuItems: [] };
     if (menuConfigScript) {
@@ -39,9 +32,39 @@ document.addEventListener('DOMContentLoaded', () => {
 
     // Helper to check if we're on mobile
     const isMobile = () => window.matchMedia('(max-width: 800px)').matches;
+    
+    /**
+     * Load menu data from external JSON file
+     * This is done asynchronously to avoid blocking page render
+     */
+    async function loadMenuData() {
+        if (menuDataLoaded || menuDataLoading) return;
+        menuDataLoading = true;
+        
+        try {
+            const response = await fetch('/public/menu-data.json');
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            menuData = await response.json();
+            menuDataLoaded = true;
+            
+            // Re-render menu now that we have full data
+            initializeFromCurrentPage();
+        } catch (error) {
+            console.error('Failed to load menu data:', error);
+            menuDataLoaded = true; // Mark as loaded to prevent retries
+        } finally {
+            menuDataLoading = false;
+        }
+    }
+    
+    // Start loading menu data immediately
+    loadMenuData();
 
     // Get items at a specific path
     function getItemsAtPath(path) {
+        if (!menuData) return [];
         let items = menuData;
         for (const segment of path) {
             const folder = items.find(item => item.path === (path.slice(0, path.indexOf(segment) + 1).join('/') || segment));
@@ -56,6 +79,7 @@ document.addEventListener('DOMContentLoaded', () => {
 
     // Find item by path
     function findItemByPath(pathString) {
+        if (!menuData) return null;
         const segments = pathString.split('/').filter(Boolean);
         let items = menuData;
         let item = null;
@@ -98,6 +122,12 @@ document.addEventListener('DOMContentLoaded', () => {
 
     // Render menu at current path
     function renderMenu() {
+        // Wait for menu data to load
+        if (!menuData) {
+            menuContainer.innerHTML = '<li class="menu-loading">Loading menu...</li>';
+            return;
+        }
+        
         // Get items for current level (level 1)
         let level1Items;
         if (currentPath.length === 0) {
@@ -421,5 +451,6 @@ document.addEventListener('DOMContentLoaded', () => {
         renderMenu();
     }
 
-    initializeFromCurrentPage();
+    // Initial render shows loading state, then loadMenuData() will call initializeFromCurrentPage() when ready
+    renderMenu();
 });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {
@@ -24,6 +24,7 @@
     "url": "git+https://github.com/kenjura/ursa.git"
   },
   "dependencies": {
+    "compression": "^1.7.4",
     "directory-tree": "^3.3.2",
     "express": "^4.18.2",
     "fs-extra": "^10.1.0",

package/src/helper/automenu.js

@@ -132,7 +132,8 @@ function resolveHref(rawHref, validPaths) {
 }
 
 // Build a flat tree structure with path info for JS navigation
-function buildMenuData(tree, source, validPaths, parentPath = '') {
+// Set includeDebug=false to exclude debug fields and reduce JSON size
+function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug = true) {
   const items = [];
   
   // Files to hide from menu by default
@@ -192,14 +193,21 @@ function buildMenuData(tree, source, validPaths, parentPath = '') {
       label,
       path: folderPath,
       href,
-      inactive,
-      debug,
       hasChildren,
       icon,
     };
     
+    // Only include debug and inactive fields if requested (for smaller JSON)
+    if (includeDebug) {
+      menuItem.inactive = inactive;
+      menuItem.debug = debug;
+    } else if (inactive) {
+      // Only include inactive if true (to save space)
+      menuItem.inactive = true;
+    }
+    
     if (hasChildren) {
-      menuItem.children = buildMenuData(item, source, validPaths, folderPath);
+      menuItem.children = buildMenuData(item, source, validPaths, folderPath, includeDebug);
     }
     
     items.push(menuItem);
@@ -218,7 +226,9 @@ export async function getAutomenu(source, validPaths) {
   const tree = dirTree(source, {
     exclude: /[\/\\]\.|node_modules/,  // Exclude hidden folders (starting with .) and node_modules
   });
-  const menuData = buildMenuData(tree, source, validPaths);
+  
+  // Build menu data WITHOUT debug fields for smaller JSON
+  const menuData = buildMenuData(tree, source, validPaths, '', false);
   
   // Get root config for openMenuItems setting
   const rootConfig = getRootConfig(source);
@@ -227,14 +237,11 @@ export async function getAutomenu(source, validPaths) {
   // Add home item with resolved href
   const homeResolved = resolveHref('/', validPaths);
   const fullMenuData = [
-    { label: 'Home', path: '', href: homeResolved.href, inactive: homeResolved.inactive, debug: homeResolved.debug, hasChildren: false, icon: `<span class="menu-icon">${HOME_ICON}</span>` },
+    { label: 'Home', path: '', href: homeResolved.href, hasChildren: false, icon: `<span class="menu-icon">${HOME_ICON}</span>` },
     ...menuData
   ];
   
-  // Embed the menu data as JSON for JavaScript to use
-  const menuDataScript = `<script type="application/json" id="menu-data">${JSON.stringify(fullMenuData)}</script>`;
-  
-  // Embed the openMenuItems config as separate JSON
+  // Embed the openMenuItems config as JSON (small, safe to embed)
   const menuConfigScript = `<script type="application/json" id="menu-config">${JSON.stringify({ openMenuItems })}</script>`;
   
   // Render the breadcrumb header (hidden by default, shown when navigating)
@@ -245,10 +252,14 @@ export async function getAutomenu(source, validPaths) {
   <span class="menu-current-path"></span>
 </div>`;
 
-  // Render the initial menu (root level)
+  // Render the initial menu (root level only - children loaded from external JSON)
   const menuHtml = renderMenuLevel(fullMenuData, 0);
   
-  return `${menuDataScript}${menuConfigScript}${breadcrumbHtml}<ul class="menu-level" data-level="0">${menuHtml}</ul>`;
+  // Return both the HTML for embedding and the full menu data for the static JSON file
+  return {
+    html: `${menuConfigScript}${breadcrumbHtml}<ul class="menu-level" data-level="0">${menuHtml}</ul>`,
+    menuData: fullMenuData
+  };
 }
 
 function renderMenuLevel(items, level) {

package/src/helper/build/autoIndex.js

@@ -0,0 +1,197 @@
+// Auto-index generation helpers for build
+import { existsSync } from "fs";
+import { readdir, readFile } from "fs/promises";
+import { basename, dirname, extname, join } from "path";
+import { outputFile } from "fs-extra";
+import { findStyleCss } from "../findStyleCss.js";
+import { toTitleCase } from "./titleCase.js";
+import { addTimestampToHtmlStaticRefs } from "./cacheBust.js";
+
+/**
+ * Generate automatic index.html files for folders that don't have one
+ * @param {string} output - Output directory path
+ * @param {string[]} directories - List of source directories
+ * @param {string} source - Source directory path
+ * @param {object} templates - Template map
+ * @param {string} menu - Rendered menu HTML
+ * @param {string} footer - Footer HTML
+ * @param {string[]} generatedArticles - List of source article paths that were generated
+ * @param {Set<string>} copiedCssFiles - Set of CSS files already copied to output
+ * @param {Set<string>} existingHtmlFiles - Set of existing HTML files in source (relative paths)
+ * @param {string} cacheBustTimestamp - Cache-busting timestamp
+ * @param {object} progress - Progress reporter instance
+ */
+export async function generateAutoIndices(output, directories, source, templates, menu, footer, generatedArticles, copiedCssFiles, existingHtmlFiles, cacheBustTimestamp, progress) {
+  // Alternate index file names to look for (in priority order)
+  const INDEX_ALTERNATES = ['_index.html', 'home.html', '_home.html'];
+  
+  // Normalize paths (remove trailing slashes for consistent replacement)
+  const sourceNorm = source.replace(/\/+$/, '');
+  const outputNorm = output.replace(/\/+$/, '');
+  
+  // Build set of directories that already have an index.html from a source index.md/txt/yml
+  const dirsWithSourceIndex = new Set();
+  for (const articlePath of generatedArticles) {
+    const base = basename(articlePath, extname(articlePath));
+    if (base === 'index') {
+      const dir = dirname(articlePath);
+      const outputDir = dir.replace(sourceNorm, outputNorm);
+      dirsWithSourceIndex.add(outputDir);
+    }
+  }
+  
+  // Get all output directories (including root)
+  const outputDirs = new Set([outputNorm]);
+  for (const dir of directories) {
+    // Handle both with and without trailing slash in source
+    const outputDir = dir.replace(sourceNorm, outputNorm);
+    outputDirs.add(outputDir);
+  }
+  
+  let generatedCount = 0;
+  let renamedCount = 0;
+  let skippedHtmlCount = 0;
+  
+  for (const dir of outputDirs) {
+    const indexPath = join(dir, 'index.html');
+    
+    // Skip if this directory had a source index.md/txt/yml that was already processed
+    if (dirsWithSourceIndex.has(dir)) {
+      continue;
+    }
+    
+    // Check if there's an existing index.html in the source directory (don't overwrite it)
+    const sourceDir = dir.replace(outputNorm, sourceNorm);
+    const relativeIndexPath = join(sourceDir, 'index.html').replace(sourceNorm + '/', '');
+    if (existingHtmlFiles && existingHtmlFiles.has(relativeIndexPath)) {
+      skippedHtmlCount++;
+      continue; // Don't overwrite existing source HTML
+    }
+    
+    // Skip if index.html already exists in output (e.g., created by previous run)
+    if (existsSync(indexPath)) {
+      continue;
+    }
+    
+    // Get folder name for (foldername).html check
+    const folderName = basename(dir);
+    const folderNameAlternate = `${folderName}.html`;
+    
+    // Check for alternate index files
+    let foundAlternate = null;
+    for (const alt of [...INDEX_ALTERNATES, folderNameAlternate]) {
+      const altPath = join(dir, alt);
+      if (existsSync(altPath)) {
+        foundAlternate = altPath;
+        break;
+      }
+    }
+    
+    if (foundAlternate) {
+      // Rename/copy alternate to index.html
+      try {
+        const content = await readFile(foundAlternate, 'utf8');
+        await outputFile(indexPath, content);
+        renamedCount++;
+        progress.status('Auto-index', `Promoted ${basename(foundAlternate)} → index.html in ${dir.replace(outputNorm, '') || '/'}`);
+      } catch (e) {
+        progress.log(`Error promoting ${foundAlternate} to index.html: ${e.message}`);
+      }
+    } else {
+      // Generate a simple index listing direct children
+      try {
+        const children = await readdir(dir, { withFileTypes: true });
+        
+        // Filter to only include relevant files and folders
+        const items = children
+          .filter(child => {
+            // Skip hidden files and index alternates we just checked
+            if (child.name.startsWith('.')) return false;
+            if (child.name === 'index.html') return false;
+            // Include directories and html files
+            return child.isDirectory() || child.name.endsWith('.html');
+          })
+          .map(child => {
+            const isDir = child.isDirectory();
+            const name = isDir ? child.name : child.name.replace('.html', '');
+            const href = isDir ? `${child.name}/` : child.name;
+            const displayName = toTitleCase(name);
+            const icon = isDir ? '📁' : '📄';
+            return `<li>${icon} <a href="${href}">${displayName}</a></li>`;
+          });
+        
+        if (items.length === 0) {
+          // Empty folder, skip generating index
+          continue;
+        }
+        
+        const folderDisplayName = dir === outputNorm ? 'Home' : toTitleCase(folderName);
+        const indexHtml = `<h1>${folderDisplayName}</h1>\n<ul class="auto-index">\n${items.join('\n')}\n</ul>`;
+        
+        const template = templates["default-template"];
+        if (!template) {
+          progress.log(`Warning: No default template for auto-index in ${dir}`);
+          continue;
+        }
+        
+        // Find nearest style.css for this directory
+        let styleLink = "";
+        try {
+          // Map output dir back to source dir to find style.css
+          const sourceDir = dir.replace(outputNorm, sourceNorm);
+          const cssPath = await findStyleCss(sourceDir);
+          if (cssPath) {
+            // Calculate output path for the CSS file (mirrors source structure)
+            const cssOutputPath = cssPath.replace(sourceNorm, outputNorm);
+            const cssUrlPath = '/' + cssPath.replace(sourceNorm, '');
+            
+            // Copy CSS file if not already copied
+            if (!copiedCssFiles.has(cssPath)) {
+              const cssContent = await readFile(cssPath, 'utf8');
+              await outputFile(cssOutputPath, cssContent);
+              copiedCssFiles.add(cssPath);
+            }
+            
+            // Generate link tag
+            styleLink = `<link rel="stylesheet" href="${cssUrlPath}" />`;
+          }
+        } catch (e) {
+          // ignore CSS lookup errors
+        }
+        
+        let finalHtml = template;
+        const replacements = {
+          "${menu}": menu,
+          "${body}": indexHtml,
+          "${searchIndex}": "[]",
+          "${title}": folderDisplayName,
+          "${meta}": "{}",
+          "${transformedMetadata}": "",
+          "${styleLink}": styleLink,
+          "${footer}": footer
+        };
+        for (const [key, value] of Object.entries(replacements)) {
+          finalHtml = finalHtml.replace(key, value);
+        }
+        // Add cache-busting timestamps to static file references
+        finalHtml = addTimestampToHtmlStaticRefs(finalHtml, cacheBustTimestamp);
+        
+        await outputFile(indexPath, finalHtml);
+        generatedCount++;
+        progress.status('Auto-index', `Generated index.html for ${dir.replace(outputNorm, '') || '/'}`);
+      } catch (e) {
+        progress.log(`Error generating auto-index for ${dir}: ${e.message}`);
+      }
+    }
+  }
+  
+  if (generatedCount > 0 || renamedCount > 0 || skippedHtmlCount > 0) {
+    let summary = `${generatedCount} generated, ${renamedCount} promoted`;
+    if (skippedHtmlCount > 0) {
+      summary += `, ${skippedHtmlCount} skipped (existing HTML)`;
+    }
+    progress.done('Auto-index', summary);
+  } else {
+    progress.log(`Auto-index: All folders already have index.html`);
+  }
+}

package/src/helper/build/batch.js

@@ -0,0 +1,19 @@
+// Batch processing helpers for build
+
+/**
+ * Process items in batches to limit memory usage
+ * @param {Array} items - Items to process
+ * @param {Function} processor - Async function to process each item
+ * @param {number} batchSize - Max concurrent operations
+ */
+export async function processBatched(items, processor, batchSize = 50) {
+  const results = [];
+  for (let i = 0; i < items.length; i += batchSize) {
+    const batch = items.slice(i, i + batchSize);
+    const batchResults = await Promise.all(batch.map(processor));
+    results.push(...batchResults);
+    // Allow GC to run between batches
+    if (global.gc) global.gc();
+  }
+  return results;
+}

package/src/helper/build/cacheBust.js

@@ -0,0 +1,62 @@
+// Cache busting helpers for build
+
+/**
+ * Generate a cache-busting timestamp in ISO format (e.g., 20251221T221700Z)
+ * @returns {string} Timestamp string suitable for query params
+ */
+export function generateCacheBustTimestamp() {
+  const now = new Date();
+  const year = now.getUTCFullYear();
+  const month = String(now.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(now.getUTCDate()).padStart(2, '0');
+  const hours = String(now.getUTCHours()).padStart(2, '0');
+  const minutes = String(now.getUTCMinutes()).padStart(2, '0');
+  const seconds = String(now.getUTCSeconds()).padStart(2, '0');
+  return `${year}${month}${day}T${hours}${minutes}${seconds}Z`;
+}
+
+/**
+ * Add cache-busting timestamp to url() references in CSS content
+ * @param {string} cssContent - The CSS file content
+ * @param {string} timestamp - The cache-busting timestamp
+ * @returns {string} CSS with timestamped URLs
+ */
+export function addTimestampToCssUrls(cssContent, timestamp) {
+  // Match url(...) in any context, including CSS variables, with optional whitespace and quotes
+  // Exclude data: URLs and already-timestamped URLs
+  return cssContent.replace(
+    /url\(\s*(['"]?)(?!data:)([^'"\)]+?)\1\s*\)/gi,
+    (match, quote, url) => {
+      // Don't add timestamp if already has query string
+      if (url.includes('?')) {
+        return match;
+      }
+      return `url(${quote}${url}?v=${timestamp}${quote})`;
+    }
+  );
+}
+
+/**
+ * Add cache-busting timestamp to static file references in HTML
+ * @param {string} html - The HTML content
+ * @param {string} timestamp - The cache-busting timestamp
+ * @returns {string} HTML with timestamped static file references
+ */
+export function addTimestampToHtmlStaticRefs(html, timestamp) {
+  // Add timestamp to CSS links
+  html = html.replace(
+    /(<link[^>]+href=["'])([^"']+\.css)(["'][^>]*>)/gi,
+    `$1$2?v=${timestamp}$3`
+  );
+  // Add timestamp to JS scripts
+  html = html.replace(
+    /(<script[^>]+src=["'])([^"']+\.js)(["'][^>]*>)/gi,
+    `$1$2?v=${timestamp}$3`
+  );
+  // Add timestamp to images in img tags
+  html = html.replace(
+    /(<img[^>]+src=["'])([^"']+\.(jpg|jpeg|png|gif|webp|svg|ico))(["'][^>]*>)/gi,
+    `$1$2?v=${timestamp}$4`
+  );
+  return html;
+}

package/src/helper/build/excludeFilter.js

@@ -0,0 +1,67 @@
+// Exclude/filter helpers for build
+import { existsSync } from "fs";
+import { readFile, stat } from "fs/promises";
+
+/**
+ * Parse exclude option - can be comma-separated paths or a file path
+ * @param {string} excludeOption - The exclude option value
+ * @param {string} source - Source directory path
+ * @returns {Promise<Set<string>>} Set of excluded folder paths (normalized)
+ */
+export async function parseExcludeOption(excludeOption, source) {
+  const excludedPaths = new Set();
+  
+  if (!excludeOption) return excludedPaths;
+  
+  // Check if it's a file path (exists as a file)
+  const isFile = existsSync(excludeOption) && (await stat(excludeOption)).isFile();
+  
+  let patterns;
+  if (isFile) {
+    // Read patterns from file (one per line)
+    const content = await readFile(excludeOption, 'utf8');
+    patterns = content.split('\n')
+      .map(line => line.trim())
+      .filter(line => line && !line.startsWith('#')); // Skip empty lines and comments
+  } else {
+    // Treat as comma-separated list
+    patterns = excludeOption.split(',').map(p => p.trim()).filter(Boolean);
+  }
+  
+  // Normalize patterns to absolute paths
+  for (const pattern of patterns) {
+    // Remove leading/trailing slashes and normalize
+    const normalized = pattern.replace(/^\/+|\/+$/g, '');
+    // Store as relative path for easier matching
+    excludedPaths.add(normalized);
+  }
+  
+  return excludedPaths;
+}
+
+/**
+ * Create a filter function that excludes files in specified folders
+ * @param {Set<string>} excludedPaths - Set of excluded folder paths
+ * @param {string} source - Source directory path
+ * @returns {Function} Filter function
+ */
+export function createExcludeFilter(excludedPaths, source) {
+  if (excludedPaths.size === 0) {
+    return () => true; // No exclusions, allow all
+  }
+  
+  return (filePath) => {
+    // Get path relative to source
+    const relativePath = filePath.replace(source, '').replace(/^\/+/, '');
+    
+    // Check if file is in any excluded folder
+    for (const excluded of excludedPaths) {
+      if (relativePath === excluded || 
+          relativePath.startsWith(excluded + '/') ||
+          relativePath.startsWith(excluded + '\\')) {
+        return false; // Exclude this file
+      }
+    }
+    return true; // Include this file
+  };
+}

package/src/helper/build/footer.js

@@ -0,0 +1,113 @@
+// Footer generation helpers for build
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+import { URL } from "url";
+import { renderFile } from "../fileRenderer.js";
+
+/**
+ * Generate footer HTML from footer.md and package.json
+ * @param {string} source - resolved source path with trailing slash
+ * @param {string} _source - original source path
+ * @param {number} buildId - the current build ID
+ * @returns {Promise<string>} Footer HTML
+ */
+export async function getFooter(source, _source, buildId) {
+  const footerParts = [];
+  
+  // Try to read footer.md from source root
+  const footerPath = join(source, 'footer.md');
+  try {
+    if (existsSync(footerPath)) {
+      const footerMd = await readFile(footerPath, 'utf8');
+      const footerHtml = renderFile({ fileContents: footerMd, type: '.md' });
+      footerParts.push(`<div class="footer-content">${footerHtml}</div>`);
+    }
+  } catch (e) {
+    console.error(`Error reading footer.md: ${e.message}`);
+  }
+  
+  // Try to read package.json from doc repo (check both source dir and parent)
+  let docPackage = null;
+  const sourceDir = resolve(_source);
+  const packagePaths = [
+    join(sourceDir, 'package.json'),           // In source dir itself
+    join(sourceDir, '..', 'package.json'),     // One level up (if docs is a subfolder)
+  ];
+  
+  for (const packagePath of packagePaths) {
+    try {
+      if (existsSync(packagePath)) {
+        const packageJson = await readFile(packagePath, 'utf8');
+        docPackage = JSON.parse(packageJson);
+        console.log(`Found doc package.json at ${packagePath}`);
+        break;
+      }
+    } catch (e) {
+      // Continue to next path
+    }
+  }
+  
+  // Get ursa version from ursa's own package.json
+  // Use import.meta.url to find the package.json relative to this file
+  let ursaVersion = 'unknown';
+  try {
+    // From src/helper/build/footer.js, go up to package root
+    const currentFileUrl = new URL(import.meta.url);
+    const currentDir = dirname(currentFileUrl.pathname);
+    const ursaPackagePath = resolve(currentDir, '..', '..', '..', 'package.json');
+    
+    if (existsSync(ursaPackagePath)) {
+      const ursaPackageJson = await readFile(ursaPackagePath, 'utf8');
+      const ursaPackage = JSON.parse(ursaPackageJson);
+      ursaVersion = ursaPackage.version;
+      console.log(`Found ursa package.json at ${ursaPackagePath}, version: ${ursaVersion}`);
+    }
+  } catch (e) {
+    console.error(`Error reading ursa package.json: ${e.message}`);
+  }
+  
+  // Build meta line: version, build id, timestamp, "generated by ursa"
+  const metaParts = [];
+  if (docPackage?.version) {
+    metaParts.push(`v${docPackage.version}`);
+  }
+  metaParts.push(`build ${buildId}`);
+  
+  // Full date/time in a readable format
+  const now = new Date();
+  const timestamp = now.toISOString().replace('T', ' ').replace(/\.\d{3}Z$/, ' UTC');
+  metaParts.push(timestamp);
+  
+  metaParts.push(`Generated by <a href="https://www.npmjs.com/package/@kenjura/ursa">ursa</a> v${ursaVersion}`);
+  
+  footerParts.push(`<div class="footer-meta">${metaParts.join(' • ')}</div>`);
+  
+  // Copyright line from doc package.json
+  if (docPackage?.copyright) {
+    footerParts.push(`<div class="footer-copyright">${docPackage.copyright}</div>`);
+  } else if (docPackage?.author) {
+    const year = new Date().getFullYear();
+    const author = typeof docPackage.author === 'string' ? docPackage.author : docPackage.author.name;
+    if (author) {
+      footerParts.push(`<div class="footer-copyright">© ${year} ${author}</div>`);
+    }
+  }
+  
+  // Try to get git short hash of doc repo (as HTML comment)
+  try {
+    const { execSync } = await import('child_process');
+    const gitHash = execSync('git rev-parse --short HEAD', {
+      cwd: resolve(_source),
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    if (gitHash) {
+      footerParts.push(`<!-- git: ${gitHash} -->`);
+    }
+  } catch (e) {
+    // Not a git repo or git not available - silently skip
+  }
+  
+  return footerParts.join('\n');
+}