@kenjura/ursa 0.72.0 → 0.75.0

package/meta/widgets.js

@@ -0,0 +1,376 @@
+/**
+ * Widget system for the top nav right-side panel.
+ * 
+ * Widgets appear as icon buttons in the nav bar. Clicking a button toggles a
+ * dropdown panel anchored to the right side below the nav. Only one widget can
+ * be open at a time.
+ * 
+ * Built-in widgets: TOC, Search, Profile
+ */
+class WidgetManager {
+  constructor() {
+    this.dropdown = document.getElementById('widget-dropdown');
+    this.buttons = document.querySelectorAll('.widget-button[data-widget]');
+    this.activeWidget = null;
+    
+    if (!this.dropdown || this.buttons.length === 0) return;
+    
+    this.init();
+  }
+  
+  init() {
+    // Bind button clicks
+    this.buttons.forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const widgetName = btn.dataset.widget;
+        this.toggle(widgetName);
+      });
+    });
+    
+    // Close on outside click
+    document.addEventListener('click', (e) => {
+      if (this.activeWidget && 
+          !this.dropdown.contains(e.target) &&
+          !e.target.closest('.widget-button')) {
+        this.close();
+      }
+    });
+    
+    // Close on Escape
+    document.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape' && this.activeWidget) {
+        this.close();
+      }
+    });
+
+    // Initialize search widget content
+    this.initSearchWidget();
+  }
+  
+  /**
+   * Toggle a widget open/closed. If a different widget is open, switch to the new one.
+   */
+  toggle(widgetName) {
+    if (this.activeWidget === widgetName) {
+      this.close();
+      return;
+    }
+    
+    this.open(widgetName);
+  }
+  
+  /**
+   * Open a specific widget panel.
+   */
+  open(widgetName) {
+    // Close any open widget first
+    if (this.activeWidget) {
+      this.deactivateContent(this.activeWidget);
+    }
+    
+    this.activeWidget = widgetName;
+    
+    // Show dropdown
+    this.dropdown.classList.remove('hidden');
+    this.dropdown.dataset.activeWidget = widgetName;
+    
+    // Show the correct content panel
+    this.activateContent(widgetName);
+    
+    // Update button states
+    this.buttons.forEach(btn => {
+      btn.classList.toggle('active', btn.dataset.widget === widgetName);
+    });
+
+    // Fire event for other scripts to listen to
+    document.dispatchEvent(new CustomEvent('widget-opened', { detail: { widget: widgetName } }));
+  }
+  
+  /**
+   * Close the currently open widget.
+   */
+  close() {
+    if (!this.activeWidget) return;
+    
+    const closing = this.activeWidget;
+    this.deactivateContent(closing);
+    
+    this.activeWidget = null;
+    this.dropdown.classList.add('hidden');
+    delete this.dropdown.dataset.activeWidget;
+    
+    // Update button states
+    this.buttons.forEach(btn => btn.classList.remove('active'));
+    
+    // Fire event
+    document.dispatchEvent(new CustomEvent('widget-closed', { detail: { widget: closing } }));
+  }
+  
+  /**
+   * Show a widget's content panel.
+   */
+  activateContent(widgetName) {
+    const content = this.dropdown.querySelector(`.widget-content[data-widget="${widgetName}"]`);
+    if (content) {
+      content.classList.add('active');
+    }
+    
+    // Widget-specific activation
+    if (widgetName === 'search') {
+      this.activateSearch();
+    }
+  }
+  
+  /**
+   * Hide a widget's content panel.
+   */
+  deactivateContent(widgetName) {
+    const content = this.dropdown.querySelector(`.widget-content[data-widget="${widgetName}"]`);
+    if (content) {
+      content.classList.remove('active');
+    }
+    
+    // Widget-specific deactivation
+    if (widgetName === 'search') {
+      this.deactivateSearch();
+    }
+  }
+  
+  /**
+   * Initialize search widget — move the search input and results into the widget panel.
+   */
+  initSearchWidget() {
+    const searchContent = document.getElementById('widget-content-search');
+    if (!searchContent) return;
+    
+    // The search input and wrapper are created by search.js (GlobalSearch).
+    // We need to wait for it to be ready, then move elements into the widget.
+    // Use a short delay to let GlobalSearch initialize first.
+    const moveSearch = () => {
+      const searchWrapper = document.querySelector('.search-wrapper-inline');
+      const searchResults = document.getElementById('search-results');
+      
+      if (searchWrapper) {
+        // Clone the search input into the widget (the inline one stays for non-top-menu/mobile)
+        // Actually, we'll relocate the existing elements when the widget is activated.
+        // For now, create a dedicated search input for the widget.
+        const widgetInput = document.createElement('input');
+        widgetInput.id = 'widget-search-input';
+        widgetInput.type = 'text';
+        widgetInput.placeholder = 'Search...';
+        widgetInput.className = 'widget-search-input';
+        
+        const widgetWrapper = document.createElement('div');
+        widgetWrapper.className = 'widget-search-wrapper';
+        widgetWrapper.appendChild(widgetInput);
+        
+        // Create dedicated results container for widget
+        const widgetResults = document.createElement('div');
+        widgetResults.id = 'widget-search-results';
+        widgetResults.className = 'widget-search-results';
+        
+        searchContent.appendChild(widgetWrapper);
+        searchContent.appendChild(widgetResults);
+        
+        // Bind the widget search input to the GlobalSearch instance
+        this.bindWidgetSearch(widgetInput, widgetResults);
+      }
+    };
+    
+    // Wait for search.js to initialize
+    setTimeout(moveSearch, 50);
+  }
+  
+  /**
+   * Bind the widget search input to use GlobalSearch's search functionality.
+   */
+  bindWidgetSearch(input, resultsContainer) {
+    this._widgetSearchInput = input;
+    this._widgetSearchResults = resultsContainer;
+    
+    let currentSelection = -1;
+    
+    input.addEventListener('input', () => {
+      const query = input.value.trim();
+      this.performWidgetSearch(query);
+    });
+    
+    input.addEventListener('keydown', (e) => {
+      const items = resultsContainer.querySelectorAll('.search-result-item');
+      
+      switch (e.key) {
+        case 'ArrowDown':
+          e.preventDefault();
+          if (items.length > 0) {
+            currentSelection = Math.min(currentSelection + 1, items.length - 1);
+            this.updateWidgetSearchSelection(items, currentSelection);
+          }
+          break;
+        case 'ArrowUp':
+          e.preventDefault();
+          if (items.length > 0) {
+            currentSelection = Math.max(currentSelection - 1, 0);
+            this.updateWidgetSearchSelection(items, currentSelection);
+          }
+          break;
+        case 'Enter':
+          e.preventDefault();
+          if (currentSelection >= 0 && items[currentSelection]) {
+            items[currentSelection].click();
+          }
+          break;
+        case 'Escape':
+          this.close();
+          break;
+      }
+    });
+
+    // Reset selection on new search
+    input.addEventListener('input', () => { currentSelection = -1; });
+  }
+  
+  /**
+   * Perform search using GlobalSearch's search logic, rendering into widget results.
+   */
+  performWidgetSearch(query) {
+    const gs = window.globalSearch;
+    const container = this._widgetSearchResults;
+    if (!gs || !container) return;
+    
+    container.innerHTML = '';
+    
+    if (!query || query.length < gs.MIN_QUERY_LENGTH) {
+      if (query && query.length > 0) {
+        container.innerHTML = `<div class="search-result-message">Type at least ${gs.MIN_QUERY_LENGTH} characters to search</div>`;
+      }
+      return;
+    }
+    
+    if (!gs.indexLoaded) {
+      container.innerHTML = '<div class="search-result-message">Loading search index...</div>';
+      return;
+    }
+    
+    const pathResults = gs.searchPaths(query);
+    const fullTextResults = gs.searchFullText(query);
+    
+    // Deduplicate
+    const pathPaths = new Set(pathResults.map(r => r.path));
+    const uniqueFullTextResults = fullTextResults.filter(r => !pathPaths.has(r.path));
+    
+    if (pathResults.length === 0 && uniqueFullTextResults.length === 0) {
+      container.innerHTML = `<div class="search-result-message">No results for "${query}"</div>`;
+      return;
+    }
+    
+    // Path results section
+    if (pathResults.length > 0) {
+      const section = document.createElement('div');
+      section.className = 'search-section';
+      const header = document.createElement('div');
+      header.className = 'search-section-header';
+      header.textContent = `Title/Path Matches (${pathResults.length})`;
+      section.appendChild(header);
+      
+      const limit = Math.min(pathResults.length, 10);
+      for (let i = 0; i < limit; i++) {
+        section.appendChild(this.createWidgetResultItem(pathResults[i]));
+      }
+      if (pathResults.length > 10) {
+        const more = document.createElement('div');
+        more.className = 'search-result-message';
+        more.textContent = `... and ${pathResults.length - 10} more`;
+        section.appendChild(more);
+      }
+      container.appendChild(section);
+    }
+    
+    // Full-text results section
+    if (uniqueFullTextResults.length > 0) {
+      const section = document.createElement('div');
+      section.className = 'search-section';
+      const header = document.createElement('div');
+      header.className = 'search-section-header';
+      header.textContent = `Content Matches (${uniqueFullTextResults.length})`;
+      section.appendChild(header);
+      
+      const limit = Math.min(uniqueFullTextResults.length, 10);
+      for (let i = 0; i < limit; i++) {
+        section.appendChild(this.createWidgetResultItem(uniqueFullTextResults[i]));
+      }
+      if (uniqueFullTextResults.length > 10) {
+        const more = document.createElement('div');
+        more.className = 'search-result-message';
+        more.textContent = `... and ${uniqueFullTextResults.length - 10} more`;
+        section.appendChild(more);
+      }
+      container.appendChild(section);
+    }
+  }
+  
+  /**
+   * Create a search result item for the widget.
+   */
+  createWidgetResultItem(result) {
+    const item = document.createElement('div');
+    item.className = 'search-result-item';
+    
+    const title = document.createElement('div');
+    title.className = 'search-result-title';
+    title.textContent = result.title || 'Untitled';
+    
+    const path = document.createElement('div');
+    path.className = 'search-result-path';
+    path.textContent = result.path || result.url || '';
+    
+    item.appendChild(title);
+    item.appendChild(path);
+    
+    item.addEventListener('click', () => {
+      window.location.href = result.url || result.path;
+    });
+    
+    item.addEventListener('mouseenter', () => {
+      // Clear other selections
+      item.closest('.widget-search-results')?.querySelectorAll('.search-result-item').forEach(el => {
+        el.classList.remove('selected');
+      });
+      item.classList.add('selected');
+    });
+    
+    return item;
+  }
+  
+  updateWidgetSearchSelection(items, index) {
+    items.forEach((item, i) => {
+      item.classList.toggle('selected', i === index);
+    });
+    if (index >= 0 && items[index]) {
+      items[index].scrollIntoView({ block: 'nearest' });
+    }
+  }
+  
+  /**
+   * Called when the search widget is activated.
+   */
+  activateSearch() {
+    const input = this._widgetSearchInput;
+    if (input) {
+      // Focus with small delay to allow panel animation
+      setTimeout(() => input.focus(), 50);
+    }
+  }
+  
+  /**
+   * Called when the search widget is deactivated.
+   */
+  deactivateSearch() {
+    // Keep the search query so user can re-open and see results
+  }
+}
+
+// Initialize widgets when DOM is ready
+document.addEventListener('DOMContentLoaded', () => {
+  window.widgetManager = new WidgetManager();
+});

