@kenjura/ursa 0.66.0 → 0.73.0

package/CHANGELOG.md

@@ -1,3 +1,60 @@
+# 0.73.0
+2026-02-07
+
+- fixed build pipeline blocker
+
+# 0.72.0
+2026-02-07
+
+- MDX support: Ursa can now process .mdx files with embedded JSX components
+  - MDX files are parsed and rendered to HTML with React components
+  - Custom components can be imported and used within MDX content
+  - MDX documents are fully integrated with Ursa's build and serve processes, including hot reloading in dev mode
+  - This allows for rich interactive content while still benefiting from Ursa's static site generation features
+
+# 0.71.0
+2026-02-05
+
+- 'Dev mode': new mode similar to serve, but only generates documents on-demand to save time.
+  - When running `ursa dev`, the server starts immediately without a full build
+  - Documents are generated on-the-fly when requested, with caching for subsequent requests
+  - Ideal for development with large sites where full builds are slow
+  - Still supports hot reloading and file watching for dynamic updates
+- Custom menus can now include auto-generated menus in addition to custom content
+- Custom menus are displayed on the top bar instead of the side
+
+# 0.70.0
+2026-02-04
+
+- **Navigation Cache**: Dramatically improved navigation build time
+  - Navigation structure cached in `.ursa/nav-cache.json`
+  - Cache validated by file list hash + metadata file stats (index.md, config.json)
+  - Parallel stat operations for faster cache validation
+  - Result: Navigation build drops from ~9s to ~50ms on cached runs (99% improvement)
+
+# 0.69.0
+2026-02-04
+
+- **Image Processing Performance**: Dramatically improved image processing speed
+  - Persistent image cache: images are only re-processed when source file changes (mtime/size check)
+  - Parallel processing: 8 images processed concurrently instead of sequentially
+  - Smart preview skipping: images smaller than 800x800 skip preview generation (already small enough)
+  - Result: Image processing drops from ~23s to ~16ms on cached runs (99.9% improvement)
+
+# 0.68.0
+2026-02-04
+
+- **Build Performance Profiling**: Added comprehensive profiling to identify performance bottlenecks
+  - Each build phase is now timed with millisecond precision
+  - Visual bar chart report shows percentage of total build time per phase
+  - Phases tracked: Scan source files, Filter & classify, Build navigation, Load cache, Copy meta files, Process images, Process articles, Write search index, Write menu data, Process directories, Process static files, Auto-index generation, Finalization
+  - Report displayed at end of each build for performance analysis
+
+# 0.67.0
+2026-02-04
+
+- All images referenced in whitelisted documents should be processed and copied, even if the images themselves are not in the whitelist
+
 # 0.66.0
 2026-02-04
 

package/bin/ursa.js

@@ -168,6 +168,55 @@ yargs(hideBin(process.argv))
       }
     }
   )
+  .command(
+    'dev <source>',
+    'Start dev mode - serves documents on-demand without pre-processing (fast startup)',
+    (yargs) => {
+      return yargs
+        .positional('source', {
+          describe: 'Source directory containing markdown/wikitext files',
+          type: 'string',
+          demandOption: true
+        })
+        .option('meta', {
+          alias: 'm',
+          describe: 'Meta directory containing templates and styles (defaults to ursa package meta)',
+          type: 'string'
+        })
+        .option('output', {
+          alias: 'o', 
+          default: 'output',
+          describe: 'Output directory for generated files',
+          type: 'string'
+        })
+        .option('port', {
+          alias: 'p',
+          default: 8080,
+          describe: 'Port to serve on',
+          type: 'number'
+        });
+    },
+    async (argv) => {
+      const source = resolve(argv.source);
+      const meta = argv.meta ? resolve(argv.meta) : PACKAGE_META;
+      const output = resolve(argv.output);
+      const port = argv.port;
+      
+      try {
+        const { dev } = await import('../src/dev.js');
+        await dev({
+          _source: source,
+          _meta: meta,
+          _output: output,
+          port: port
+        });
+      } catch (error) {
+        console.error('Error starting dev mode:', error.message);
+        console.error(error);
+        process.exit(1);
+      }
+    }
+  )
   .command(
     '$0 <source>',
     'Generate a static site from source files (default command)',

package/meta/character-sheet-template.html

@@ -73,6 +73,7 @@
       });
     }
   </script>
