@kenjura/ursa 0.58.0 → 0.60.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# 0.60.0
+2026-01-03
+
+- added `menu-label` frontmatter field to override default menu labels
+- added `menu-sort-as` frontmatter field for custom sort ordering
+- metadata-only index.md files now trigger auto-index generation
+- index files sorted to top of menu panes with distinct styling
+- fixed menu column vertical scrolling
+- excluded Ursa-internal fields from frontmatter table display
+
+# 0.59.0
+2026-01-01
+
+- added frontmatter rendering
+
 # 0.58.0
 2025-12-26
 

package/meta/default.css

@@ -263,6 +263,7 @@ nav#nav-main {
   .menu-columns-wrapper {
     display: flex;
     height: 100%;
+    min-height: 0; /* Allow flex children to shrink */
     transition: transform 0.25s ease-out;
   }
   
@@ -270,7 +271,9 @@ nav#nav-main {
   .menu-column {
     width: 130px;
     min-width: 130px;
+    flex-shrink: 0;
     height: 100%;
+    min-height: 0; /* Allow flex child to shrink and enable scrolling */
     overflow-y: auto;
     overflow-x: hidden;
     border-right: 1px solid rgba(128, 128, 128, 0.15);
@@ -373,6 +376,18 @@ nav#nav-main {
     opacity: 1;
   }
   