package/package.json

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

package/src/dev.js

@@ -28,6 +28,7 @@ import { buildFullTextIndex } from "./helper/fullTextIndex.js";
 import { getAutomenu } from "./helper/automenu.js";
 import { renderFile } from "./helper/fileRenderer.js";
 import { processImage } from "./helper/imageProcessor.js";
+import { generateBreadcrumbs } from "./helper/breadcrumbs.js";
 import { extractImageReferences } from "./helper/imageExtractor.js";
 import { recurse } from "./helper/recursive-readdir.js";
 import { isFolderHidden, clearConfigCache } from "./helper/folderConfig.js";
@@ -358,8 +359,9 @@ async function renderDocument(urlPath) {
     const sourceDir = dirname(sourcePath);
     const autoIndexHtml = await generateAutoIndexHtmlFromSource(sourceDir, 2);
     if (autoIndexHtml) {
-      // Wrap in template and return
-      return await wrapInTemplate(autoIndexHtml, 'Index', null, urlPath, sourcePath);
+      // Wrap in template and return — use parent folder name for title
+      const indexTitle = toTitleCase(basename(dirname(sourcePath)) || 'Index');
+      return await wrapInTemplate(autoIndexHtml, indexTitle, null, urlPath, sourcePath);
     }
   }
   
