@kenjura/ursa 0.53.0 → 0.55.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
+# 0.55.0
+2025-12-21
+
+- custom menus (menu.md|txt) override the automenu when present
+
+# 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-01-01
+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).

package/meta/default.css

@@ -74,16 +74,46 @@ nav#nav-global {
     opacity: 0.7;
   }
 
-  input#global-search {
+  .search-wrapper {
+    position: relative;
     width: var(--article-width);
     max-width: calc(100% - 16px);
+    justify-self: center;
+  }
+  
+  input#global-search {
+    width: 100%;
     height: calc(var(--global-nav-height) - 16px);
     border-radius: 5px;
     background: rgba(0,0,0,0.25);
     color: var(--text-color);
     border-width: 0px;
-    padding: 0 1rem;
-    justify-self: center;
+    padding: 0 2.5rem 0 1rem;
+    box-sizing: border-box;
+  }
+  
+  .search-clear-button {
+    position: absolute;
+    right: 8px;
+    top: 50%;
+    transform: translateY(-50%);
+    background: none;
+    border: none;
+    color: var(--text-color);
+    font-size: 1.25rem;
+    line-height: 1;
+    cursor: pointer;
+    padding: 4px 8px;
+    opacity: 0.6;
+    transition: opacity 0.2s ease;
+  }
+  
+  .search-clear-button:hover {
+    opacity: 1;
+  }
+  
+  .search-clear-button.hidden {
+    display: none;
   }
 
   .avatar {
@@ -152,10 +182,10 @@ nav#nav-global {
 
 nav#nav-main {
   position: fixed;
-  top: calc(var(--global-nav-height) + 0.5rem);
+  top: calc(var(--global-nav-height));
   left: 0;
   width: 260px;
-  max-height: calc(100vh - var(--global-nav-height) - 1rem);
+  max-height: calc(100vh - var(--global-nav-height));
   overflow-y: auto;
   padding: 0.5rem 0;
   font-size: 0.9rem;
@@ -379,12 +409,13 @@ nav#nav-main {
 /* Table of Contents - Right side navigation */
 nav#nav-toc {
   position: fixed;
-  top: calc(var(--global-nav-height) + 1rem);
-  right: 1rem;
+  top: calc(var(--global-nav-height));
+  right: 0;
   max-width: calc(50vw - var(--article-width) / 2 - 2rem);
-  max-height: calc(100vh - var(--global-nav-height) - 2rem);
+  max-height: calc(100vh - var(--global-nav-height));
   overflow-y: auto;
   z-index: 100;
+  padding: 0.5rem 0;
 
   ul {
     list-style: none;
@@ -481,12 +512,16 @@ footer#site-footer {
   nav#nav-global {
     display: flex;
     
-    input#global-search {
+    .search-wrapper {
       flex: 1;
       width: auto;
       max-width: none;
       margin: 0 8px;
     }
+    
+    input#global-search {
+      width: 100%;
+    }
   }
   article#main-content {
     width: calc(100vw - 2rem);

package/meta/menu.js