+  ${customScript}
 </body>
 
 </html>

package/meta/default-template.html

@@ -12,9 +12,20 @@
     <nav id="nav-global">
         <button class="menu-button" aria-label="Menu">☰</button>
 
-        <input id="global-search" type="text" placeholder="Search..." />
+        <div class="nav-center">
+            <nav id="nav-main-top">
+                <!-- Top menu will be populated by JavaScript when data-menu-position="top" -->
+            </nav>
 
-        <span class="avatar" aria-hidden="true">👤</span>
+            <div class="search-wrapper">
+                <input id="global-search" type="text" placeholder="Search..." />
+            </div>
+        </div>
+
+        <div class="nav-right-controls">
+            <button class="search-button" aria-label="Search">🔍</button>
+            <span class="avatar" aria-hidden="true">👤</span>
+        </div>
     </nav>
     <nav id="nav-main">
         ${menu}
@@ -37,6 +48,7 @@
     <script src="/public/search.js"></script>
     <script src="/public/sectionify.js"></script>
     <script src="/public/sticky.js"></script>
+    ${customScript}
 </body>
 
 </html>

package/meta/default.css

@@ -74,11 +74,17 @@ nav#nav-global {
     opacity: 0.7;
   }
 
-  .search-wrapper {
-    position: relative;
+  /* Center container for search and top menu */
+  .nav-center {
     width: var(--article-width);
     max-width: calc(100% - 16px);
     justify-self: center;
+    position: relative;
+  }
+
+  .search-wrapper {
+    position: relative;
+    width: 100%;
   }
   
   input#global-search {
@@ -120,6 +126,10 @@ nav#nav-global {
     font-size: 1.5rem;
     line-height: 1;
     padding: 8px;
+  }
+  
+  /* When avatar is standalone (not in container), align to end */
+  > .avatar {
     justify-self: end;
   }
 }
@@ -219,6 +229,253 @@ nav#nav-global {
   text-decoration: underline;
 }
 
