@kenjura/ursa 0.81.4 → 0.83.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+
+# 0.83.0
+2026-05-07
+
+- **New `--promote-changelog=<file.md>` option** for the `generate` and `serve` commands. When supplied, the named markdown (or .mdx) file is staged into the source root for the duration of the build, so it is rendered by the normal Ursa pipeline and ends up in the output root as a sibling of the main `index.html`. The staged copy is removed after the build completes (or when the serve process exits via SIGINT/SIGTERM). If a file with the same basename already exists in the source root, no staging is performed and a warning is logged.
+- **Search UI fix**: clicking a search suggestion (or selecting one with Enter) now hides the search results dropdown immediately. Previously the dropdown could remain visible when navigation did not trigger a fresh page load (e.g. same-page anchor links, or restoration from the browser's back/forward cache). Also added a `pageshow` listener that hides results when the page is restored from bfcache.
+- **Search UI fully collapses after navigation**: clicking a search suggestion (in either the inline search dropdown or the search widget panel) now also closes the search widget panel and clears the search input, mirroring the effect of clicking the search icon a second time. The input is also cleared when the page is restored from the browser's back/forward cache.
+# 0.82.0
+2026-05-06
+
+- **Frontmatter table is now opt-in**: The HTML frontmatter table that was previously injected into every Markdown/MDX document after the first H1 is now only rendered when the document's frontmatter sets `render-frontmatter: true` (boolean `true` or string `"true"`). Documents without the flag (or with it set to `false`) no longer have the table injected. The `render-frontmatter` key itself is excluded from the rendered table.
+
 # 0.81.4
 2026-05-04
 

package/bin/ursa.js

@@ -5,6 +5,7 @@ import { hideBin } from 'yargs/helpers';
 import { generate } from '../src/jobs/generate.js';
 import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import { stagePromotedChangelog, registerCleanupOnExit } from '../src/helper/promoteChangelog.js';
 
 // Get the directory where ursa is installed
 const __filename = fileURLToPath(import.meta.url);
@@ -48,6 +49,10 @@ yargs(hideBin(process.argv))
           describe: 'Ignore cached hashes and regenerate all files',
           type: 'boolean',
           default: false
+        })
+        .option('promote-changelog', {
+          describe: 'Path to a markdown file to render at the output root (sibling of index.html)',
+          type: 'string'
         });
     },
     async (argv) => {
@@ -57,6 +62,7 @@ yargs(hideBin(process.argv))
       const whitelist = argv.whitelist ? resolve(argv.whitelist) : null;
       const exclude = argv.exclude || null;
       const clean = argv.clean;
+      const promoteChangelog = argv['promote-changelog'] || null;
       
       console.log(`Generating site from ${source} to ${output} using meta from ${meta}`);
       if (whitelist) {
@@ -69,7 +75,9 @@ yargs(hideBin(process.argv))
         console.log(`Clean build: ignoring cached hashes`);
       }
       
+      let promoted = { stagedFile: null, cleanup: async () => {} };
       try {
+        promoted = await stagePromotedChangelog({ changelogPath: promoteChangelog, sourceDir: source });
         await generate({
           _source: source,
           _meta: meta,
@@ -82,6 +90,8 @@ yargs(hideBin(process.argv))
       } catch (error) {
         console.error('Error generating site:', error.message);
         process.exit(1);
+      } finally {
+        await promoted.cleanup();
       }
     }
   )
@@ -127,6 +137,10 @@ yargs(hideBin(process.argv))
           describe: 'Ignore cached hashes and regenerate all files',
           type: 'boolean',
           default: false
+        })
+        .option('promote-changelog', {
+          describe: 'Path to a markdown file to render at the output root (sibling of index.html)',
+          type: 'string'
         });
     },
     async (argv) => {
@@ -137,6 +151,7 @@ yargs(hideBin(process.argv))
       const whitelist = argv.whitelist ? resolve(argv.whitelist) : null;
       const exclude = argv.exclude || null;
       const clean = argv.clean;
+      const promoteChangelog = argv['promote-changelog'] || null;
       
       console.log(`Starting development server...`);
       console.log(`Source: ${source}`);
@@ -151,6 +166,8 @@ yargs(hideBin(process.argv))
       }
       
       try {
+        const promoted = await stagePromotedChangelog({ changelogPath: promoteChangelog, sourceDir: source });
+        registerCleanupOnExit(promoted.cleanup);
         const { serve } = await import('../src/serve.js');
         await serve({
           _source: source,

package/meta/templates/default-template/search.js

@@ -590,6 +590,27 @@ class GlobalSearch {
   }
   
   navigateToResult(result) {
+    // Hide the results dropdown immediately. This handles cases where the
+    // navigation does not trigger a fresh page load (e.g. same-page anchor
+    // links, or restoration from the browser's back/forward cache).
+    this.hideResults();
+    // Also close the search widget panel (if any) so the search UI fully
+    // collapses, mirroring the effect of clicking the search icon again.
+    if (window.widgetManager && typeof window.widgetManager.close === 'function') {
+      try {
+        const side = window.widgetManager.getSide
+          ? window.widgetManager.getSide('search')
+          : undefined;
+        window.widgetManager.close(side);
+      } catch {
+        // ignore — best effort
+      }
+    }
+    // Clear the search input so the field is empty when the user reopens it.
+    if (this.searchInput) {
+      this.searchInput.value = '';
+      this.updateClearButtonVisibility();
+    }
     if (result.url) {
       window.location.href = result.url;
     } else if (result.path) {
@@ -601,4 +622,21 @@ class GlobalSearch {
 // Initialize when DOM is loaded
 document.addEventListener('DOMContentLoaded', () => {
   window.globalSearch = new GlobalSearch();
+});
+
+// Also hide search results if the page is restored from the browser's
+// back/forward cache (bfcache). Without this, the search dropdown can
+// appear "stuck" open after returning to a previous page.
+window.addEventListener('pageshow', () => {
+  if (window.globalSearch && typeof window.globalSearch.hideResults === 'function') {
+    window.globalSearch.hideResults();
+  }
+  // Also clear the search input on bfcache restore so the field doesn't
+  // appear pre-populated with the previous query.
+  if (window.globalSearch && window.globalSearch.searchInput) {
+    window.globalSearch.searchInput.value = '';
+    if (typeof window.globalSearch.updateClearButtonVisibility === 'function') {
+      window.globalSearch.updateClearButtonVisibility();
+    }
+  }
 });

package/meta/templates/default-template/widgets.js

@@ -464,6 +464,19 @@ class WidgetManager {
     item.appendChild(path);
     
     item.addEventListener('click', () => {
+      // Close the search widget panel before navigating, so it isn't left
+      // open when the new page loads (or when a same-page anchor link
+      // doesn't trigger a fresh page load at all).
+      const side = this.getSide('search');
+      // Clear the widget search input so the field is empty next time the
+      // user opens the search panel.
+      if (this._widgetSearchInput) {
+        this._widgetSearchInput.value = '';
+      }
+      if (this._widgetSearchResults) {
+        this._widgetSearchResults.innerHTML = '';
+      }
+      this.close(side);
       window.location.href = result.url || result.path;
     });
     

package/package.json

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

package/src/helper/__test__/frontmatterTable.test.js

@@ -0,0 +1,88 @@
+import {
+  metadataToTable,
+  injectFrontmatterTable,
+  isRenderFrontmatterEnabled,
+} from "../frontmatterTable.js";
+
+describe("isRenderFrontmatterEnabled", () => {
+  it("returns false for missing metadata", () => {
+    expect(isRenderFrontmatterEnabled(null)).toBe(false);
+    expect(isRenderFrontmatterEnabled(undefined)).toBe(false);
+    expect(isRenderFrontmatterEnabled({})).toBe(false);
+  });
+  it("returns false when flag is missing", () => {
+    expect(isRenderFrontmatterEnabled({ title: "Foo" })).toBe(false);
+  });
+  it("returns false when flag is false", () => {
+    expect(isRenderFrontmatterEnabled({ "render-frontmatter": false })).toBe(false);
+  });
+  it("returns true when flag is boolean true", () => {
+    expect(isRenderFrontmatterEnabled({ "render-frontmatter": true })).toBe(true);
+  });
+  it("returns true when flag is the string 'true'", () => {
+    expect(isRenderFrontmatterEnabled({ "render-frontmatter": "true" })).toBe(true);
+  });
+});
+
+describe("injectFrontmatterTable", () => {
+  const body = "<h1>Title</h1>\n<p>Body</p>";
+
+  it("does not inject when render-frontmatter flag is missing", () => {
+    const result = injectFrontmatterTable(body, { type: "power", cost: 3 });
+    expect(result).toBe(body);
+    expect(result).not.toContain("frontmatter-table");
+  });
+
+  it("does not inject when render-frontmatter is false", () => {
+    const result = injectFrontmatterTable(body, {
+      "render-frontmatter": false,
+      type: "power",
+    });
+    expect(result).toBe(body);
+  });
+
+  it("injects table after first H1 when render-frontmatter is true", () => {
+    const result = injectFrontmatterTable(body, {
+      "render-frontmatter": true,
+      type: "power",
+      cost: 3,
+    });
+    expect(result).toContain('<table class="frontmatter-table">');
+    expect(result).toContain("<th>Type</th>");
+    expect(result).toContain("<td>power</td>");
+    // Table appears after the </h1>
+    expect(result.indexOf("</h1>")).toBeLessThan(result.indexOf("frontmatter-table"));
+  });
+
+  it("accepts string 'true' for the flag", () => {
+    const result = injectFrontmatterTable(body, {
+      "render-frontmatter": "true",
+      type: "power",
+    });
+    expect(result).toContain('<table class="frontmatter-table">');
+  });
+
+  it("does not include render-frontmatter itself as a row", () => {
+    const result = injectFrontmatterTable(body, {
+      "render-frontmatter": true,
+      type: "power",
+    });
+    expect(result).not.toContain(">Render Frontmatter<");
+  });
+
+  it("returns body unchanged when no displayable entries exist", () => {
+    const result = injectFrontmatterTable(body, {
+      "render-frontmatter": true,
+      title: "ignored",
+    });
+    expect(result).toBe(body);
+  });
+});
+
+describe("metadataToTable", () => {
+  it("still produces a table when called directly (used by other consumers)", () => {
+    const html = metadataToTable({ type: "power", cost: 3 });
+    expect(html).toContain('<table class="frontmatter-table">');
+    expect(html).toContain("<th>Type</th>");
+  });
+});

package/src/helper/__test__/promoteChangelog.test.js

@@ -0,0 +1,94 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { jest } from '@jest/globals';
+import { stagePromotedChangelog } from '../promoteChangelog.js';
+
+let tmpDir;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ursa-promote-changelog-'));
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+describe('stagePromotedChangelog', () => {
+  it('is a no-op when no changelogPath is provided', async () => {
+    const sourceDir = path.join(tmpDir, 'src');
+    await fs.mkdir(sourceDir);
+    const result = await stagePromotedChangelog({ changelogPath: null, sourceDir });
+    expect(result.stagedFile).toBe(null);
+    const entries = await fs.readdir(sourceDir);
+    expect(entries).toEqual([]);
+  });
+
+  it('throws when the source file does not exist', async () => {
+    const sourceDir = path.join(tmpDir, 'src');
+    await fs.mkdir(sourceDir);
+    await expect(
+      stagePromotedChangelog({
+        changelogPath: path.join(tmpDir, 'missing.md'),
+        sourceDir,
+      })
+    ).rejects.toThrow(/cannot read file/);
+  });
+
+  it('copies the file into the source root using its basename', async () => {
+    const sourceDir = path.join(tmpDir, 'src');
+    await fs.mkdir(sourceDir);
+    const cl = path.join(tmpDir, 'CHANGELOG.md');
+    await fs.writeFile(cl, '# Hello\n');
+
+    const result = await stagePromotedChangelog({ changelogPath: cl, sourceDir });
+
+    expect(result.stagedFile).toBe(path.join(sourceDir, 'CHANGELOG.md'));
+    const staged = await fs.readFile(result.stagedFile, 'utf8');
+    expect(staged).toBe('# Hello\n');
+  });
+
+  it('cleanup removes the staged file', async () => {
+    const sourceDir = path.join(tmpDir, 'src');
+    await fs.mkdir(sourceDir);
+    const cl = path.join(tmpDir, 'CHANGELOG.md');
+    await fs.writeFile(cl, '# Hello\n');
+
+    const result = await stagePromotedChangelog({ changelogPath: cl, sourceDir });
+    await result.cleanup();
+
+    await expect(fs.access(result.stagedFile)).rejects.toThrow();
+  });
+
+  it('cleanup is idempotent', async () => {
+    const sourceDir = path.join(tmpDir, 'src');
+    await fs.mkdir(sourceDir);
+    const cl = path.join(tmpDir, 'CHANGELOG.md');
+    await fs.writeFile(cl, '# Hello\n');
+
+    const result = await stagePromotedChangelog({ changelogPath: cl, sourceDir });
+    await result.cleanup();
+    await expect(result.cleanup()).resolves.toBeUndefined();
+  });
+
+  it('refuses to clobber an existing file in the source root', async () => {
+    const sourceDir = path.join(tmpDir, 'src');
+    await fs.mkdir(sourceDir);
+    const existing = path.join(sourceDir, 'CHANGELOG.md');
+    await fs.writeFile(existing, '# Original\n');
+    const cl = path.join(tmpDir, 'CHANGELOG.md');
+    await fs.writeFile(cl, '# Promoted\n');
+
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const result = await stagePromotedChangelog({ changelogPath: cl, sourceDir });
+      expect(result.stagedFile).toBe(null);
+      // Existing file untouched
+      const content = await fs.readFile(existing, 'utf8');
+      expect(content).toBe('# Original\n');
+      expect(warn).toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});

package/src/helper/frontmatterTable.js

@@ -3,6 +3,18 @@
  * and inject it into the document body after the first H1
  */
 
+/**
+ * Determine whether the document's frontmatter opts in to rendering
+ * the frontmatter table. Accepts boolean true or the string "true".
+ * @param {Object} metadata
+ * @returns {boolean}
+ */
+export function isRenderFrontmatterEnabled(metadata) {
+  if (!metadata || typeof metadata !== 'object') return false;
+  const value = metadata['render-frontmatter'];
+  return value === true || value === 'true';
+}
+
 /**
  * Convert a metadata value to a displayable string
  * @param {any} value - The value to convert
@@ -75,7 +87,8 @@ export function metadataToTable(metadata) {
     'generate-auto-index', // Auto-indexing control
     'auto-index-depth',    // Auto-indexing depth
     'auto-index-position', // Auto-indexing position
-    'hydrate'         // MDX hydration control
+    'hydrate',        // MDX hydration control
+    'render-frontmatter' // Opt-in flag controlling whether this table is rendered
   ];
   const entries = Object.entries(metadata).filter(
     ([key]) => !excludeKeys.includes(key.toLowerCase())
@@ -109,8 +122,14 @@ ${rows}
  * @returns {string} The body HTML with the frontmatter table injected
  */
 export function injectFrontmatterTable(bodyHtml, metadata) {
+  // Opt-in: only render the frontmatter table when the document explicitly
+  // sets `render-frontmatter: true` in its frontmatter.
+  if (!metadata || !isRenderFrontmatterEnabled(metadata)) {
+    return bodyHtml;
+  }
+
   const table = metadataToTable(metadata);
-  
+
   if (!table) {
     return bodyHtml;
   }

package/src/helper/promoteChangelog.js

@@ -0,0 +1,107 @@
+/**
+ * Promote-changelog helper.
+ *
+ * Implements the `--promote-changelog=<file.md>` CLI option for `generate`
+ * and `serve`. The named markdown (or .mdx) file is staged into the source
+ * root before the build runs, so that it is rendered by the normal Ursa
+ * pipeline and ends up in the output root as a sibling of the main
+ * `index.html`. Once the build finishes (or the serve process exits) the
+ * staged copy is removed, leaving the source tree untouched.
+ *
+ * Behavior:
+ *   - If no `--promote-changelog` value is provided, this is a no-op.
+ *   - The staged filename is the basename of the supplied path (e.g.
+ *     `CHANGELOG.md` becomes `<source>/CHANGELOG.md`).
+ *   - If a file with the same basename already exists in the source root,
+ *     no staging is performed and the existing file is left in place. A
+ *     warning is logged so the user can resolve the conflict.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Stage a changelog file into the source root.
+ *
+ * @param {Object} args
+ * @param {string|null|undefined} args.changelogPath - Path supplied via --promote-changelog.
+ * @param {string} args.sourceDir - Resolved absolute path to the source directory.
+ * @returns {Promise<{ stagedFile: string|null, cleanup: () => Promise<void> }>}
+ */
+export async function stagePromotedChangelog({ changelogPath, sourceDir }) {
+  const noop = { stagedFile: null, cleanup: async () => {} };
+  if (!changelogPath) return noop;
+
+  const absolute = path.resolve(changelogPath);
+  let content;
+  try {
+    content = await fs.readFile(absolute, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `--promote-changelog: cannot read file at ${absolute}: ${err.message}`
+    );
+  }
+
+  const baseName = path.basename(absolute);
+  const stagedFile = path.join(sourceDir, baseName);
+
+  // Refuse to clobber an existing file in the source root.
+  let alreadyExists = false;
+  try {
+    await fs.access(stagedFile);
+    alreadyExists = true;
+  } catch {
+    // expected when the file does not exist
+  }
+
+  if (alreadyExists) {
+    console.warn(
+      `--promote-changelog: a file already exists at ${stagedFile}; leaving it in place.`
+    );
+    return noop;
+  }
+
+  await fs.writeFile(stagedFile, content);
+  console.log(`--promote-changelog: staged ${absolute} -> ${stagedFile}`);
+
+  let cleanedUp = false;
+  const cleanup = async () => {
+    if (cleanedUp) return;
+    cleanedUp = true;
+    try {
+      await fs.unlink(stagedFile);
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        console.warn(
+          `--promote-changelog: failed to remove staged file ${stagedFile}: ${err.message}`
+        );
+      }
+    }
+  };
+
+  return { stagedFile, cleanup };
+}
+
+/**
+ * Register process-exit handlers that invoke the given cleanup function.
+ * Used by long-running commands (serve, dev) so the staged file is removed
+ * even when the user stops the process with Ctrl-C.
+ *
+ * @param {() => Promise<void>} cleanup
+ */
+export function registerCleanupOnExit(cleanup) {
+  if (!cleanup) return;
+  let triggered = false;
+  const run = (exitCode) => {
+    if (triggered) return;
+    triggered = true;
+    Promise.resolve(cleanup())
+      .catch(() => {})
+      .finally(() => {
+        if (typeof exitCode === 'number') process.exit(exitCode);
+      });
+  };
+  process.once('exit', () => run());
+  process.once('SIGINT', () => run(130));
+  process.once('SIGTERM', () => run(143));
+}

package/src/jobs/generate.js

@@ -1583,7 +1583,24 @@ export async function regenerateSingleFile(changedFile, {
     const xmlOutputFilename = outputFilename.replace(".html", ".xml");
     const xml = `<article>${o2x(jsonObject)}</article>`;
     await outputFile(xmlOutputFilename, xml);
-    
+
+    // Folder-named index promotion (mirrors autoIndex behavior on full builds):
+    // If the file is named like its parent folder (e.g. aletheia/aletheia.md) and
+    // no explicit index.{md,mdx,txt,yml,html} exists alongside it, also write the
+    // same outputs to <dir>/index.html|json|xml so the canonical URL stays fresh.
+    const sourceDirOfFile = dirname(changedFile);
+    const parentFolderName = basename(sourceDirOfFile);
+    if (base && parentFolderName && base === parentFolderName) {
+      const hasExplicitIndex = ['index.md', 'index.mdx', 'index.txt', 'index.yml', 'index.html']
+        .some(name => existsSync(join(sourceDirOfFile, name)));
+      if (!hasExplicitIndex) {
+        const outDirOfFile = dirname(outputFilename);
+        await outputFile(join(outDirOfFile, 'index.html'), finalHtml);
+        await outputFile(join(outDirOfFile, 'index.json'), json);
+        await outputFile(join(outDirOfFile, 'index.xml'), xml);
+      }
+    }
+
     // Update hash cache
     updateHash(changedFile, rawBody, hashCache);
     

package/src/serve.js

@@ -69,6 +69,30 @@ function docPathToUrl(docPath, sourceDir) {
   return normalizeUrl(rawUrl);
 }
 
+/**
+ * Return all URL paths a source file maps to. Most files map to a single URL,
+ * but folder-named files (e.g. aletheia/aletheia.md) are promoted to
+ * <folder>/index.html during the build, so they also serve the folder URL.
+ * @param {string} docPath - Absolute source path
+ * @param {string} sourceDir - Absolute source directory (with trailing slash)
+ * @returns {string[]} Normalized URL paths
+ */
+function docPathToUrls(docPath, sourceDir) {
+  const urls = [docPathToUrl(docPath, sourceDir)];
+  const ext = docPath.match(/\.(md|mdx|txt|yml|yaml)$/);
+  if (ext) {
+    const base = basename(docPath, ext[0]);
+    const parent = basename(dirname(docPath));
+    if (base && parent && base === parent) {
+      // Folder-named file → also serves the folder's index URL
+      const folderUrl = normalizeUrl('/' + dirname(docPath).replace(
+        sourceDir.endsWith('/') ? sourceDir : sourceDir + '/', '') + '/');
+      if (!urls.includes(folderUrl)) urls.push(folderUrl);
+    }
+  }
+  return urls;
+}
+
 /**
  * Broadcast a message to all connected WebSocket clients.
  * @param {object} messageObj - Object to JSON.stringify and send
@@ -573,10 +597,12 @@ export async function serve({
         const affectedUrlSet = new Set();
 
         for (const docPath of docPathsArray) {
-          const url = docPathToUrl(docPath, sourceDir + '/');
-          affectedUrlSet.add(url);
-          if (viewedUrls.includes(url)) {
-            priorityPaths.push(docPath);
+          const urls = docPathToUrls(docPath, sourceDir + '/');
+          for (const url of urls) {
+            affectedUrlSet.add(url);
+            if (viewedUrls.includes(url) && !priorityPaths.includes(docPath)) {
+              priorityPaths.push(docPath);
+            }
           }
         }
 
@@ -599,7 +625,7 @@ export async function serve({
           onPriorityComplete: ({ regenerated, failed, priorityDocs }) => {
             if (regenerated > 0) {
               // Immediately reload clients whose pages are now ready
-              const readyUrls = new Set(priorityDocs.map(p => docPathToUrl(p, sourceDir + '/')));
+              const readyUrls = new Set(priorityDocs.flatMap(p => docPathToUrls(p, sourceDir + '/')));
               console.log(`⚡ Priority complete: ${regenerated} OK, ${failed} failed → reloading clients`);
               reloadAffectedClients(readyUrls, uniqueNames[0]);
             } else if (failed > 0) {
@@ -610,7 +636,7 @@ export async function serve({
 
         // After all remaining docs are done, reload any remaining affected clients
         // (non-priority clients that weren't reloaded during onPriorityComplete)
-        const priorityUrlSet = new Set(priorityPaths.map(p => docPathToUrl(p, sourceDir + '/')));
+        const priorityUrlSet = new Set(priorityPaths.flatMap(p => docPathToUrls(p, sourceDir + '/')));
         const remainingUrls = new Set([...affectedUrlSet].filter(u => !priorityUrlSet.has(u)));
         if (remainingUrls.size > 0) {
           reloadAffectedClients(remainingUrls, uniqueNames[0]);