@@ -2,6 +2,10 @@ document.addEventListener('DOMContentLoaded', () => {
     const navMain = document.querySelector('nav#nav-main');
     if (!navMain) return;
 
+    // Check for custom menu
+    const customMenuPath = document.body.dataset.customMenu;
+    const isCustomMenu = !!customMenuPath;
+
     // State - menu data will be loaded asynchronously
     let menuData = null;
     let menuDataLoaded = false;
@@ -36,13 +40,16 @@ document.addEventListener('DOMContentLoaded', () => {
     /**
      * Load menu data from external JSON file
      * This is done asynchronously to avoid blocking page render
+     * Will load custom menu if data-custom-menu is present, otherwise loads auto-menu
      */
     async function loadMenuData() {
         if (menuDataLoaded || menuDataLoading) return;
         menuDataLoading = true;
         
         try {
-            const response = await fetch('/public/menu-data.json');
+            // Use custom menu path if present, otherwise use auto-menu
+            const menuUrl = customMenuPath || '/public/menu-data.json';
+            const response = await fetch(menuUrl);
             if (!response.ok) {
                 throw new Error(`HTTP ${response.status}`);
             }
@@ -50,7 +57,11 @@ document.addEventListener('DOMContentLoaded', () => {
             menuDataLoaded = true;
             
             // Re-render menu now that we have full data
-            initializeFromCurrentPage();
+            if (isCustomMenu) {
+                renderCustomMenu();
+            } else {
+                initializeFromCurrentPage();
+            }
         } catch (error) {
             console.error('Failed to load menu data:', error);
             menuDataLoaded = true; // Mark as loaded to prevent retries
@@ -231,6 +242,230 @@ document.addEventListener('DOMContentLoaded', () => {
         attachClickHandlers();
     }
 
+    /**
+     * Get the custom menu root folder name and parent URL from the current location
+     * @returns {{name: string, parentUrl: string}} - Menu root name and parent URL
+     */
+    function getCustomMenuInfo() {
+        const pathname = window.location.pathname;
+        // Remove the filename to get the directory
+        const pathParts = pathname.split('/').filter(Boolean);
+        
+        // Find the menu root by looking at the custom menu path
+        // e.g., /public/custom-menu-systems-system6.json -> systems/system6
+        if (customMenuPath) {
+            const match = customMenuPath.match(/custom-menu-(.+)\.json$/);
+            if (match) {
+                const menuId = match[1];
+                // Convert dashes back to path (e.g., systems-system6 -> systems/system6)
+                // But we need to be careful - the ID uses dashes for path separators
+                // The actual menu root is the folder containing the menu file
+                // We can infer it from the current URL path
+                
+                // Find common prefix between current path and menu ID
+                const menuParts = menuId.split('-');
+                let matchedParts = [];
+                let currentIndex = 0;
+                
+                for (let i = 0; i < pathParts.length && currentIndex < menuParts.length; i++) {
+                    // Check if this path part matches the next menu ID parts
+                    let pathPart = pathParts[i].toLowerCase();
+                    let menuPart = menuParts[currentIndex].toLowerCase();
+                    
+                    // Handle multi-word folder names (e.g., "Galactic Horizons" -> "GalacticHorizons")
+                    if (pathPart.replace(/\s+/g, '').toLowerCase() === menuPart.toLowerCase()) {
+                        matchedParts.push(pathParts[i]);
+                        currentIndex++;
+                    } else if (pathPart === menuPart) {
+                        matchedParts.push(pathParts[i]);
+                        currentIndex++;
+                    }
+                }
+                
+                if (matchedParts.length > 0) {
+                    const menuRootName = matchedParts[matchedParts.length - 1];
+                    // Parent URL is one level up from the menu root
+                    const parentParts = matchedParts.slice(0, -1);
+                    const parentUrl = parentParts.length > 0 
+                        ? '/' + parentParts.join('/') + '/index.html'
+                        : '/index.html';
+                    
+                    return { name: menuRootName, parentUrl };
+                }
+            }
+        }
+        
+        // Fallback: use the first directory in the current path
+        if (pathParts.length > 0) {
+            return { 
+                name: pathParts[0], 
+                parentUrl: '/index.html' 
+            };
+        }
+        
+        return { name: 'Menu', parentUrl: '/index.html' };
+    }
+
+    /**
+     * Render custom menu with two-level display
+     * Custom menus use a simpler structure but same visual style
+     */
+    function renderCustomMenu() {
+        // Wait for menu data to load
+        if (!menuData) {
+            menuContainer.innerHTML = '<li class="menu-loading">Loading menu...</li>';
+            return;
+        }
+
+        // Show breadcrumb for custom menus with menu root name and back button
+        if (breadcrumb) {
+            const menuInfo = getCustomMenuInfo();
+            breadcrumb.style.display = 'flex';
+            if (currentPathSpan) {
+                currentPathSpan.textContent = menuInfo.name;
+            }
+            // Update back button to navigate to parent
+            if (backButton) {
+                backButton.onclick = (e) => {
+                    e.preventDefault();
+                    window.location.href = menuInfo.parentUrl;
+                };
+            }
+            // Hide home button for custom menus (back is enough)
+            if (homeButton) {
+                homeButton.style.display = 'none';
+            }
+        }
+
+        // Build HTML for level 1 and level 2 (max 2 levels shown)
+        let html = '';
+        for (const item of menuData) {
+            const isActive = isCurrentPage(item);
+            const activeClass = isActive ? ' current-menu-item' : '';
+            const hasChildrenClass = item.hasChildren ? ' has-children' : '';
+            
+            // Auto-expand items that contain the current page
+            const containsCurrentPage = item.hasChildren && isCurrentPageInSubtree(item);
+            const isExpanded = expandedLevel1.has(item.path) || (containsCurrentPage && !collapsedLevel1.has(item.path));
+            const expandedClass = isExpanded ? ' expanded' : '';
+            const caretIndicator = item.hasChildren 
+                ? `<span class="menu-caret">${isExpanded ? '▼' : '▶'}</span>` 
+                : '';
+            
+            const labelHtml = item.href
+                ? `<a href="${item.href}" class="menu-label">${item.label}</a>`
+                : `<span class="menu-label">${item.label}</span>`;
+
+            html += `
+<li class="menu-item level-1${hasChildrenClass}${activeClass}${expandedClass}" data-path="${item.path}">
+  <div class="menu-item-row">
+    ${item.icon || '<span class="menu-icon">📄</span>'}
+    ${labelHtml}
+    ${caretIndicator}
+  </div>`;
+
+            // Show children if expanded
+            if (item.children && item.children.length > 0 && isExpanded) {
+                html += '<ul class="menu-sublevel">';
+                for (const child of item.children) {
+                    const childActive = isCurrentPage(child);
+                    const childActiveClass = childActive ? ' current-menu-item' : '';
+                    const childHasChildren = child.hasChildren ? ' has-children' : '';
+                    // Level-2 items with children get triple-dot indicator
+                    const childMoreIndicator = child.hasChildren ? '<span class="menu-more" title="Has sub-items">⋮</span>' : '';
+                    
+                    const childLabelHtml = child.href
+                        ? `<a href="${child.href}" class="menu-label">${child.label}</a>`
+                        : `<span class="menu-label">${child.label}</span>`;
+
+                    html += `
+  <li class="menu-item level-2${childHasChildren}${childActiveClass}" data-path="${child.path}">
+    <div class="menu-item-row">
+      ${child.icon || '<span class="menu-icon">📄</span>'}
+      ${childLabelHtml}
+      ${childMoreIndicator}
+    </div>
+  </li>`;
+                }
+                html += '</ul>';
+            }
+
+            html += '</li>';
+        }
+
+        menuContainer.innerHTML = html;
+
+        // Attach click handlers for custom menu
+        attachCustomMenuClickHandlers();
+    }
+
+    /**
+     * Check if current page is within an item's subtree (for custom menus)
+     */
+    function isCurrentPageInSubtree(item) {
+        if (isCurrentPage(item)) return true;
+        if (item.children) {
+            for (const child of item.children) {
+                if (isCurrentPageInSubtree(child)) return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Attach click handlers for custom menu items
+     */
+    function attachCustomMenuClickHandlers() {
+        const menuItems = menuContainer.querySelectorAll('.menu-item.level-1.has-children');
+        menuItems.forEach(li => {
+            const row = li.querySelector('.menu-item-row');
+            const caret = li.querySelector('.menu-caret');
+            const link = li.querySelector('a.menu-label');
+            const path = li.dataset.path;
+            
+            const toggleExpand = (e) => {
+                e.preventDefault();
+                e.stopPropagation();
+                
+                const isCurrentlyExpanded = li.classList.contains('expanded');
+                
+                if (isCurrentlyExpanded) {
+                    expandedLevel1.delete(path);
+                    collapsedLevel1.add(path);
+                } else {
+                    expandedLevel1.add(path);
+                    collapsedLevel1.delete(path);
+                }
+                renderCustomMenu();
+            };
+            
+            if (caret) {
+                caret.addEventListener('click', toggleExpand);
+            }
+            
+            // If clicking the link on current page, toggle instead of navigate
+            if (link) {
+                link.addEventListener('click', (e) => {
+                    const linkHref = link.getAttribute('href');
+                    const currentHref = window.location.pathname;
+                    const normalizedLinkHref = linkHref.replace(/\/index\.html$/, '').replace(/\.html$/, '');
+                    const normalizedCurrentHref = currentHref.replace(/\/index\.html$/, '').replace(/\.html$/, '');
+                    
+                    if (normalizedLinkHref === normalizedCurrentHref) {
+                        toggleExpand(e);
+                    }
+                });
+            }
+            
+            // Clicking row (not link) toggles
+            row.addEventListener('click', (e) => {
+                if (!e.target.closest('a')) {
+                    toggleExpand(e);
+                }
+            });
+        });
+    }
+
     // Check if an item matches the current page
     function isCurrentPage(item) {
         if (!item.href) return false;

package/meta/search.js

@@ -18,12 +18,31 @@ class GlobalSearch {
   }
   
   init() {
+    this.wrapSearchInput();
     this.createResultsContainer();
+    this.createClearButton();
     this.bindEvents();
     // Start loading the index immediately (but don't block)
     this.loadSearchIndex();
   }
   
+  wrapSearchInput() {
+    // Wrap the search input in a container for positioning the clear button
+    this.searchWrapper = document.createElement('div');
+    this.searchWrapper.className = 'search-wrapper';
+    this.searchInput.parentNode.insertBefore(this.searchWrapper, this.searchInput);
+    this.searchWrapper.appendChild(this.searchInput);
+  }
+  
+  createClearButton() {
+    this.clearButton = document.createElement('button');
+    this.clearButton.className = 'search-clear-button hidden';
+    this.clearButton.type = 'button';
+    this.clearButton.setAttribute('aria-label', 'Clear search');
+    this.clearButton.innerHTML = '×';
+    this.searchWrapper.appendChild(this.clearButton);
+  }
+  
   createResultsContainer() {
     this.searchResults = document.createElement('div');
     this.searchResults.id = 'search-results';
@@ -72,6 +91,13 @@ class GlobalSearch {
     // Input events
     this.searchInput.addEventListener('input', (e) => {
       this.handleSearch(e.target.value);
+      this.updateClearButtonVisibility();
+    });
+    
+    // Clear button click
+    this.clearButton.addEventListener('click', (e) => {
+      e.preventDefault();
+      this.clearSearch();
     });
     
     // Keyboard navigation
@@ -247,6 +273,21 @@ class GlobalSearch {
     this.currentSelection = -1;
   }
   
+  clearSearch() {
+    this.searchInput.value = '';
+    this.hideResults();
+    this.updateClearButtonVisibility();
+    this.searchInput.focus();
+  }
+  
+  updateClearButtonVisibility() {
+    if (this.searchInput.value.trim()) {
+      this.clearButton.classList.remove('hidden');
+    } else {
+      this.clearButton.classList.add('hidden');
+    }
+  }
+  
   handleKeydown(e) {
     const items = this.searchResults.querySelectorAll('.search-result-item');
     

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.53.0",
+  "version": "0.55.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {

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;
+}