@kenjura/ursa 0.54.0 → 0.55.0

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 0.55.0
+2025-12-21
+
+- custom menus (menu.md|txt) override the automenu when present
+
 # 0.54.0
 2025-12-21
 

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.54.0",
+  "version": "0.55.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {

package/src/helper/build/menu.js

@@ -1,6 +1,8 @@
 // Menu helpers for build
 import { getAutomenu } from "../automenu.js";
 import { renderFile } from "../fileRenderer.js";
+import { findCustomMenu, parseCustomMenu, buildCustomMenuHtml } from "../customMenu.js";
+import { dirname, relative, resolve } from "path";
 
 /**
  * Get menu HTML and menu data from source directory
@@ -17,3 +19,85 @@ export async function getMenu(allSourceFilenames, source, validPaths) {
     menuData: menuResult.menuData
   };
 }
+
+/**
+ * Find all unique custom menus in the source tree
+ * @param {string[]} allSourceFilenames - All source file names
+ * @param {string} source - Source directory path
+ * @returns {Map<string, {menuPath: string, menuDir: string, menuData: Array}>} Map of menu dir to menu info
+ */
+export function findAllCustomMenus(allSourceFilenames, source) {
+  const customMenus = new Map();
+  const checkedDirs = new Set();
+  
+  // Check each directory for custom menus
+  for (const file of allSourceFilenames) {
+    const dir = dirname(file);
+    if (checkedDirs.has(dir)) continue;
+    checkedDirs.add(dir);
+    
+    const menuInfo = findCustomMenu(dir, source);
+    if (menuInfo && !customMenus.has(menuInfo.menuDir)) {
+      const menuData = parseCustomMenu(menuInfo.content, menuInfo.menuDir, source);
+      customMenus.set(menuInfo.menuDir, {
+        menuPath: menuInfo.path,
+        menuDir: menuInfo.menuDir,
+        menuData,
+        // The URL path for the menu JSON file
+        menuJsonPath: '/public/custom-menu-' + getMenuId(menuInfo.menuDir, source) + '.json',
+      });
+    }
+  }
+  
+  return customMenus;
+}
+
+/**
+ * Generate a unique ID for a custom menu based on its directory
+ * @param {string} menuDir - The directory where the menu is located
+ * @param {string} source - The source root directory
+ * @returns {string} - A URL-safe ID
+ */
+function getMenuId(menuDir, source) {
+  const relativePath = relative(source, menuDir);
+  if (!relativePath) return 'root';
+  return relativePath.replace(/[\/\\]/g, '-').replace(/[^a-zA-Z0-9-]/g, '');
+}
+
+/**
+ * Get the custom menu info for a specific file path
+ * @param {string} filePath - The source file path
+ * @param {string} source - The source root directory
+ * @param {Map} customMenus - Map of all custom menus
+ * @returns {{menuJsonPath: string, menuDir: string} | null} - Custom menu info or null
+ */
+export function getCustomMenuForFile(filePath, source, customMenus) {
+  const fileDir = resolve(dirname(filePath));
+  const sourceResolved = resolve(source);
+  
+  // Walk up from file dir to find matching custom menu
+  let currentDir = fileDir;
+  while (currentDir.startsWith(sourceResolved)) {
+    if (customMenus.has(currentDir)) {
+      const menuInfo = customMenus.get(currentDir);
+      return {
+        menuJsonPath: menuInfo.menuJsonPath,
+        menuDir: relative(source, menuInfo.menuDir) || '',
+      };
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) break;
+    currentDir = parentDir;
+  }
+  
+  return null;
+}
+
+/**
+ * Build HTML for a custom menu
+ * @param {Array} menuData - The parsed menu data
+ * @returns {string} - HTML string for the menu
+ */
+export function buildCustomMenuHtmlExport(menuData) {
+  return buildCustomMenuHtml(menuData);
+}

package/src/helper/customMenu.js