+/* ==========================================
+   TOP NAVIGATION MENU STYLES
+   When body[data-menu-position="top"] is set
+   ========================================== */
+
+/* Top menu container - positioning handled by parent .nav-center */
+nav#nav-main-top {
+  display: none;
+  width: 100%;
+}
+
+/* Show top menu when position is top */
+body[data-menu-position="top"] nav#nav-main-top {
+  display: flex;
+  align-items: center;
+}
+
+/* Hide search input when top menu is present - it moves to a button */
+body[data-menu-position="top"] nav#nav-global input#global-search {
+  display: none;
+}
+
+/* Show search button instead when top menu is active */
+body[data-menu-position="top"] nav#nav-global .search-button {
+  display: inline-flex;
+}
+
+/* Hide side nav when top menu is active */
+body[data-menu-position="top"] nav#nav-main {
+  display: none;
+}
+
+/* Full-width article when side nav is hidden */
+body[data-menu-position="top"] article#main-content {
+  margin-left: auto;
+  margin-right: auto;
+}
+
+/* Update nav-global grid to accommodate top menu - keep search+avatar together on right */
+body[data-menu-position="top"] nav#nav-global {
+  grid-template-columns: auto 1fr auto;
+}
+
+/* Top-level menu list */
+nav#nav-main-top .top-menu-level {
+  display: flex;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  gap: 0;
+}
+
+/* Top-level menu items */
+nav#nav-main-top .top-menu-item {
+  position: relative;
+  padding: 0;
+}
+
+nav#nav-main-top .top-menu-label {
+  display: block;
+  padding: 8px 16px;
+  color: var(--text-color);
+  text-decoration: none;
+  white-space: nowrap;
+  cursor: pointer;
+  transition: background-color 0.15s ease;
+}
+
+nav#nav-main-top .top-menu-label:hover {
+  background-color: rgba(255, 255, 255, 0.1);
+}
+
+nav#nav-main-top a.top-menu-label:hover {
+  text-decoration: none;
+}
+
+/* Dropdown indicator for items with children */
+nav#nav-main-top .top-menu-item.has-dropdown > .top-menu-label::after {
+  content: '▼';
+  font-size: 0.4em;
+  margin-left: 6px;
+  opacity: 0.6;
+  position: relative;
+  top: -1px;
+}
+
+/* Dropdown menu (first level of children) */
+nav#nav-main-top .top-menu-dropdown {
+  display: none;
+  position: absolute;
+  top: 100%;
+  left: 0;
+  min-width: 200px;
+  background-color: var(--bg-color);
+  border: 1px solid var(--nav-top-bg);
+  border-radius: 4px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
+  list-style: none;
+  margin: 0;
+  padding: 4px 0;
+  z-index: 1005;
+}
+
+/* Show dropdown on hover */
+nav#nav-main-top .top-menu-item.has-dropdown:hover > .top-menu-dropdown {
+  display: block;
+}
+
+/* Dropdown items */
+nav#nav-main-top .dropdown-item {
+  position: relative;
+}
+
+nav#nav-main-top .dropdown-label {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 8px 16px;
+  color: var(--text-color);
+  text-decoration: none;
+  white-space: nowrap;
+  cursor: pointer;
+  transition: background-color 0.15s ease;
+}
+
+nav#nav-main-top .dropdown-label:hover {
+  background-color: var(--nav-top-bg);
+}
+
+nav#nav-main-top a.dropdown-label:hover {
+  text-decoration: none;
+}
+
+/* Flyout indicator */
+nav#nav-main-top .flyout-indicator {
+  font-size: 0.7em;
+  opacity: 0.6;
+  margin-left: 8px;
+}
+
+/* Flyout menu (nested children) */
+nav#nav-main-top .top-menu-flyout {
+  display: none;
+  position: absolute;
+  left: 100%;
+  top: 0;
+  min-width: 200px;
+  background-color: var(--bg-color);
+  border: 1px solid var(--nav-top-bg);
+  border-radius: 4px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
+  list-style: none;
+  margin: 0;
+  padding: 4px 0;
+  z-index: 1006;
+}
+
+/* Show flyout on hover */
+nav#nav-main-top .dropdown-item.has-flyout:hover > .top-menu-flyout {
+  display: block;
+}
+
+/* Search button and avatar container (shown when top menu is active) */
+nav#nav-global .nav-right-controls {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  justify-self: end;
+}
+
+nav#nav-global .search-button {
+  display: none;
+  align-items: center;
+  justify-content: center;
+  background: none;
+  border: none;
+  color: var(--text-color);
+  font-size: 1.25rem;
+  padding: 8px 12px;
+  cursor: pointer;
+  opacity: 0.8;
+  transition: opacity 0.2s ease;
+}
+
+nav#nav-global .search-button:hover {
+  opacity: 1;
+}
+
+/* Search backdrop - just the dark overlay */
+body[data-menu-position="top"] .search-backdrop {
+  display: none;
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: rgba(0, 0, 0, 0.7);
+  z-index: 1010;
+}
+
+body[data-menu-position="top"] .search-backdrop.active {
+  display: block;
+}
+
+/* Floating search container - positioned above nav */
+body[data-menu-position="top"] .search-floating {
+  display: none;
+  position: fixed;
+  top: 80px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: min(600px, calc(100vw - 32px));
+  z-index: 1020;
+}
+
+body[data-menu-position="top"] .search-floating.active {
+  display: block;
+}
+
+/* Style the search wrapper when inside floating container */
+body[data-menu-position="top"] .search-floating .search-wrapper {
+  width: 100%;
+}
+
+body[data-menu-position="top"] .search-floating #global-search {
+  width: 100%;
+  height: 48px;
+  font-size: 1.25rem;
+  padding: 0 16px;
+  border: 2px solid var(--nav-top-bg);
+  border-radius: 8px;
+  background: var(--bg-color);
+  color: var(--text-color);
+}
+
+/* Search results inside floating container */
+body[data-menu-position="top"] .search-floating .search-results {
+  position: relative;
+  top: 4px;
+  max-height: 60vh;
+  overflow-y: auto;
+  background: var(--bg-color);
+  border: 1px solid var(--border-color);
+  border-radius: 8px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
+}
+
 nav#nav-main {
   position: fixed;
   top: calc(var(--global-nav-height));

