@kenjura/ursa 0.41.0 → 0.44.0

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+# 0.44.0
+2025-12-16
+
+- Added 'sections' metadata property with hierarchical section structure
+
+# 0.43.0
+2025-12-14
+
+- Added buildId and .ursa.json
+- Added full datetime to footer
+- Added commit hash to footer as comment
+
+# 0.42.0
+2025-12-14
+
+- Automenu will now remove dashes from file names
+
 # 0.41.0
 2025-12-13
 

package/package.json

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

package/src/helper/automenu.js

@@ -14,6 +14,13 @@ const HOME_ICON = '🏠';
 // Index file extensions to check for folder links
 const INDEX_EXTENSIONS = ['.md', '.txt', '.yml', '.yaml'];
 
+// Convert filename to display name (e.g., "foo-bar" -> "Foo Bar")
+function toDisplayName(filename) {
+  return filename
+    .replace(/[-_]/g, ' ')  // Replace dashes and underscores with spaces
+    .replace(/\b\w/g, c => c.toUpperCase());  // Capitalize first letter of each word
+}
+
 function hasIndexFile(dirPath) {
   for (const ext of INDEX_EXTENSIONS) {
     const indexPath = join(dirPath, `index${ext}`);
@@ -151,7 +158,7 @@ function buildMenuData(tree, source, validPaths, parentPath = '') {
     
     // Get folder config for custom label and icon
     const folderConfig = hasChildren ? getFolderConfig(item.path) : null;
-    const label = folderConfig?.label || baseName;
+    const label = folderConfig?.label || toDisplayName(baseName);
     
     let rawHref = null;
     if (hasChildren) {

package/src/helper/sectionExtractor.js

@@ -0,0 +1,76 @@
+/**
+ * Extract sections from markdown content based on headings
+ * Creates a hierarchical structure of sections
+ */
+
+/**
+ * Extract sections from markdown content
+ * @param {string} content - The markdown content
+ * @returns {Array} Array of section objects with name and optional children
+ */
+export function extractSections(content) {
+  if (!content) return [];
+  
+  // Match all markdown headings (# to ######)
+  // Handles both "# Heading" and "#Heading" formats
+  const headingRegex = /^(#{1,6})\s*(.+?)$/gm;
+  
+  const headings = [];
+  let match;
+  
+  while ((match = headingRegex.exec(content)) !== null) {
+    const level = match[1].length; // Number of # characters
+    const name = match[2].trim();
+    headings.push({ level, name });
+  }
+  
+  if (headings.length === 0) return [];
+  
+  // Build hierarchical structure
+  return buildSectionTree(headings);
+}
+
+/**
+ * Build a hierarchical tree from flat heading list
+ * @param {Array} headings - Array of {level, name} objects
+ * @returns {Array} Hierarchical section tree
+ */
+function buildSectionTree(headings) {
+  const root = { level: 0, children: [] };
+  const stack = [root];
+  
+  for (const heading of headings) {
+    const section = { name: heading.name, level: heading.level, children: [] };
+    
+    // Pop stack until we find a parent with lower level
+    while (stack.length > 1 && stack[stack.length - 1].level >= heading.level) {
+      stack.pop();
+    }
+    
+    // Add to parent's children
+    const parent = stack[stack.length - 1];
+    parent.children.push(section);
+    
+    // Push this section onto stack (it might have children)
+    stack.push(section);
+  }
+  
+  // Clean up: remove level and empty children arrays
+  cleanupTree(root.children);
+  
+  return root.children;
+}
+
+/**
+ * Remove level property and empty children arrays from the tree
+ */
+function cleanupTree(sections) {
+  for (const section of sections) {
+    delete section.level;
+    if (section.children && section.children.length > 0) {
+      cleanupTree(section.children);
+    } else {
+      delete section.children;
+    }
+  }
+}

package/src/helper/ursaConfig.js

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+
+const CONFIG_FILENAME = '.ursa.json';
+
+/**
+ * Get the path to the .ursa.json config file in the source directory
+ * @param {string} sourceDir - The source directory path
+ * @returns {string} Path to the config file
+ */
+function getConfigPath(sourceDir) {
+  return join(sourceDir, CONFIG_FILENAME);
+}
+
+/**
+ * Load the ursa config from .ursa.json
+ * @param {string} sourceDir - The source directory path
+ * @returns {object} The config object (empty object if file doesn't exist)
+ */
+export function loadUrsaConfig(sourceDir) {
+  const configPath = getConfigPath(sourceDir);
+  try {
+    if (existsSync(configPath)) {
+      const content = readFileSync(configPath, 'utf8');
+      return JSON.parse(content);
+    }
+  } catch (e) {
+    console.error(`Error reading ${CONFIG_FILENAME}: ${e.message}`);
+  }
+  return {};
+}
+
+/**
+ * Save the ursa config to .ursa.json
+ * @param {string} sourceDir - The source directory path
+ * @param {object} config - The config object to save
+ */
+export function saveUrsaConfig(sourceDir, config) {
+  const configPath = getConfigPath(sourceDir);
+  try {
+    const content = JSON.stringify(config, null, 2);
+    writeFileSync(configPath, content, 'utf8');
+  } catch (e) {
+    console.error(`Error writing ${CONFIG_FILENAME}: ${e.message}`);
+  }
+}
+
+/**
+ * Get the current build ID and increment it for the next build
+ * @param {string} sourceDir - The source directory path
+ * @returns {number} The current build ID (starting from 1)
+ */
+export function getAndIncrementBuildId(sourceDir) {
+  const config = loadUrsaConfig(sourceDir);
+  const currentBuildId = config.buildId || 0;
+  const newBuildId = currentBuildId + 1;
+  
+  config.buildId = newBuildId;
+  saveUrsaConfig(sourceDir, config);
+  
+  return newBuildId;
+}

package/src/jobs/generate.js

@@ -20,6 +20,8 @@ import {
   buildValidPaths,
   markInactiveLinks,
 } from "../helper/linkValidator.js";
+import { getAndIncrementBuildId } from "../helper/ursaConfig.js";
+import { extractSections } from "../helper/sectionExtractor.js";
 
 // Helper function to build search index from processed files
 function buildSearchIndex(jsonCache, source, output) {
@@ -128,8 +130,12 @@ export async function generate({
 
   const menu = await getMenu(allSourceFilenames, source, validPaths);
 
+  // Get and increment build ID from .ursa.json
+  const buildId = getAndIncrementBuildId(resolve(_source));
+  console.log(`Build #${buildId}`);
+
   // Generate footer content
-  const footer = await getFooter(source, _source);
+  const footer = await getFooter(source, _source, buildId);
 
   // Load content hash cache from .ursa folder in source directory
   let hashCache = new Map();
@@ -225,12 +231,16 @@ export async function generate({
             dirname: dir,
             basename: base,
           });
+          // Extract sections for markdown files
+          const sections = type === '.md' ? extractSections(rawBody) : [];
+          
           jsonCache.set(file, {
             name: base,
             url,
             contents: rawBody,
             bodyHtml: body,
             metadata: meta,
+            sections,
             transformedMetadata: '',
           });
           return; // Skip regenerating this file
@@ -302,6 +312,10 @@ export async function generate({
         // json
 
         const jsonOutputFilename = outputFilename.replace(".html", ".json");
+        
+        // Extract sections for markdown files
+        const sections = type === '.md' ? extractSections(rawBody) : [];
+        
         const jsonObject = {
           name: base,
           url,
@@ -309,6 +323,7 @@ export async function generate({
           // bodyLessMeta: bodyLessMeta,
           bodyHtml: body,
           metadata: meta,
+          sections,
           transformedMetadata,
           // html: finalHtml,
         };
@@ -551,8 +566,9 @@ function addTrailingSlash(somePath) {
  * Generate footer HTML from footer.md and package.json
  * @param {string} source - resolved source path with trailing slash
  * @param {string} _source - original source path
+ * @param {number} buildId - the current build ID
  */
-async function getFooter(source, _source) {
+async function getFooter(source, _source, buildId) {
   const footerParts = [];
   
   // Try to read footer.md from source root
@@ -607,12 +623,18 @@ async function getFooter(source, _source) {
     console.error(`Error reading ursa package.json: ${e.message}`);
   }
   
-  // Build meta line: version, timestamp, "generated by ursa"
+  // Build meta line: version, build id, timestamp, "generated by ursa"
   const metaParts = [];
   if (docPackage?.version) {
     metaParts.push(`v${docPackage.version}`);
   }
-  metaParts.push(new Date().toISOString().split('T')[0]); // YYYY-MM-DD
+  metaParts.push(`build ${buildId}`);
+  
+  // Full date/time in a readable format
+  const now = new Date();
+  const timestamp = now.toISOString().replace('T', ' ').replace(/\.\d{3}Z$/, ' UTC');
+  metaParts.push(timestamp);
+  
   metaParts.push(`Generated by <a href="https://www.npmjs.com/package/@kenjura/ursa">ursa</a> v${ursaVersion}`);
   
   footerParts.push(`<div class="footer-meta">${metaParts.join(' • ')}</div>`);
@@ -628,5 +650,20 @@ async function getFooter(source, _source) {
     }
   }
   
+  // Try to get git short hash of doc repo (as HTML comment)
+  try {
+    const { execSync } = await import('child_process');
+    const gitHash = execSync('git rev-parse --short HEAD', {
+      cwd: resolve(_source),
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    if (gitHash) {
+      footerParts.push(`<!-- git: ${gitHash} -->`);
+    }
+  } catch (e) {
+    // Not a git repo or git not available - silently skip
+  }
+  
   return footerParts.join('\n');
 }