@@ -0,0 +1,303 @@
+// Custom menu support - allows defining custom menus in menu.md, menu.txt, _menu.md, or _menu.txt
+import { existsSync, readFileSync } from "fs";
+import { join, dirname, relative, resolve, basename } from "path";
+
+// Menu file names to look for (in order of priority)
+const MENU_FILE_NAMES = ['menu.md', 'menu.txt', '_menu.md', '_menu.txt'];
+
+// Source file extensions to check
+const SOURCE_EXTENSIONS = ['.md', '.txt'];
+
+// Default icons
+const FOLDER_ICON = '📁';
+const DOCUMENT_ICON = '📄';
+
+/**
+ * Check if a source file exists for a given path
+ * Checks for: ./Foo.md, ./Foo.txt, ./Foo/index.md, ./Foo/index.txt, ./Foo/home.md, ./Foo/home.txt, ./Foo/Foo.md, ./Foo/Foo.txt
+ * @param {string} basePath - The base path without extension (absolute path in source)
+ * @returns {boolean} - True if a source file exists
+ */
+function sourceFileExists(basePath) {
+  const name = basename(basePath);
+  
+  // Check direct file (./Foo.md, ./Foo.txt)
+  for (const ext of SOURCE_EXTENSIONS) {
+    if (existsSync(basePath + ext)) {
+      return true;
+    }
+  }
+  
+  // Check as folder with index files (./Foo/index.md, ./Foo/index.txt, ./Foo/home.md, ./Foo/home.txt, ./Foo/Foo.md, ./Foo/Foo.txt)
+  const indexNames = ['index', 'home', name];
+  for (const indexName of indexNames) {
+    for (const ext of SOURCE_EXTENSIONS) {
+      if (existsSync(join(basePath, indexName + ext))) {
+        return true;
+      }
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Find a custom menu file in the given directory or any parent directory
+ * @param {string} dirPath - The directory to start searching from
+ * @param {string} sourceRoot - The root source directory (stop searching here)
+ * @returns {{path: string, content: string, menuDir: string} | null} - Menu file info or null if not found
+ */
+export function findCustomMenu(dirPath, sourceRoot) {
+  // Normalize paths
+  const normalizedDir = resolve(dirPath);
+  const normalizedRoot = resolve(sourceRoot);
+  
+  let currentDir = normalizedDir;
+  
+  // Walk up the directory tree until we reach or pass the source root
+  while (currentDir.startsWith(normalizedRoot)) {
+    for (const menuFileName of MENU_FILE_NAMES) {
+      const menuPath = join(currentDir, menuFileName);
+      if (existsSync(menuPath)) {
+        try {
+          const content = readFileSync(menuPath, 'utf8');
+          return {
+            path: menuPath,
+            content,
+            menuDir: currentDir, // The directory where the menu was found
+          };
+        } catch (e) {
+          console.error(`Error reading menu file ${menuPath}:`, e);
+        }
+      }
+    }
+    
+    // Move up one directory
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      // Reached filesystem root
+      break;
+    }
+    currentDir = parentDir;
+  }
+  
+  return null;
+}
+
+/**
+ * Parse a custom menu file and return menu data structure
+ * Supports two formats:
+ * 
+ * Markdown format:
+ * - [Label](./relative/path)
+ *   - [Child Label](./relative/child/path)
+ * 
+ * Wikitext format:
+ * * [[path|Label]]
+ * ** [[child/path|Child Label]]
+ * or
+ * * [[Label]]  (path derived from label)
+ * 
+ * @param {string} content - The menu file content
+ * @param {string} menuDir - The directory where the menu file was found
+ * @param {string} sourceRoot - The root source directory
+ * @returns {Array} - Menu data array compatible with the existing menu system
+ */
+export function parseCustomMenu(content, menuDir, sourceRoot) {
+  const lines = content.split('\n');
+  const menuItems = [];
+  const stack = [{ children: menuItems, indent: -1 }]; // Stack for tracking nesting
+  
+  for (const line of lines) {
+    // Skip empty lines
+    const trimmedLine = line.trim();
+    if (!trimmedLine) {
+      continue;
+    }
+    
+    let label = null;
+    let href = null;
+    let indent = 0;
+    
+    // Try wikitext format first: * [[path|Label]] or * [[Label]]
+    if (trimmedLine.match(/^\*+\s*\[\[/)) {
+      // Count asterisks for indent level
+      const asteriskMatch = trimmedLine.match(/^(\*+)/);
+      indent = asteriskMatch ? (asteriskMatch[1].length - 1) * 2 : 0; // Convert to space-equivalent
+      
+      // Parse wikitext link: [[path|label]] or [[label]]
+      const wikiMatch = trimmedLine.match(/\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/);
+      if (wikiMatch) {
+        if (wikiMatch[2]) {
+          // [[path|label]] format - first part is path, second is label
+          // Special case: _home means index
+          const pathPart = wikiMatch[1] === '_home' ? 'index' : wikiMatch[1];
+          label = wikiMatch[2];
+          href = './' + pathPart;
+        } else {
+          // [[label]] format - path derived from label
+          label = wikiMatch[1];
+          // Special case: _home means index
+          href = './' + (wikiMatch[1] === '_home' ? 'index' : wikiMatch[1]);
+        }
+      }
+    }
+    // Try markdown format: - [Label](path)
+    else if (trimmedLine.startsWith('-')) {
+      // Calculate indentation level (count leading spaces/tabs before the dash)
+      const leadingWhitespace = line.match(/^(\s*)/)[1];
+      indent = leadingWhitespace.length;
+      
+      // Parse the markdown link: - [Label](path)
+      const linkMatch = trimmedLine.match(/^-\s*\[([^\]]+)\]\(([^)]+)\)/);
+      if (linkMatch) {
+        label = linkMatch[1];
+        href = linkMatch[2];
+      }
+    }
+    
+    // Skip if we couldn't parse
+    if (!label || !href) {
+      continue;
+    }
+    
+    // Resolve relative paths based on where the menu file was found
+    // Resolve relative paths and check if source file exists
+    let absoluteSourcePath = null;
+    if (href.startsWith('./') || href.startsWith('../') || !href.startsWith('/')) {
+      // It's a relative path - resolve it relative to the menu directory
+      absoluteSourcePath = resolve(menuDir, href);
+      
+      // Check if the source file exists
+      const fileExists = sourceFileExists(absoluteSourcePath);
+      
+      if (fileExists) {
+        // Convert to web-accessible path (relative to source root)
+        href = '/' + relative(sourceRoot, absoluteSourcePath);
+        // Normalize path separators for web
+        href = href.replace(/\\/g, '/');
+        // Ensure it ends with .html if it doesn't have an extension
+        if (!href.match(/\.[a-z]+$/i)) {
+          // Check if it's likely a folder (ends with /) or file
+          if (href.endsWith('/')) {
+            href = href + 'index.html';
+          } else {
+            // Assume it's a file - add .html
+            href = href + '.html';
+          }
+        }
+      } else {
+        // Source file doesn't exist - this is a non-navigable menu item
+        href = null;
+      }
+    }
+    
+    const menuItem = {
+      label,
+      path: label.toLowerCase().replace(/\s+/g, '-'), // Generate path from label
+      href,
+      hasChildren: false, // Will be updated if children are added
+      icon: `<span class="menu-icon">${href ? DOCUMENT_ICON : FOLDER_ICON}</span>`,
+      children: [],
+    };
+    
+    // Find the correct parent based on indentation
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+    
+    // Add this item to the current parent
+    const parent = stack[stack.length - 1];
+    parent.children.push(menuItem);
+    
+    // If this is the first child, mark parent as having children
+    if (parent.menuItem) {
+      parent.menuItem.hasChildren = true;
+      parent.menuItem.icon = `<span class="menu-icon">${FOLDER_ICON}</span>`;
+    }
+    
+    // Push this item onto the stack as a potential parent
+    stack.push({ children: menuItem.children, indent, menuItem });
+  }
+  
+  return menuItems;
+}
+
+/**
+ * Get custom menu data for a given file path
+ * @param {string} filePath - The source file path
+ * @param {string} sourceRoot - The root source directory
+ * @returns {{menuData: Array, menuPath: string} | null} - Menu data and path, or null if no custom menu
+ */
+export function getCustomMenuForFile(filePath, sourceRoot) {
+  const fileDir = dirname(filePath);
+  const customMenuInfo = findCustomMenu(fileDir, sourceRoot);
+  
+  if (!customMenuInfo) {
+    return null;
+  }
+  
+  const menuData = parseCustomMenu(customMenuInfo.content, customMenuInfo.menuDir, sourceRoot);
+  
+  return {
+    menuData,
+    menuPath: customMenuInfo.path,
+    menuDir: customMenuInfo.menuDir,
+  };
+}
+
+/**
+ * Build menu HTML structure from custom menu data
+ * This matches the format expected by the existing menu.js client-side code
+ * @param {Array} menuData - The parsed menu data
+ * @returns {string} - HTML string for the menu
+ */
+export function buildCustomMenuHtml(menuData) {
+  const menuConfigScript = `<script type="application/json" id="menu-config">${JSON.stringify({ openMenuItems: [], customMenu: true })}</script>`;
+  
+  const breadcrumbHtml = `
+<div class="menu-breadcrumb" style="display: none;">
+  <button class="menu-back" title="Go back">←</button>
+  <button class="menu-home" title="Go to root">🏠</button>
+  <span class="menu-current-path"></span>
+</div>`;
+
+  const menuHtml = renderCustomMenuLevel(menuData);
+  
+  return `${menuConfigScript}${breadcrumbHtml}<ul class="menu-level" data-level="0">${menuHtml}</ul>`;
+}
+
+/**
+ * Render a level of the custom menu
+ * @param {Array} items - Menu items at this level
+ * @returns {string} - HTML string
+ */
+function renderCustomMenuLevel(items) {
+  return items.map(item => {
+    const hasChildrenClass = item.hasChildren ? ' has-children' : '';
+    const hasChildrenIndicator = item.hasChildren ? '<span class="menu-more">⋯</span>' : '';
+    
+    const labelHtml = item.href
+      ? `<a href="${item.href}" class="menu-label">${item.label}</a>`
+      : `<span class="menu-label">${item.label}</span>`;
+    
+    return `
+<li class="menu-item${hasChildrenClass}" data-path="${item.path}">
+  <div class="menu-item-row">
+    ${item.icon}
+    ${labelHtml}
+    ${hasChildrenIndicator}
+  </div>
+</li>`;
+  }).join('');
+}
+
+/**
+ * Check if a directory (or any parent) has a custom menu
+ * @param {string} dirPath - The directory to check
+ * @param {string} sourceRoot - The root source directory
+ * @returns {boolean} - True if a custom menu exists
+ */
+export function hasCustomMenu(dirPath, sourceRoot) {
+  return findCustomMenu(dirPath, sourceRoot) !== null;
+}

package/src/jobs/generate.js

@@ -46,6 +46,8 @@ import {
   addTrailingSlash,
   getTemplates,
   getMenu,
+  findAllCustomMenus,
+  getCustomMenuForFile,
   getTransformedMetadata,
   getFooter,
   generateAutoIndices,
@@ -161,6 +163,10 @@ export async function generate({
   const menu = menuResult.html;
   const menuData = menuResult.menuData;
 
+  // Find all custom menus in the source tree
+  const customMenus = findAllCustomMenus(allSourceFilenames, source);
+  progress.log(`Found ${customMenus.size} custom menu(s)`);
+
   // Get and increment build ID from .ursa.json
   const buildId = getAndIncrementBuildId(resolve(_source));
   progress.log(`Build #${buildId}`);
@@ -334,6 +340,9 @@ export async function generate({
         throw new Error(`Template not found. Requested: "${requestedTemplateName || DEFAULT_TEMPLATE_NAME}". Available templates: ${Object.keys(templates).join(', ') || 'none'}`);
       }
 
+      // Check if this file has a custom menu
+      const customMenuInfo = getCustomMenuForFile(file, source, customMenus);
+
       // Build final HTML with all replacements in a single regex pass
       // This avoids creating 8 intermediate strings
       const replacements = {
@@ -350,6 +359,14 @@ export async function generate({
       const pattern = /\$\{(title|menu|meta|transformedMetadata|body|styleLink|searchIndex|footer)\}/g;
       let finalHtml = template.replace(pattern, (match) => replacements[match] ?? match);
 
+      // If this page has a custom menu, add data attribute to body
+      if (customMenuInfo) {
+        finalHtml = finalHtml.replace(
+          /<body([^>]*)>/,
+          `<body$1 data-custom-menu="${customMenuInfo.menuJsonPath}">`
+        );
+      }
+
       // Resolve links and mark broken internal links as inactive
       finalHtml = markInactiveLinks(finalHtml, validPaths, docUrlPath, false);
 
@@ -414,6 +431,14 @@ export async function generate({
   progress.log(`Writing menu data (${(menuDataJson.length / 1024).toFixed(1)} KB)`);
   await outputFile(menuDataPath, menuDataJson);
 
+  // Write custom menu JSON files
+  for (const [menuDir, menuInfo] of customMenus) {
+    const customMenuPath = join(output, menuInfo.menuJsonPath);
+    const customMenuJson = JSON.stringify(menuInfo.menuData);
+    progress.log(`Writing custom menu: ${menuInfo.menuJsonPath}`);
+    await outputFile(customMenuPath, customMenuJson);
+  }
+
   // Process directory indices with batched concurrency
   const totalDirs = allSourceFilenamesThatAreDirectories.length;
   let processedDirs = 0;