@kenjura/ursa 0.81.3 → 0.82.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 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
+
+- bug fix: directory index html files were never being written...impossibly, but there it is
+
 # 0.81.3
 2026-04-14
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.81.3",
+  "version": "0.82.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/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/jobs/generate.js

@@ -1025,7 +1025,7 @@ export async function generate({
 
       // html
       const htmlOutputFilename = dirPath.replace(source, output) + ".html";
-      const indexAlreadyExists = fileExists(htmlOutputFilename);
+      const indexAlreadyExists = await fileExists(htmlOutputFilename);
       if (!indexAlreadyExists) {
         const template = templates["default-template"];
         const indexHtml = `<ul>${pathsInThisDirectory
@@ -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]);