package/meta/menu.js

@@ -3,9 +3,20 @@
  * 
  * Displays 2 columns at a time, with horizontal scrolling to navigate deeper levels.
  * Each column represents one level of the folder hierarchy.
+ * 
+ * Also supports top menu position for horizontal navigation with dropdowns.
  */
 document.addEventListener('DOMContentLoaded', () => {
     const navMain = document.querySelector('nav#nav-main');
+    const navMainTop = document.querySelector('nav#nav-main-top');
+    const menuPosition = document.body.dataset.menuPosition || 'side';
+    
+    // If menu position is top, handle differently
+    if (menuPosition === 'top') {
+        initTopMenu();
+        return;
+    }
+    
     if (!navMain) return;
 
     // Check for custom menu
@@ -527,3 +538,222 @@ document.addEventListener('DOMContentLoaded', () => {
     // Initial render (shows loading, then loadMenuData will call initializeFromCurrentPage)
     renderMenu();
 });
+
+/**
+ * Initialize top menu (horizontal navigation with dropdowns)
+ */
+function initTopMenu() {
+    const navMainTop = document.querySelector('nav#nav-main-top');
+    const customMenuPath = document.body.dataset.customMenu;
+    
+    if (!navMainTop || !customMenuPath) return;
+    
+    // Load menu data and render top menu
+    fetch(customMenuPath)
+        .then(response => response.json())
+        .then(data => {
+            // Handle new JSON format with menuData and menuPosition
+            const menuData = data.menuData || data;
+            renderTopMenu(navMainTop, menuData);
+        })
+        .catch(error => {
+            console.error('Failed to load top menu data:', error);
+        });
+    
+    // Set up search button toggle
+    initTopMenuSearch();
+}
+
+/**
+ * Render the top navigation menu
+ */
+function renderTopMenu(container, menuData) {
+    const ul = document.createElement('ul');
+    ul.className = 'top-menu-level';
+    
+    menuData.forEach(item => {
+        const li = document.createElement('li');
+        li.className = 'top-menu-item';
+        if (item.hasChildren || (item.children && item.children.length > 0)) {
+            li.classList.add('has-dropdown');
+        }
+        
+        // Create label (link or span)
+        const label = item.href 
+            ? document.createElement('a')
+            : document.createElement('span');
+        label.className = 'top-menu-label';
+        label.textContent = item.label;
+        if (item.href) {
+            label.href = item.href;
+        }
+        li.appendChild(label);
+        
+        // Create dropdown if has children
+        if (item.children && item.children.length > 0) {
+            const dropdown = createTopMenuDropdown(item.children);
+            li.appendChild(dropdown);
+        }
+        
+        ul.appendChild(li);
+    });
+    
+    container.appendChild(ul);
+}
+
+/**
+ * Create a dropdown menu for top navigation
+ */
+function createTopMenuDropdown(items) {
+    const ul = document.createElement('ul');
+    ul.className = 'top-menu-dropdown';
+    
+    items.forEach(item => {
+        const li = document.createElement('li');
+        li.className = 'dropdown-item';
+        if (item.hasChildren || (item.children && item.children.length > 0)) {
+            li.classList.add('has-flyout');
+        }
+        
+        // Create label
+        const label = item.href
+            ? document.createElement('a')
+            : document.createElement('span');
+        label.className = 'dropdown-label';
+        label.textContent = item.label;
+        if (item.href) {
+            label.href = item.href;
+        }
+        li.appendChild(label);
+        
+        // Add flyout indicator if has children
+        if (item.children && item.children.length > 0) {
+            const indicator = document.createElement('span');
+            indicator.className = 'flyout-indicator';
+            indicator.textContent = '▶';
+            label.appendChild(indicator);
+            
+            // Create flyout submenu
+            const flyout = createTopMenuFlyout(item.children);
+            li.appendChild(flyout);
+        }
+        
+        ul.appendChild(li);
+    });
+    
+    return ul;
+}
+
+/**
+ * Create a flyout submenu for nested items
+ */
+function createTopMenuFlyout(items) {
+    const ul = document.createElement('ul');
+    ul.className = 'top-menu-flyout';
+    
+    items.forEach(item => {
+        const li = document.createElement('li');
+        li.className = 'dropdown-item';
+        if (item.hasChildren || (item.children && item.children.length > 0)) {
+            li.classList.add('has-flyout');
+        }
+        
+        const label = item.href
+            ? document.createElement('a')
+            : document.createElement('span');
+        label.className = 'dropdown-label';
+        label.textContent = item.label;
+        if (item.href) {
+            label.href = item.href;
+        }
+        li.appendChild(label);
+        
+        // Recursive flyout for deeper levels
+        if (item.children && item.children.length > 0) {
+            const indicator = document.createElement('span');
+            indicator.className = 'flyout-indicator';
+            indicator.textContent = '▶';
+            label.appendChild(indicator);
+            
+            const flyout = createTopMenuFlyout(item.children);
+            li.appendChild(flyout);
+        }
+        
+        ul.appendChild(li);
+    });
+    
+    return ul;
+}
+
+/**
+ * Initialize search functionality for top menu mode
+ */
+function initTopMenuSearch() {
+    const searchButton = document.querySelector('nav#nav-global .search-button');
+    const searchInput = document.querySelector('#global-search');
+    const searchWrapper = searchInput?.closest('.search-wrapper');
+    const searchResults = document.querySelector('#search-results');
+    
+    if (!searchButton || !searchInput || !searchWrapper) return;
+    
+    // Create search overlay backdrop (just the dark background)
+    const backdrop = document.createElement('div');
+    backdrop.className = 'search-backdrop';
+    document.body.appendChild(backdrop);
+    
+    // Create container for search that floats above the nav
+    const floatingSearch = document.createElement('div');
+    floatingSearch.className = 'search-floating';
+    document.body.appendChild(floatingSearch);
+    
+    // Toggle search on button click
+    searchButton.addEventListener('click', () => {
+        backdrop.classList.add('active');
+        floatingSearch.classList.add('active');
+        
+        // Move the search wrapper into the floating container
+        floatingSearch.appendChild(searchWrapper);
+        
+        // Move search results into floating container too (if exists)
+        if (searchResults) {
+            floatingSearch.appendChild(searchResults);
+        }
+        
+        searchInput.value = '';
+        searchInput.focus();
+    });
+    
+    function closeSearch() {
+        backdrop.classList.remove('active');
+        floatingSearch.classList.remove('active');
+        
+        // Move search wrapper back to nav-center
+        const navCenter = document.querySelector('.nav-center');
+        if (navCenter && searchWrapper) {
+            navCenter.appendChild(searchWrapper);
+        }
+        // Move search results back too
+        if (searchResults && searchWrapper) {
+            searchWrapper.parentNode.appendChild(searchResults);
+        }
+    }
+    
+    // Close on backdrop click
+    backdrop.addEventListener('click', closeSearch);
+    
+    // Close on escape
+    document.addEventListener('keydown', (e) => {
+        if (e.key === 'Escape' && backdrop.classList.contains('active')) {
+            closeSearch();
+        }
+    });
+    
+    // Close when a search result is clicked (navigation will happen)
+    if (searchResults) {
+        searchResults.addEventListener('click', (e) => {
+            if (e.target.closest('.search-result-item')) {
+                closeSearch();
+            }
+        });
+    }
+}