+  /* Index file styling - appears at top of menu with subtle emphasis */
+  .menu-column-item.is-index > .menu-column-item-row {
+    border-bottom: 1px solid rgba(128, 128, 128, 0.15);
+    margin-bottom: 4px;
+    padding-bottom: 8px;
+  }
+  
+  .menu-column-item.is-index > .menu-column-item-row .menu-column-label {
+    font-weight: 500;
+    opacity: 0.95;
+  }
+  
   /* Scroll buttons */
   .menu-scroll-btn {
     position: absolute;

package/meta/menu.js

@@ -227,6 +227,11 @@ document.addEventListener('DOMContentLoaded', () => {
                     li.classList.add('has-children');
                 }
                 
+                // Check if this is an index file
+                if (item.isIndex) {
+                    li.classList.add('is-index');
+                }
+                
                 // Create the item content
                 const row = document.createElement('div');
                 row.className = 'menu-column-item-row';
@@ -396,8 +401,15 @@ document.addEventListener('DOMContentLoaded', () => {
         let scrollTimeout = null;
         
         container.addEventListener('wheel', (e) => {
-            // Handle both horizontal and vertical scroll (convert vertical to horizontal for menu)
-            const delta = Math.abs(e.deltaX) > Math.abs(e.deltaY) ? e.deltaX : e.deltaY;
+            // Only handle horizontal scroll - let vertical scroll work normally for column scrolling
+            const isHorizontalScroll = Math.abs(e.deltaX) > Math.abs(e.deltaY);
+            
+            if (!isHorizontalScroll) {
+                // Allow vertical scrolling within columns
+                return;
+            }
+            
+            const delta = e.deltaX;
             
             if (Math.abs(delta) > 0) {
                 e.preventDefault();

package/package.json

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

package/src/helper/automenu.js

@@ -1,7 +1,9 @@
 import dirTree from "directory-tree";
 import { extname, basename, join, dirname } from "path";
-import { existsSync } from "fs";
+import { existsSync, readFileSync } from "fs";
 import { getFolderConfig, isFolderHidden, getRootConfig } from "./folderConfig.js";
+import { extractMetadata, isMetadataOnly } from "./metadataExtractor.js";
+import { stripHtml } from "./stripHtml.js";
 
 // Icon extensions to check for custom icons
 const ICON_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico'];
@@ -21,6 +23,92 @@ function toDisplayName(filename) {
     .replace(/\b\w/g, c => c.toUpperCase());  // Capitalize first letter of each word
 }
 
+/**
+ * Get the menu label from a file's frontmatter
+ * @param {string} filePath - Path to the markdown file
+ * @returns {string|null} The menu-label value (with HTML stripped), or null if not found
+ */
+function getMenuLabelFromFile(filePath) {
+  try {
+    if (!existsSync(filePath)) return null;
+    const content = readFileSync(filePath, 'utf8');
+    const metadata = extractMetadata(content);
+    if (metadata && metadata['menu-label']) {
+      return stripHtml(String(metadata['menu-label']));
+    }
+  } catch (e) {
+    // Ignore read errors
+  }
+  return null;
+}
+
+/**
+ * Get the menu-sort-as value from a file's frontmatter
+ * @param {string} filePath - Path to the markdown file
+ * @returns {string|null} The menu-sort-as value (with HTML stripped), or null if not found
+ */
+function getMenuSortAsFromFile(filePath) {
+  try {
+    if (!existsSync(filePath)) return null;
+    const content = readFileSync(filePath, 'utf8');
+    const metadata = extractMetadata(content);
+    if (metadata && metadata['menu-sort-as']) {
+      return stripHtml(String(metadata['menu-sort-as']));
+    }
+  } catch (e) {
+    // Ignore read errors
+  }
+  return null;
+}
+
+/**
+ * Get the menu label for a folder from its index.md frontmatter
+ * Falls back to config.json label (deprecated), then display name
+ * @param {string} dirPath - Path to the folder
+ * @param {object|null} folderConfig - The folder's config.json if any
+ * @param {string} baseName - The folder's base name
+ * @returns {string} The label to display
+ */
+function getFolderLabel(dirPath, folderConfig, baseName) {
+  // First, check index.md for menu-label (preferred method)
+  for (const ext of INDEX_EXTENSIONS) {
+    const indexPath = join(dirPath, `index${ext}`);
+    const label = getMenuLabelFromFile(indexPath);
+    if (label) return label;
+  }
+  
+  // Fall back to config.json label (deprecated)
+  if (folderConfig?.label) {
+    return folderConfig.label;
+  }
+  
+  // Default to display name from folder name
+  return toDisplayName(baseName);
+}
+
+/**
+ * Get the sort key for a folder from its index.md frontmatter
+ * @param {string} dirPath - Path to the folder
+ * @returns {string|null} The menu-sort-as value, or null if not found
+ */
+function getFolderSortKey(dirPath) {
+  for (const ext of INDEX_EXTENSIONS) {
+    const indexPath = join(dirPath, `index${ext}`);
+    const sortKey = getMenuSortAsFromFile(indexPath);
+    if (sortKey) return sortKey;
+  }
+  return null;
+}
+
+/**
+ * Check if a file is an index file
+ * @param {string} baseName - The file's base name (without extension)
+ * @returns {boolean} True if this is an index file
+ */
+function isIndexFile(baseName) {
+  return baseName.toLowerCase() === 'index';
+}
+
 function hasIndexFile(dirPath) {
   for (const ext of INDEX_EXTENSIONS) {
     const indexPath = join(dirPath, `index${ext}`);
@@ -165,14 +253,45 @@ function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug =
       continue;
     }
     
+    // Skip metadata-only index files (they only provide folder metadata, not actual pages)
+    if (!hasChildren && isIndexFile(baseName)) {
+      try {
+        const content = readFileSync(item.path, 'utf8');
+        if (isMetadataOnly(content)) {
+          continue; // Skip - this file doesn't produce a page
+        }
+      } catch (e) {
+        // If we can't read it, include it in the menu
+      }
+    }
+    
     // Check if this folder is hidden via config.json
     if (hasChildren && isFolderHidden(item.path, source)) {
       continue; // Skip hidden folders
     }
     
-    // Get folder config for custom label and icon
+    // Get folder config for custom label and icon (deprecated for labels, still used for icons/hidden)
     const folderConfig = hasChildren ? getFolderConfig(item.path) : null;
-    const label = folderConfig?.label || toDisplayName(baseName);
+    
+    // Determine the label - prefer menu-label from frontmatter
+    let label;
+    let sortKey;
+    const isIndex = !hasChildren && isIndexFile(baseName);
+    
+    if (hasChildren) {
+      // For folders, get label from index.md frontmatter, then config.json, then folder name
+      label = getFolderLabel(item.path, folderConfig, baseName);
+      // Get sort key from folder's index.md, fall back to baseName (not transformed label)
+      sortKey = getFolderSortKey(item.path) || baseName;
+    } else {
+      // For files, check frontmatter for menu-label
+      const fileLabel = getMenuLabelFromFile(item.path);
+      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);
+      sortKey = fileSortKey || baseName;
+    }
     
     let rawHref = null;
     let href = null;
@@ -204,10 +323,12 @@ function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug =
     
     const menuItem = {
       label,
+      sortKey, // Used for sorting (menu-sort-as or label)
       path: folderPath,
       href,
       hasChildren,
       icon,
+      isIndex, // Mark index files for special styling and sorting
     };
     
     // Only include debug and inactive fields if requested (for smaller JSON)
@@ -226,11 +347,17 @@ function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug =
     items.push(menuItem);
   }
   
+  // Sort: folders first, then index files, then alphabetically by sortKey
   return items.sort((a, b) => {
+    // Folders always come first
     if (a.hasChildren && !b.hasChildren) return -1;
     if (b.hasChildren && !a.hasChildren) return 1;
-    if (a.label > b.label) return 1;
-    if (a.label < b.label) return -1;
+    // 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;
     return 0;
   });
 }
@@ -280,13 +407,14 @@ function renderMenuLevel(items, level) {
     const hasChildrenClass = item.hasChildren ? ' has-children' : '';
     const hasChildrenIndicator = item.hasChildren ? '<span class="menu-more">⋯</span>' : '';
     const inactiveClass = item.inactive ? ' inactive' : '';
+    const isIndexClass = item.isIndex ? ' is-index' : '';
     
     const labelHtml = item.href
       ? `<a href="${item.href}" class="menu-label${inactiveClass}">${item.label}</a>`
       : `<span class="menu-label">${item.label}</span>`;
     
     return `
-<li class="menu-item${hasChildrenClass}" data-path="${item.path}">
+<li class="menu-item${hasChildrenClass}${isIndexClass}" data-path="${item.path}">
   <div class="menu-item-row">
     ${item.icon}
     ${labelHtml}

package/src/helper/build/autoIndex.js

@@ -1,11 +1,12 @@
 // Auto-index generation helpers for build
-import { existsSync } from "fs";
+import { existsSync, readFileSync } 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";
+import { isMetadataOnly } from "../metadataExtractor.js";
 
 /**
  * Generate automatic index.html files for folders that don't have one
@@ -30,10 +31,23 @@ export async function generateAutoIndices(output, directories, source, templates
   const outputNorm = output.replace(/\/+$/, '');
   
   // Build set of directories that already have an index.html from a source index.md/txt/yml
+  // Exclude metadata-only index files - they should still get auto-generated indices
   const dirsWithSourceIndex = new Set();
   for (const articlePath of generatedArticles) {
     const base = basename(articlePath, extname(articlePath));
     if (base === 'index') {
+      // Check if this is a metadata-only index file
+      try {
+        if (existsSync(articlePath)) {
+          const content = readFileSync(articlePath, 'utf8');
+          if (isMetadataOnly(content)) {
+            // Skip - this folder should still get an auto-index
+            continue;
+          }
+        }
+      } catch (e) {
+        // If we can't read it, assume it has content
+      }
       const dir = dirname(articlePath);
       const outputDir = dir.replace(sourceNorm, outputNorm);
       dirsWithSourceIndex.add(outputDir);

package/src/helper/frontmatterTable.js

@@ -0,0 +1,128 @@
+/**
+ * Convert YAML frontmatter metadata to an HTML table
+ * and inject it into the document body after the first H1
+ */
+
+/**
+ * Convert a metadata value to a displayable string
+ * @param {any} value - The value to convert
+ * @returns {string} The displayable string
+ */
+function formatValue(value) {
+  if (value === null || value === undefined) {
+    return '';
+  }
+  if (Array.isArray(value)) {
+    return value.map(formatValue).join(', ');
+  }
+  if (typeof value === 'object') {
+    // For nested objects, render as a mini definition list
+    return Object.entries(value)
+      .map(([k, v]) => `<strong>${escapeHtml(k)}:</strong> ${escapeHtml(formatValue(v))}`)
+      .join('<br>');
+  }
+  return String(value);
+}
+
+/**
+ * Escape HTML special characters
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string
+ */
+function escapeHtml(str) {
+  if (typeof str !== 'string') return str;
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+/**
+ * Convert a key to a human-readable label
+ * @param {string} key - The metadata key
+ * @returns {string} Human-readable label
+ */
+function formatKey(key) {
+  // Convert camelCase or snake_case to Title Case with spaces
+  return key
+    .replace(/([a-z])([A-Z])/g, '$1 $2') // camelCase
+    .replace(/_/g, ' ') // snake_case
+    .replace(/\b\w/g, c => c.toUpperCase()); // Title Case
+}
+
+/**
+ * Generate an HTML table from metadata object
+ * @param {Object} metadata - The parsed YAML frontmatter
+ * @returns {string} HTML table string
+ */
+export function metadataToTable(metadata) {
+  if (!metadata || typeof metadata !== 'object' || Object.keys(metadata).length === 0) {
+    return '';
+  }
+
+  // Filter out Ursa-internal keys that shouldn't be displayed in the metadata table
+  // These are used by Ursa for rendering/menu behavior, not document metadata
+  const excludeKeys = [
+    'template',       // Specifies which HTML template to use
+    'layout',         // Alternative name for template
+    'draft',          // Marks document as draft (not published)
+    'published',      // Publication status
+    'menu-label',     // Custom label for menu display
+    'menu-sort-as',   // Custom sort key for menu ordering
+  ];
+  const entries = Object.entries(metadata).filter(
+    ([key]) => !excludeKeys.includes(key.toLowerCase())
+  );
+
+  if (entries.length === 0) {
+    return '';
+  }
+
+  const rows = entries.map(([key, value]) => {
+    const formattedValue = formatValue(value);
+    // Don't escape HTML in formatted value since it may contain our formatting
+    return `    <tr>
+      <th>${escapeHtml(formatKey(key))}</th>
+      <td>${formattedValue}</td>
+    </tr>`;
+  }).join('\n');
+
+  return `<table class="frontmatter-table">
+  <tbody>
+${rows}
+  </tbody>
+</table>`;
+}
+
+/**
+ * Inject the frontmatter table into the body HTML after the first H1
+ * If no H1 is present, prepend the table to the body
+ * @param {string} bodyHtml - The rendered body HTML
+ * @param {Object} metadata - The parsed YAML frontmatter
+ * @returns {string} The body HTML with the frontmatter table injected
+ */
+export function injectFrontmatterTable(bodyHtml, metadata) {
+  const table = metadataToTable(metadata);
+  
+  if (!table) {
+    return bodyHtml;
+  }
+
+  // Look for the first closing </h1> tag
+  const h1CloseMatch = bodyHtml.match(/<\/h1>/i);
+  
+  if (h1CloseMatch) {
+    // Insert the table after the first </h1>
+    const insertPosition = h1CloseMatch.index + h1CloseMatch[0].length;
+    return (
+      bodyHtml.slice(0, insertPosition) +
+      '\n' + table + '\n' +
+      bodyHtml.slice(insertPosition)
+    );
+  }
+
+  // No H1 found, prepend the table
+  return table + '\n' + bodyHtml;
+}

package/src/helper/metadataExtractor.js

@@ -18,6 +18,25 @@ export function extractRawMetadata(rawBody) {
   return frontMatter;
 }
 
+/**
+ * Check if a markdown file is "metadata-only" - has frontmatter but no meaningful content
+ * Such files are used only to provide metadata (like menu-label) for folders
+ * @param {string} rawBody - The raw file content
+ * @returns {boolean} True if the file has only frontmatter and no other content
+ */
+export function isMetadataOnly(rawBody) {
+  if (!rawBody) return false;
+  
+  const frontMatter = matchAllFrontMatter(rawBody);
+  if (!frontMatter) return false;
+  
+  // Get content after frontmatter
+  const contentAfter = rawBody.slice(frontMatter.length).trim();
+  
+  // Consider the file metadata-only if there's no content after frontmatter
+  return contentAfter.length === 0;
+}
+
 function matchFrontMatter(str) {
   // Only match YAML front matter at the start of the file
   // Must have --- at line start, content, then closing --- also at line start

package/src/helper/stripHtml.js

@@ -0,0 +1,19 @@
+/**
+ * Strip HTML tags from a string
+ * @param {string} text - The string that may contain HTML
+ * @returns {string} The text with HTML tags removed
+ */
+export function stripHtml(text) {
+  if (!text || typeof text !== 'string') return text;
+  
+  // Remove HTML tags
+  return text
+    .replace(/<[^>]*>/g, '')  // Remove HTML tags
+    .replace(/&lt;/g, '<')     // Decode common HTML entities
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+    .replace(/&quot;/g, '"')
+    .replace(/&#039;/g, "'")
+    .replace(/&nbsp;/g, ' ')
+    .trim();
+}

package/src/jobs/generate.js

@@ -7,7 +7,9 @@ import { isFolderHidden, clearConfigCache } from "../helper/folderConfig.js";
 import {
   extractMetadata,
   extractRawMetadata,
+  isMetadataOnly,
 } from "../helper/metadataExtractor.js";
+import { injectFrontmatterTable } from "../helper/frontmatterTable.js";
 import {
   hashContent,
   loadHashCache,
@@ -279,6 +281,14 @@ export async function generate({
         return;
       }
 
+      // Skip metadata-only index files - they exist only to provide folder metadata
+      // The auto-index system will generate the actual index.html for these folders
+      if (base === 'index' && type === '.md' && isMetadataOnly(rawBody)) {
+        progress.log(`ℹ️  Skipping metadata-only ${shortFile} - auto-index will generate listing`);
+        skippedCount++;
+        return;
+      }
+
       // Check if file needs regeneration
       const needsRegen = _clean || needsRegeneration(file, rawBody, hashCache);
       
@@ -307,13 +317,18 @@ export async function generate({
       // Calculate the document's URL path (e.g., "/character/index.html")
       const docUrlPath = '/' + dir + base + '.html';
 
-      const body = renderFile({
+      let body = renderFile({
         fileContents: rawBody,
         type,
         dirname: dir,
         basename: base,
       });
 
+      // Inject frontmatter table after first H1 (for markdown files with metadata)
+      if (type === '.md' && fileMeta) {
+        body = injectFrontmatterTable(body, fileMeta);
+      }
+
       // Find nearest style.css or _style.css up the tree and copy to output
       // Use cache to avoid repeated filesystem walks for same directory
       let styleLink = "";