@kenjura/ursa 0.52.0 → 0.53.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+# 0.53.0
+2025-01-01
+
+### 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.53.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/jobs/generate.js

@@ -323,7 +323,9 @@ export async function generate({
   const validPaths = buildValidPaths(allSourceFilenamesThatAreArticles, source, allSourceFilenamesThatAreDirectories);
   progress.log(`Built ${validPaths.size} valid paths for link validation`);
 
-  const menu = await getMenu(allSourceFilenames, source, validPaths);
+  const menuResult = await getMenu(allSourceFilenames, source, validPaths);
+  const menu = menuResult.html;
+  const menuData = menuResult.menuData;
 
   // Get and increment build ID from .ursa.json
   const buildId = getAndIncrementBuildId(resolve(_source));
@@ -549,6 +551,13 @@ export async function generate({
   progress.log(`Writing search index with ${searchIndex.length} entries`);
   await outputFile(searchIndexPath, JSON.stringify(searchIndex));
 
+  // Write menu data as a separate JSON file (not embedded in each page)
+  // This dramatically reduces HTML file sizes for large sites
+  const menuDataPath = join(output, 'public', 'menu-data.json');
+  const menuDataJson = JSON.stringify(menuData);
+  progress.log(`Writing menu data (${(menuDataJson.length / 1024).toFixed(1)} KB)`);
+  await outputFile(menuDataPath, menuDataJson);
+
   // Process directory indices with batched concurrency
   const totalDirs = allSourceFilenamesThatAreDirectories.length;
   let processedDirs = 0;
@@ -1084,23 +1093,12 @@ async function getTemplates(meta) {
 async function getMenu(allSourceFilenames, source, validPaths) {
   // todo: handle various incarnations of menu filename
 
-  const rawMenu = await getAutomenu(source, validPaths);
-  const menuBody = renderFile({ fileContents: rawMenu, type: ".md" });
-  return menuBody;
-
-  // const allMenus = allSourceFilenames.filter((filename) =>
-  //   filename.match(/_?menu\.(html|yml|md|txt)/)
-  // );
-  // console.log({ allMenus });
-  // if (allMenus.length === 0) return "";
-
-  // // pick best menu...TODO: actually apply logic here
-  // const bestMenu = allMenus[0];
-  // const rawBody = await readFile(bestMenu, "utf8");
-  // const type = parse(bestMenu).ext;
-  // const menuBody = renderFile({ fileContents: rawBody, type });
-
-  // return menuBody;
+  const menuResult = await getAutomenu(source, validPaths);
+  const menuBody = renderFile({ fileContents: menuResult.html, type: ".md" });
+  return {
+    html: menuBody,
+    menuData: menuResult.menuData
+  };
 }
 
 async function getTransformedMetadata(dirname, metadata) {

package/src/serve.js

@@ -1,4 +1,5 @@
 import express from "express";
+import compression from "compression";
 import watch from "node-watch";
 import { generate, regenerateSingleFile, clearWatchCache } from "./jobs/generate.js";
 import { join, resolve, dirname } from "path";
@@ -252,6 +253,15 @@ export async function serve({
 function serveFiles(outputDir, port = 8080) {
   const app = express();
 
+  // Enable gzip compression for all responses
+  // This significantly reduces transfer size for JSON and HTML files
+  app.use(compression({
+    // Compress everything over 1KB
+    threshold: 1024,
+    // Use default compression level (good balance of speed vs size)
+    level: 6
+  }));
+
   app.use(
     express.static(outputDir, { extensions: ["html"], index: "index.html" })
   );