@kenjura/ursa 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.34.0
+2025-12-11
+
+- Added config.json with folder-specific settings for label, icon, and visibility
+- Root-level config.json can specify open menu items
+
 # 0.33
 2025-12-10
 

package/meta/menu.js

@@ -14,6 +14,17 @@ document.addEventListener('DOMContentLoaded', () => {
         return;
     }
 
+    // Load menu config from embedded JSON (contains openMenuItems)
+    const menuConfigScript = document.getElementById('menu-config');
+    let menuConfig = { openMenuItems: [] };
+    if (menuConfigScript) {
+        try {
+            menuConfig = JSON.parse(menuConfigScript.textContent);
+        } catch (e) {
+            console.error('Failed to parse menu config:', e);
+        }
+    }
+
     // State
     let currentPath = []; // Array of path segments representing current directory
     let expandedLevel1 = new Set(); // Track which level-1 items are expanded
@@ -357,6 +368,21 @@ document.addEventListener('DOMContentLoaded', () => {
         const currentHref = window.location.pathname;
         const pathParts = currentHref.split('/').filter(Boolean);
         
+        // Check if we're on the home/root page
+        const isHomePage = currentHref === '/' || 
+                          currentHref === '/index' || 
+                          currentHref === '/index.html' ||
+                          pathParts.length === 0 ||
+                          (pathParts.length === 1 && pathParts[0].match(/^index(\.html)?$/));
+        
+        // If on home page and we have openMenuItems config, expand those items
+        if (isHomePage && menuConfig.openMenuItems && menuConfig.openMenuItems.length > 0) {
+            for (const itemPath of menuConfig.openMenuItems) {
+                // Add to expanded set - itemPath should be the folder name like "character"
+                expandedLevel1.add(itemPath);
+            }
+        }
+        
         // Try to find the deepest matching folder
         if (pathParts.length > 1) {
             // Navigate to parent folder of current page

package/package.json

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

package/src/helper/automenu.js

@@ -1,6 +1,7 @@
 import dirTree from "directory-tree";
 import { extname, basename, join, dirname } from "path";
 import { existsSync } from "fs";
+import { getFolderConfig, isFolderHidden, getRootConfig } from "./folderConfig.js";
 
 // Icon extensions to check for custom icons
 const ICON_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico'];
@@ -127,12 +128,30 @@ function resolveHref(rawHref, validPaths) {
 function buildMenuData(tree, source, validPaths, parentPath = '') {
   const items = [];
   
+  // Files to hide from menu by default
+  const hiddenFiles = ['config.json', 'style.css'];
+  
   for (const item of tree.children || []) {
     const ext = extname(item.path);
-    const label = basename(item.path, ext);
+    const baseName = basename(item.path, ext);
+    const fileName = basename(item.path);
     const hasChildren = !!item.children;
     const relativePath = item.path.replace(source, '');
-    const folderPath = parentPath ? `${parentPath}/${label}` : label;
+    const folderPath = parentPath ? `${parentPath}/${baseName}` : baseName;
+    
+    // Skip hidden files (config.json, style.css, etc.)
+    if (!hasChildren && hiddenFiles.includes(fileName)) {
+      continue;
+    }
+    
+    // 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
+    const folderConfig = hasChildren ? getFolderConfig(item.path) : null;
+    const label = folderConfig?.label || baseName;
     
     let rawHref = null;
     if (hasChildren) {
@@ -149,6 +168,12 @@ function buildMenuData(tree, source, validPaths, parentPath = '') {
     // Resolve the href and check if target exists
     const { href, inactive, debug } = resolveHref(rawHref, validPaths);
     
+    // Determine icon - custom from config, or custom icon file, or default
+    let icon = getIcon(item, source);
+    if (folderConfig?.icon) {
+      icon = `<span class="menu-icon"><img src="${folderConfig.icon}" alt="${label}" /></span>`;
+    }
+    
     const menuItem = {
       label,
       path: folderPath,
@@ -156,7 +181,7 @@ function buildMenuData(tree, source, validPaths, parentPath = '') {
       inactive,
       debug,
       hasChildren,
-      icon: getIcon(item, source),
+      icon,
     };
     
     if (hasChildren) {
@@ -181,6 +206,10 @@ export async function getAutomenu(source, validPaths) {
   });
   const menuData = buildMenuData(tree, source, validPaths);
   
+  // Get root config for openMenuItems setting
+  const rootConfig = getRootConfig(source);
+  const openMenuItems = rootConfig?.openMenuItems || [];
+  
   // Add home item with resolved href
   const homeResolved = resolveHref('/', validPaths);
   const fullMenuData = [
@@ -191,6 +220,9 @@ export async function getAutomenu(source, validPaths) {
   // Embed the menu data as JSON for JavaScript to use
   const menuDataScript = `<script type="application/json" id="menu-data">${JSON.stringify(fullMenuData)}</script>`;
   
+  // Embed the openMenuItems config as separate JSON
+  const menuConfigScript = `<script type="application/json" id="menu-config">${JSON.stringify({ openMenuItems })}</script>`;
+  
   // Render the breadcrumb header (hidden by default, shown when navigating)
   const breadcrumbHtml = `
 <div class="menu-breadcrumb" style="display: none;">
@@ -202,7 +234,7 @@ export async function getAutomenu(source, validPaths) {
   // Render the initial menu (root level)
   const menuHtml = renderMenuLevel(fullMenuData, 0);
   
-  return `${menuDataScript}${breadcrumbHtml}<ul class="menu-level" data-level="0">${menuHtml}</ul>`;
+  return `${menuDataScript}${menuConfigScript}${breadcrumbHtml}<ul class="menu-level" data-level="0">${menuHtml}</ul>`;
 }
 
 function renderMenuLevel(items, level) {

package/src/helper/folderConfig.js

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+
+const CONFIG_FILENAME = 'config.json';
+
+// Cache for folder configs to avoid repeated file reads
+const configCache = new Map();
+
+/**
+ * Folder configuration schema:
+ * {
+ *   label?: string,       // Custom label for menu display
+ *   icon?: string,        // URL to icon image for menu
+ *   hidden?: boolean,     // If true, hide from menu and don't generate files
+ *   openMenuItems?: string[]  // (root only) Array of folder names to expand by default
+ * }
+ */
+
+/**
+ * Clear the config cache (useful between generation runs)
+ */
+export function clearConfigCache() {
+  configCache.clear();
+}
+
+/**
+ * Read and parse a folder's config.json if it exists (synchronous)
+ * @param {string} folderPath - Absolute path to the folder
+ * @returns {object|null} Parsed config object or null if not found
+ */
+export function getFolderConfig(folderPath) {
+  // Check cache first
+  if (configCache.has(folderPath)) {
+    return configCache.get(folderPath);
+  }
+  
+  const configPath = join(folderPath, CONFIG_FILENAME);
+  try {
+    if (existsSync(configPath)) {
+      const content = readFileSync(configPath, 'utf8');
+      const config = JSON.parse(content);
+      configCache.set(folderPath, config);
+      return config;
+    }
+  } catch (e) {
+    console.warn(`Could not read folder config at ${configPath}:`, e.message);
+  }
+  
+  configCache.set(folderPath, null);
+  return null;
+}
+
+/**
+ * Get the root folder's config
+ * @param {string} sourceRoot - The source root directory
+ * @returns {object|null} Config object or null
+ */
+export function getRootConfig(sourceRoot) {
+  return getFolderConfig(sourceRoot.replace(/\/$/, ''));
+}
+
+/**
+ * Check if a folder or any of its ancestors is hidden via config.json
+ * @param {string} folderPath - Absolute path to check
+ * @param {string} sourceRoot - The source root directory (stop checking at this level)
+ * @returns {boolean} True if this folder should be hidden
+ */
+export function isFolderHidden(folderPath, sourceRoot) {
+  let currentPath = folderPath.replace(/\/$/, '');
+  
+  // Normalize source root for comparison
+  const normalizedRoot = sourceRoot.replace(/\/$/, '');
+  
+  while (currentPath.length >= normalizedRoot.length) {
+    const config = getFolderConfig(currentPath);
+    if (config?.hidden === true) {
+      return true;
+    }
+    
+    // Move to parent directory
+    const parentPath = dirname(currentPath);
+    if (parentPath === currentPath) break; // Reached filesystem root
+    currentPath = parentPath;
+  }
+  
+  return false;
+}

package/src/jobs/generate.js

@@ -4,6 +4,7 @@ import { copyFile, mkdir, readdir, readFile, stat } from "fs/promises";
 import { getAutomenu } from "../helper/automenu.js";
 import { filterAsync } from "../helper/filterAsync.js";
 import { isDirectory } from "../helper/isDirectory.js";
+import { isFolderHidden, clearConfigCache } from "../helper/folderConfig.js";
 import {
   extractMetadata,
   extractRawMetadata,
@@ -101,16 +102,25 @@ export async function generate({
   const templates = await getTemplates(meta); // todo: error if no default template
   // console.log({ templates });
 
+  // Clear config cache at start of generation to pick up any changes
+  clearConfigCache();
+
+  // Helper to check if a path is inside a config-hidden folder
+  const isInHiddenFolder = (filePath) => {
+    const dir = dirname(filePath);
+    return isFolderHidden(dir, source);
+  };
+
   // read all articles, process them, copy them to build
   const articleExtensions = /\.(md|txt|yml)/;
   const hiddenOrSystemDirs = /[\/\\]\.(?!\.)|[\/\\]node_modules[\/\\]/;  // Matches hidden folders (starting with .) or node_modules
   const allSourceFilenamesThatAreArticles = allSourceFilenames.filter(
-    (filename) => filename.match(articleExtensions) && !filename.match(hiddenOrSystemDirs)
+    (filename) => filename.match(articleExtensions) && !filename.match(hiddenOrSystemDirs) && !isInHiddenFolder(filename)
   );
   const allSourceFilenamesThatAreDirectories = (await filterAsync(
     allSourceFilenames,
     (filename) => isDirectory(filename)
-  )).filter((filename) => !filename.match(hiddenOrSystemDirs));
+  )).filter((filename) => !filename.match(hiddenOrSystemDirs) && !isFolderHidden(filename, source));
 
   // Build set of valid internal paths for link validation (must be before menu)
   const validPaths = buildValidPaths(allSourceFilenamesThatAreArticles, source);
@@ -363,7 +373,7 @@ export async function generate({
   );
 
   // copy all static files (i.e. images)
-  const imageExtensions = /\.(jpg|png|gif|webp)/; // todo: handle-extensionless images...ugh
+  const imageExtensions = /\.(jpg|jpeg|png|gif|webp|svg|ico)/; // static asset extensions
   const allSourceFilenamesThatAreImages = allSourceFilenames.filter(
     (filename) => filename.match(imageExtensions)
   );

package/src/serve.js

@@ -48,7 +48,15 @@ export async function serve({
 
   // Source changes use incremental mode (only regenerate changed files)
   // Exception: CSS changes require full rebuild since they're embedded in all pages
-  watch(sourceDir, { recursive: true, filter: /\.(js|json|css|html|md|txt|yml|yaml)$/ }, async (evt, name) => {
+  watch(sourceDir, { 
+    recursive: true, 
+    filter: (f, skip) => {
+      // Skip .ursa folder (contains hash cache that gets updated during generation)
+      if (/[\/\\]\.ursa[\/\\]?/.test(f)) return skip;
+      // Only watch relevant file types
+      return /\.(js|json|css|html|md|txt|yml|yaml)$/.test(f);
+    }
+  }, async (evt, name) => {
     console.log(`Source files changed! Event: ${evt}, File: ${name}`);
     
     // CSS files affect all pages (embedded styles), so trigger full rebuild