@@ -375,6 +377,20 @@ async function renderDocument(urlPath) {
   });
   
   const fileMeta = extractMetadata(rawBody);
+
+  // Title from filename (for index/home, use parent folder name)
+  const titleBase = (base === 'index' || base === 'home') ? basename(dirname(sourcePath)) : base;
+  const title = toTitleCase(titleBase || base);
+  if (!body || !body.trimStart().startsWith('<h1')) {
+    const h1Title = fileMeta?.title || title;
+    body = `<h1>${h1Title}</h1>\n` + (body || '');
+  }
+
+  // Inject breadcrumbs before the H1
+  const breadcrumbs = generateBreadcrumbs(dir, base, fileMeta);
+  if (breadcrumbs) {
+    body = breadcrumbs + body;
+  }
   
   // Inject frontmatter table for markdown/mdx files
   if ((type === '.md' || type === '.mdx') && fileMeta) {
@@ -401,7 +417,6 @@ async function renderDocument(urlPath) {
   // Process images in this document
   body = await processDocumentImages(body, sourcePath);
   
-  const title = toTitleCase(base);
   const html = await wrapInTemplate(body, title, fileMeta, urlPath, sourcePath);
   
   // Cache rendered document
@@ -463,7 +478,7 @@ async function wrapInTemplate(body, title, fileMeta, urlPath, sourcePath) {
   
   // Build replacements
   const replacements = {
-    "${title}": title,
+    "${title}": fileMeta?.title || title,
     "${menu}": menu,
     "${meta}": JSON.stringify(fileMeta || {}),
     "${transformedMetadata}": "",
@@ -478,16 +493,28 @@ async function wrapInTemplate(body, title, fileMeta, urlPath, sourcePath) {
   const pattern = /\$\{(title|menu|meta|transformedMetadata|body|styleLink|customScript|searchIndex|footer)\}/g;
   let finalHtml = template.replace(pattern, (match) => replacements[match] ?? match);
   
-  // Check for custom menu
+  // Add menu data attributes to body
   if (sourcePath && customMenus) {
     const customMenuInfo = getCustomMenuForFile(sourcePath, source, customMenus);
     if (customMenuInfo) {
-      const menuPosition = customMenuInfo.menuPosition || 'side';
+      const menuPosition = customMenuInfo.menuPosition || 'top';
       finalHtml = finalHtml.replace(
         /<body([^>]*)>/,
         `<body$1 data-custom-menu="${customMenuInfo.menuJsonPath}" data-menu-position="${menuPosition}">`
       );
+    } else {
+      // No custom menu — default to top menu
+      finalHtml = finalHtml.replace(
+        /<body([^>]*)>/,
+        `<body$1 data-menu-position="top">`
+      );
     }
+  } else {
+    // No custom menus at all — default to top menu
+    finalHtml = finalHtml.replace(
+      /<body([^>]*)>/,
+      `<body$1 data-menu-position="top">`
+    );
   }
   
   // Resolve relative URLs
@@ -568,7 +595,7 @@ async function buildBackgroundCaches() {
       const customMenuPath = join(output, menuInfo.menuJsonPath);
       const customMenuJson = JSON.stringify({
         menuData: menuInfo.menuData,
-        menuPosition: menuInfo.menuPosition || 'side',
+        menuPosition: menuInfo.menuPosition || 'top',
       });
       await outputFile(customMenuPath, customMenuJson);
     }
@@ -615,7 +642,8 @@ async function buildBackgroundCaches() {
         const ext = extname(article);
         const base = basename(article, ext);
         const relativePath = article.replace(source, '').replace(/\.(md|txt|yml)$/, '.html');
-        const title = toTitleCase(base);
+        const titleBase = (base === 'index' || base === 'home') ? basename(dirname(article)) : base;
+        const title = toTitleCase(titleBase || base);
         
         searchIndex.push({
           title,
@@ -732,13 +760,13 @@ export async function dev({
     if (url.startsWith('/public/custom-menu-') && url.endsWith('.json')) {
       // Find the menuDir from the cached customMenus by matching the JSON path
       let menuDir = null;
-      let menuPosition = 'side';
+      let menuPosition = 'top';
       
       if (devState.customMenus) {
         for (const [dir, menuInfo] of devState.customMenus) {
           if (menuInfo.menuJsonPath === url) {
             menuDir = dir;
-            menuPosition = menuInfo.menuPosition || 'side';
+            menuPosition = menuInfo.menuPosition || 'top';
             break;
           }
         }
@@ -750,7 +778,7 @@ export async function dev({
         if (menuInfo) {
           const { frontmatter, body } = extractMenuFrontmatter(menuInfo.content);
           const autoGenerate = frontmatter['auto-generate-menu'] === true || frontmatter['auto-generate-menu'] === 'true';
-          const depth = parseInt(frontmatter['menu-depth'], 10) || 2;
+          const depth = parseInt(frontmatter['menu-depth'], 10) || 10;
           menuPosition = frontmatter['menu-position'] || menuPosition;
           
           let menuData;

package/src/helper/automenu.js

@@ -109,6 +109,20 @@ function isIndexFile(baseName) {
   return baseName.toLowerCase() === 'index';
 }
 
+/**
+ * Check if a file acts as the "index" for its parent folder.
+ * This is true for actual index files (index.md) and also for files
+ * whose name matches their parent folder (e.g. Arcanist/Arcanist.md).
+ * @param {string} filePath - Full path to the file
+ * @returns {boolean}
+ */
+function isFolderNamedFile(filePath) {
+  const ext = extname(filePath);
+  const fileBase = basename(filePath, ext).toLowerCase();
+  const parentBase = basename(dirname(filePath)).toLowerCase();
+  return fileBase === parentBase;
+}
+
 function hasIndexFile(dirPath) {
   for (const ext of INDEX_EXTENSIONS) {
     const indexPath = join(dirPath, `index${ext}`);
@@ -232,11 +246,29 @@ function resolveHref(rawHref, validPaths) {
   return { href: rawHref, inactive: true, debug: debugTries.join(' | ') };
 }
 
+/**
+ * Recursively check if a directory-tree node contains any document files.
+ * @param {object} treeNode - A node from the directory-tree package
+ * @param {string[]} docExtensions - Extensions that count as documents
+ * @returns {boolean}
+ */
+function treeHasDocuments(treeNode, docExtensions) {
+  if (!treeNode.children) {
+    // Leaf node (file) — check its extension
+    return docExtensions.includes(extname(treeNode.path));
+  }
+  // Directory — recurse into children
+  return treeNode.children.some(child => treeHasDocuments(child, docExtensions));
+}
+
 // Build a flat tree structure with path info for JS navigation
 // Set includeDebug=false to exclude debug fields and reduce JSON size
 function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug = true) {
   const items = [];
   
+  // Document extensions that count as "real content"
+  const DOC_EXTENSIONS = ['.md', '.mdx', '.txt', '.html'];
+  
   // Files to hide from menu by default
   const hiddenFiles = ['config.json', 'style.css', 'footer.md'];
   
@@ -270,13 +302,18 @@ function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug =
       continue; // Skip hidden folders
     }
     
+    // Skip folders that contain no document files (recursively)
+    if (hasChildren && !treeHasDocuments(item, DOC_EXTENSIONS)) {
+      continue;
+    }
+    
     // Get folder config for custom label and icon (deprecated for labels, still used for icons/hidden)
     const folderConfig = hasChildren ? getFolderConfig(item.path) : null;
     
     // Determine the label - prefer menu-label from frontmatter
     let label;
     let sortKey;
-    const isIndex = !hasChildren && isIndexFile(baseName);
+    const isIndex = !hasChildren && (isIndexFile(baseName) || isFolderNamedFile(item.path));
     
     if (hasChildren) {
       // For folders, get label from index.md frontmatter, then config.json, then folder name
@@ -286,7 +323,12 @@ function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug =
     } else {
       // For files, check frontmatter for menu-label
       const fileLabel = getMenuLabelFromFile(item.path);
-      label = fileLabel || toDisplayName(baseName);
+      if (isIndex) {
+        // Index files (index.md or foldername.md) default to "Home" label
+        label = fileLabel || 'Home';
+      } else {
+        label = fileLabel || toDisplayName(baseName);
+      }
       // Get sort key from file's frontmatter, fall back to baseName (not transformed label)
       // This ensures menu-sort-as values can match original filenames consistently
       const fileSortKey = getMenuSortAsFromFile(item.path);
@@ -347,7 +389,7 @@ function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug =
     items.push(menuItem);
   }
   
-  // Sort: folders first, then index files, then alphabetically by sortKey
+  // Sort: folders first (a-z), then index files, then other files (a-z)
   return items.sort((a, b) => {
     // Folders always come first
     if (a.hasChildren && !b.hasChildren) return -1;
@@ -355,31 +397,79 @@ function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug =
     // Index files come before other files (after folders)
     if (a.isIndex && !b.isIndex) return -1;
     if (b.isIndex && !a.isIndex) return 1;
-    // Alphabetical sort by sortKey (menu-sort-as or label)
-    if (a.sortKey > b.sortKey) return 1;
-    if (a.sortKey < b.sortKey) return -1;
+    // Alphabetical sort by sortKey (case-insensitive)
+    const aKey = (a.sortKey || '').toLowerCase();
+    const bKey = (b.sortKey || '').toLowerCase();
+    if (aKey > bKey) return 1;
+    if (aKey < bKey) return -1;
     return 0;
   });
 }
 
+/**
+ * Post-process menu data to collapse single-document folders.
+ * When a folder contains only an index file (index.md) or a foldername-matching
+ * file (e.g. Arcanist/Arcanist.md) and no other children, the folder is replaced
+ * with a direct link to that document using the folder's label.
+ */
+function collapseSingleDocFolders(items) {
+  return items.map(item => {
+    if (!item.hasChildren || !item.children) return item;
+    
+    // Recurse first so nested single-doc folders are collapsed bottom-up
+    item.children = collapseSingleDocFolders(item.children);
+    
+    // Check if the only child(ren) are index-like files (no sub-folders)
+    const nonIndexChildren = item.children.filter(c => !c.isIndex);
+    if (nonIndexChildren.length === 0 && item.children.length > 0) {
+      // All children are index files — collapse to a single link
+      const indexChild = item.children[0];
+      return {
+        ...item,
+        hasChildren: false,
+        children: undefined,
+        href: indexChild.href || item.href,
+        isIndex: false,
+      };
+    }
+    
+    return item;
+  });
+}
+
 export async function getAutomenu(source, validPaths) {
   const tree = dirTree(source, {
     exclude: /[\/\\]\.|node_modules/,  // Exclude hidden folders (starting with .) and node_modules
   });
   
   // Build menu data WITHOUT debug fields for smaller JSON
-  const menuData = buildMenuData(tree, source, validPaths, '', false);
+  let menuData = buildMenuData(tree, source, validPaths, '', false);
+  
+  // Post-process: collapse single-document folders into direct links
+  menuData = collapseSingleDocFolders(menuData);
   
   // Get root config for openMenuItems setting
   const rootConfig = getRootConfig(source);
   const openMenuItems = rootConfig?.openMenuItems || [];
   
-  // Add home item with resolved href
+  // Partition top-level items: files go under Home, folders stay at top level
+  const topLevelFolders = menuData.filter(item => item.hasChildren);
+  const topLevelFiles = menuData.filter(item => !item.hasChildren);
+  
+  // Build Home item with top-level files as children
   const homeResolved = resolveHref('/', validPaths);
-  const fullMenuData = [
-    { label: 'Home', path: '', href: homeResolved.href, hasChildren: false, icon: `<span class="menu-icon">${HOME_ICON}</span>` },
-    ...menuData
-  ];
+  const homeItem = {
+    label: 'Home',
+    path: '',
+    href: homeResolved.href,
+    hasChildren: topLevelFiles.length > 0,
+    icon: `<span class="menu-icon">${HOME_ICON}</span>`,
+  };
+  if (topLevelFiles.length > 0) {
+    homeItem.children = topLevelFiles;
+  }
+  
+  const fullMenuData = [homeItem, ...topLevelFolders];
   
   // Embed the openMenuItems config as JSON (small, safe to embed)
   const menuConfigScript = `<script type="application/json" id="menu-config">${JSON.stringify({ openMenuItems })}</script>`;