@kenjura/ursa 0.90.1 → 0.95.0

package/src/helper/breadcrumbs.js

@@ -1,4 +1,6 @@
-import { toTitleCase } from "./build/titleCase.js";
+import { join } from "path";
+import { getFolderConfig } from "./folderConfig.js";
+import { toDisplayName, getFolderLabel } from "./menuLabels.js";
 
 /**
  * Generate breadcrumb navigation HTML from a document's path.
@@ -6,9 +8,12 @@ import { toTitleCase } from "./build/titleCase.js";
  * @param {string} dir  - Directory relative to source root, e.g. "settings/eberron/" or "/"
  * @param {string} base - Filename without extension, e.g. "index" or "places"
  * @param {object} [fileMeta] - Parsed frontmatter (used for current-page label override)
+ * @param {string|null} [sourceRoot] - Absolute path of the docroot. With it, folder
+ *   segments are named the way the menu names them (`menu-label` frontmatter, then
+ *   config.json `label`); without it they fall back to the prettified folder name.
  * @returns {string} Breadcrumb HTML string, or empty string if not applicable
  */
-export function generateBreadcrumbs(dir, base, fileMeta) {
+export function generateBreadcrumbs(dir, base, fileMeta, sourceRoot = null) {
   const segments = dir.split('/').filter(Boolean);
   const isIndexFile = (base === 'index' || base === 'home');
 
@@ -25,10 +30,20 @@ export function generateBreadcrumbs(dir, base, fileMeta) {
     const seg = allSegments[i];
     const isLast = i === allSegments.length - 1;
 
-    // Current page can use frontmatter title; others use title-cased folder name
-    const label = isLast && fileMeta?.title
-      ? fileMeta.title
-      : toTitleCase(seg);
+    // Every segment but the last is a folder, and so is the last one when this
+    // is a folder's index page. Those get the menu's label. The last segment of
+    // a regular document is the document itself, which keeps its own
+    // frontmatter override.
+    const isFolderSegment = !isLast || isIndexFile;
+    let label;
+    if (isLast && !isFolderSegment) {
+      label = fileMeta?.['menu-label'] || fileMeta?.title || toDisplayName(seg);
+    } else if (sourceRoot) {
+      const folderPath = join(sourceRoot, ...allSegments.slice(0, i + 1));
+      label = getFolderLabel(folderPath, getFolderConfig(folderPath), seg);
+    } else {
+      label = toDisplayName(seg);
+    }
 
     if (isLast) {
       parts.push(`<span class="breadcrumb-current" aria-current="page">${label}</span>`);

package/src/helper/build/__test__/autoIndex.test.js

@@ -2,7 +2,8 @@ import { join } from "path";
 import { mkdtemp, mkdir, writeFile, rm, readFile } from "fs/promises";
 import { existsSync } from "fs";
 import { tmpdir } from "os";
-import { generateAutoIndices } from "../autoIndex.js";
+import { generateAutoIndices, generateAutoIndexHtmlFromSource } from "../autoIndex.js";
+import { clearConfigCache } from "../../folderConfig.js";
 
 let tempDir;
 let source;
@@ -93,3 +94,136 @@ describe("generateAutoIndices with empty source folders", () => {
     expect(rootIndex).toContain('<a href="docs/index.html">');
   });
 });
+
+describe("auto-index naming matches the automenu", () => {
+  it("uses menu-label from a folder's index frontmatter, and config.json when there is no index", async () => {
+    // bnw has a real index.md carrying the label; hfr has no index at all, so
+    // it falls back to config.json — the same two-step the automenu uses.
+    await mkdir(join(source, "bnw"));
+    await writeFile(
+      join(source, "bnw", "index.md"),
+      "---\nmenu-label: 'BNW - Brave New World'\n---\n"
+    );
+    await writeFile(join(source, "bnw", "quests.md"), "# Quests\n");
+    await mkdir(join(source, "hfr"));
+    await writeFile(
+      join(source, "hfr", "config.json"),
+      JSON.stringify({ label: "HFR - Hyacinth: Fury Road" })
+    );
+    await writeFile(join(source, "hfr", "hfr.md"), "# Hyacinth\n");
+
+    const html = await generateAutoIndexHtmlFromSource(source, 1);
+
+    expect(html).toContain('<a href="bnw/index.html">BNW - Brave New World</a>');
+    expect(html).toContain('<a href="hfr/index.html">HFR - Hyacinth: Fury Road</a>');
+  });
+
+  it("uses menu-label on individual documents and menu-sort-as for ordering", async () => {
+    await writeFile(
+      join(source, "zebra.md"),
+      "---\nmenu-label: 'ZED - Zebra'\nmenu-sort-as: 'aardvark'\n---\n# Zebra\n"
+    );
+    await writeFile(join(source, "middle.md"), "# Middle\n");
+
+    const html = await generateAutoIndexHtmlFromSource(source, 1);
+
+    expect(html).toContain('<a href="zebra.html">ZED - Zebra</a>');
+    // Sorted by menu-sort-as ("aardvark"), not by filename ("zebra")
+    expect(html.indexOf("ZED - Zebra")).toBeLessThan(html.indexOf("Middle"));
+  });
+
+  it("preserves interior capitalization instead of title-casing it away", async () => {
+    await mkdir(join(source, "SoL"));
+    await writeFile(join(source, "SoL", "notes.md"), "# Notes\n");
+
+    const html = await generateAutoIndexHtmlFromSource(source, 1);
+
+    expect(html).toContain('<a href="SoL/index.html">SoL</a>');
+  });
+
+  it("labels generated index pages with the folder's menu-label", async () => {
+    // No index.md content, so this folder gets an auto-generated index.html;
+    // its <h1> should use the label rather than the raw folder name.
+    await mkdir(join(source, "bnw"));
+    await writeFile(
+      join(source, "bnw", "config.json"),
+      JSON.stringify({ label: "BNW - Brave New World" })
+    );
+    await writeFile(join(source, "bnw", "quests.md"), "# Quests\n");
+    await mkdir(join(output, "bnw"));
+    await writeFile(join(output, "bnw", "quests.html"), "<html><body>Quests</body></html>");
+
+    await runAutoIndices([join(source, "bnw")], [join(source, "bnw", "quests.md")], makeProgress());
+
+    const bnwIndex = await readFile(join(output, "bnw", "index.html"), "utf8");
+    expect(bnwIndex).toContain("<h1>BNW - Brave New World</h1>");
+    const rootIndex = await readFile(join(output, "index.html"), "utf8");
+    expect(rootIndex).toContain('<a href="bnw/index.html">BNW - Brave New World</a>');
+  });
+});
+
+describe("folders ignored via config.json { hidden: true }", () => {
+  beforeEach(() => {
+    // getFolderConfig memoizes per absolute path; temp dirs are unique per
+    // test, but clearing keeps the cache from growing across the suite.
+    clearConfigCache();
+  });
+
+  it("omits a hidden folder from an auto-index built from source", async () => {
+    await mkdir(join(source, "_art"), { recursive: true });
+    await writeFile(join(source, "_art", "config.json"), JSON.stringify({ hidden: true }));
+    await writeFile(join(source, "_art", "prompts.md"), "# Prompts\n");
+    await mkdir(join(source, "people"), { recursive: true });
+    await writeFile(join(source, "people", "alice.md"), "# Alice\n");
+
+    const html = await generateAutoIndexHtmlFromSource(source, 2);
+
+    expect(html).toContain("people");
+    expect(html).not.toContain("_art");
+    expect(html).not.toContain("prompts");
+  });
+
+  it("omits a hidden folder even when stale output for it still exists", async () => {
+    // A folder generated before it was hidden leaves files behind in output.
+    // The listing is built from output, so without a source-side check the
+    // hidden folder would reappear in the index.
+    await mkdir(join(source, "_art"), { recursive: true });
+    await writeFile(join(source, "_art", "config.json"), JSON.stringify({ hidden: true }));
+    await mkdir(join(source, "people"), { recursive: true });
+    await writeFile(join(source, "people", "alice.md"), "# Alice\n");
+
+    await mkdir(join(output, "_art"), { recursive: true });
+    await writeFile(join(output, "_art", "prompts.html"), "<html><body>stale</body></html>");
+    await mkdir(join(output, "people"), { recursive: true });
+    await writeFile(join(output, "people", "alice.html"), "<html><body>Alice</body></html>");
+
+    const progress = makeProgress();
+    await runAutoIndices(
+      [source, join(source, "people")],
+      [join(source, "people", "alice.md")],
+      progress
+    );
+
+    const index = await readFile(join(output, "index.html"), "utf8");
+    expect(index).toContain("people");
+    expect(index).not.toContain("_art");
+  });
+
+  it("does not count documents inside a hidden subfolder when deciding a folder has content", async () => {
+    // `notes` holds nothing but a hidden subfolder, so it produces no pages
+    // and must not be linked as though it did.
+    await mkdir(join(source, "notes", "_art"), { recursive: true });
+    await writeFile(
+      join(source, "notes", "_art", "config.json"),
+      JSON.stringify({ hidden: true })
+    );
+    await writeFile(join(source, "notes", "_art", "prompts.md"), "# Prompts\n");
+    await mkdir(join(source, "people"), { recursive: true });
+    await writeFile(join(source, "people", "alice.md"), "# Alice\n");
+
+    const html = await generateAutoIndexHtmlFromSource(source, 2);
+
+    expect(html).toContain("people");
+    expect(html).not.toContain("notes");
+  });
+});

package/src/helper/build/autoIndex.js

@@ -5,10 +5,18 @@ import { basename, dirname, extname, join } from "path";
 import { outputFile } from "fs-extra";
 import { findStyleCss, findAllStyleCss } from "../findStyleCss.js";
 import { findAllScriptJs } from "../findScriptJs.js";
-import { toTitleCase } from "./titleCase.js";
 import { addTimestampToHtmlStaticRefs } from "./cacheBust.js";
 import { isMetadataOnly, extractMetadata, getAutoIndexConfig } from "../metadataExtractor.js";
 import { getCustomMenuForFile } from "./menu.js";
+import { getFolderConfig, isFolderSelfHidden } from "../folderConfig.js";
+import {
+  toDisplayName,
+  getFolderLabel,
+  getFolderSortKey,
+  getMenuSortAsFromFile,
+  getFileLabel,
+  findSourceDocument,
+} from "../menuLabels.js";
 import { generateBreadcrumbs } from "../breadcrumbs.js";
 import { bundleDocumentCss, bundleDocumentJs } from "../assetBundler.js";
 
@@ -18,11 +26,18 @@ const OUTPUT_DOC_EXTENSIONS = ['.html'];
 
 /**
  * Recursively check if a directory contains any document files.
+ *
+ * Documents inside a config-hidden subfolder do not count: they produce no
+ * output, so a folder whose only contents are hidden must not be linked as if
+ * it had pages. When `dir` is an output directory, pass the matching source
+ * directory as `sourceDir` — the config.json lives in the source tree.
+ *
  * @param {string} dir - Directory path to check
  * @param {string[]} extensions - File extensions that count as documents
+ * @param {string|null} [sourceDir=dir] - Matching source directory, for hidden lookups
  * @returns {Promise<boolean>} True if the directory (or any subdirectory) contains at least one document
  */
-async function directoryHasDocuments(dir, extensions) {
+async function directoryHasDocuments(dir, extensions, sourceDir = dir) {
   try {
     const children = await readdir(dir, { withFileTypes: true });
     for (const child of children) {
@@ -30,7 +45,9 @@ async function directoryHasDocuments(dir, extensions) {
       const fullPath = join(dir, child.name);
       if (child.isDirectory()) {
         if (child.name === 'img') continue;
-        if (await directoryHasDocuments(fullPath, extensions)) return true;
+        if (sourceDir && isFolderSelfHidden(join(sourceDir, child.name))) continue;
+        const childSource = sourceDir ? join(sourceDir, child.name) : null;
+        if (await directoryHasDocuments(fullPath, extensions, childSource)) return true;
       } else {
         const ext = extname(child.name).toLowerCase();
         if (extensions.includes(ext)) return true;
@@ -40,6 +57,44 @@ async function directoryHasDocuments(dir, extensions) {
   return false;
 }
 
+/**
+ * Resolve the label and sort key for one auto-index entry, using the same
+ * rules as the site-wide automenu: `menu-label` frontmatter wins, then
+ * config.json `label` for folders, then the prettified file/folder name.
+ *
+ * @param {boolean} isDir - Whether the entry is a directory
+ * @param {string} baseName - Name without extension
+ * @param {string|null} sourceDir - Source directory holding this entry, if known
+ * @returns {{label: string, sortKey: string}}
+ */
+function resolveEntryNaming(isDir, baseName, sourceDir) {
+  if (!sourceDir) {
+    return { label: toDisplayName(baseName), sortKey: baseName };
+  }
+  if (isDir) {
+    const childDir = join(sourceDir, baseName);
+    return {
+      label: getFolderLabel(childDir, getFolderConfig(childDir), baseName),
+      sortKey: getFolderSortKey(childDir) || baseName,
+    };
+  }
+  const sourceFile = findSourceDocument(sourceDir, baseName);
+  return {
+    label: getFileLabel(sourceFile, baseName),
+    sortKey: (sourceFile && getMenuSortAsFromFile(sourceFile)) || baseName,
+  };
+}
+
+/**
+ * Sort auto-index entries the way the automenu does: folders first, then by
+ * sort key (case-insensitive).
+ */
+function compareEntries(a, b) {
+  if (a.isDir && !b.isDir) return -1;
+  if (!a.isDir && b.isDir) return 1;
+  return a.sortKey.toLowerCase().localeCompare(b.sortKey.toLowerCase());
+}
+
 /**
  * Generate auto-index HTML content for a directory from the OUTPUT folder
  * (used by fallback auto-index generation after all files are generated)
@@ -47,9 +102,12 @@ async function directoryHasDocuments(dir, extensions) {
  * @param {number} depth - How deep to recurse (1 = current level only, 2 = current + children, etc.)
  * @param {number} [currentDepth=0] - Current recursion depth (internal use)
  * @param {string} [pathPrefix=''] - Path prefix for generating correct hrefs (internal use)
+ * @param {string|null} [sourceDir=null] - Matching source directory, so `menu-label`
+ *   frontmatter and config.json labels can be honored. Without it, entries fall
+ *   back to their prettified file names.
  * @returns {Promise<string>} HTML content for the auto-index
  */
-export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pathPrefix = '') {
+export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pathPrefix = '', sourceDir = null) {
   try {
     const children = await readdir(dir, { withFileTypes: true });
     
@@ -62,15 +120,18 @@ export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pa
         if (child.name === 'index.html') return false;
         // Skip img folders (contain images, not content)
         if (child.isDirectory() && child.name === 'img') return false;
+        // Skip folders config.json marks hidden — they are ignored entirely,
+        // so a stale output directory must not resurrect them in a listing
+        if (child.isDirectory() && sourceDir && isFolderSelfHidden(join(sourceDir, child.name))) return false;
         // Include directories and html files
         return child.isDirectory() || child.name.endsWith('.html');
       })
-      .sort((a, b) => {
-        // Directories first, then files, alphabetically within each group
-        if (a.isDirectory() && !b.isDirectory()) return -1;
-        if (!a.isDirectory() && b.isDirectory()) return 1;
-        return a.name.localeCompare(b.name);
-      });
+      .map(child => {
+        const isDir = child.isDirectory();
+        const baseName = isDir ? child.name : child.name.replace(/\.html$/, '');
+        return { child, isDir, baseName, ...resolveEntryNaming(isDir, baseName, sourceDir) };
+      })
+      .sort(compareEntries);
     
     if (filteredChildren.length === 0) {
       return '';
@@ -78,26 +139,27 @@ export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pa
     
     const items = [];
     
-    for (const child of filteredChildren) {
-      const isDir = child.isDirectory();
+    for (const { child, isDir, label } of filteredChildren) {
       // Skip directories that contain no documents
       if (isDir) {
         const childDir = join(dir, child.name);
-        if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS)) continue;
+        const childSource = sourceDir ? join(sourceDir, child.name) : null;
+        if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS, childSource)) continue;
       }
-      const name = isDir ? child.name : child.name.replace('.html', '');
       // Use pathPrefix to ensure hrefs are correct relative to the document root
       const childPath = pathPrefix ? `${pathPrefix}/${child.name}` : child.name;
       const href = isDir ? `${childPath}/index.html` : (pathPrefix ? `${pathPrefix}/${child.name}` : child.name);
-      const displayName = toTitleCase(name);
       const icon = isDir ? '📁' : '📄';
       
-      let itemHtml = `<li>${icon} <a href="${href}">${displayName}</a>`;
+      let itemHtml = `<li>${icon} <a href="${href}">${label}</a>`;
       
       // If this is a directory and we need to go deeper, recurse
       if (isDir && currentDepth + 1 < depth) {
         const childDir = join(dir, child.name);
-        const childHtml = await generateAutoIndexHtml(childDir, depth, currentDepth + 1, childPath);
+        const childHtml = await generateAutoIndexHtml(
+          childDir, depth, currentDepth + 1, childPath,
+          sourceDir ? join(sourceDir, child.name) : null
+        );
         if (childHtml) {
           itemHtml += `\n${childHtml}`;
         }
@@ -137,15 +199,17 @@ export async function generateAutoIndexHtmlFromSource(sourceDir, depth = 1, curr
         if (child.name.match(/^index\.(md|mdx|txt|yml|html)$/i)) return false;
         // Skip img folders (contain images, not content)
         if (child.isDirectory() && child.name === 'img') return false;
+        // Skip folders config.json marks hidden — they produce no output
+        if (child.isDirectory() && isFolderSelfHidden(join(sourceDir, child.name))) return false;
         // Include directories and article files (md, mdx, txt, yml, html)
         return child.isDirectory() || child.name.match(/\.(md|mdx|txt|yml|html)$/i);
       })
-      .sort((a, b) => {
-        // Directories first, then files, alphabetically within each group
-        if (a.isDirectory() && !b.isDirectory()) return -1;
-        if (!a.isDirectory() && b.isDirectory()) return 1;
-        return a.name.localeCompare(b.name);
-      });
+      .map(child => {
+        const isDir = child.isDirectory();
+        const baseName = isDir ? child.name : basename(child.name, extname(child.name));
+        return { child, isDir, baseName, ...resolveEntryNaming(isDir, baseName, sourceDir) };
+      })
+      .sort(compareEntries);
     
     if (filteredChildren.length === 0) {
       return '';
@@ -153,24 +217,19 @@ export async function generateAutoIndexHtmlFromSource(sourceDir, depth = 1, curr
     
     const items = [];
     
-    for (const child of filteredChildren) {
-      const isDir = child.isDirectory();
+    for (const { child, isDir, baseName, label } of filteredChildren) {
       // Skip directories that contain no documents
       if (isDir) {
         const childDir = join(sourceDir, child.name);
         if (!await directoryHasDocuments(childDir, SOURCE_DOC_EXTENSIONS)) continue;
       }
-      // Get name without extension for display
-      const ext = isDir ? '' : extname(child.name);
-      const nameWithoutExt = isDir ? child.name : basename(child.name, ext);
       // Generate href - directories link to folder/index.html, files convert to .html
       // Use pathPrefix to ensure hrefs are correct relative to the document root
       const childPath = pathPrefix ? `${pathPrefix}/${child.name}` : child.name;
-      const href = isDir ? `${childPath}/index.html` : `${pathPrefix ? pathPrefix + '/' : ''}${nameWithoutExt}.html`;
-      const displayName = toTitleCase(nameWithoutExt);
+      const href = isDir ? `${childPath}/index.html` : `${pathPrefix ? pathPrefix + '/' : ''}${baseName}.html`;
       const icon = isDir ? '📁' : '📄';
       
-      let itemHtml = `<li>${icon} <a href="${href}">${displayName}</a>`;
+      let itemHtml = `<li>${icon} <a href="${href}">${label}</a>`;
       
       // If this is a directory and we need to go deeper, recurse
       if (isDir && currentDepth + 1 < depth) {
@@ -313,28 +372,34 @@ export async function generateAutoIndices(output, directories, source, templates
         const children = await readdir(dir, { withFileTypes: true });
         
         // Filter to only include relevant files and folders
-        const filteredItems = children.filter(child => {
-          // Skip hidden files and index alternates we just checked
-          if (child.name.startsWith('.')) return false;
-          if (child.name === 'index.html') return false;
-          // Include directories and html files
-          return child.isDirectory() || child.name.endsWith('.html');
-        });
+        const filteredItems = children
+          .filter(child => {
+            // Skip hidden files and index alternates we just checked
+            if (child.name.startsWith('.')) return false;
+            if (child.name === 'index.html') return false;
+            // Skip folders config.json marks hidden — they produce no output
+            if (child.isDirectory() && isFolderSelfHidden(join(sourceDir, child.name))) return false;
+            // Include directories and html files
+            return child.isDirectory() || child.name.endsWith('.html');
+          })
+          .map(child => {
+            const isDir = child.isDirectory();
+            const baseName = isDir ? child.name : child.name.replace(/\.html$/, '');
+            return { child, isDir, baseName, ...resolveEntryNaming(isDir, baseName, sourceDir) };
+          })
+          .sort(compareEntries);
 
         // Build items, skipping directories with no documents
         const items = [];
-        for (const child of filteredItems) {
-          const isDir = child.isDirectory();
+        for (const { child, isDir, label } of filteredItems) {
           if (isDir) {
             const childDir = join(dir, child.name);
-            if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS)) continue;
+            if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS, join(sourceDir, child.name))) continue;
           }
-          const name = isDir ? child.name : child.name.replace('.html', '');
           // For directories, link to /folder/index.html; for files, use the filename directly
           const href = isDir ? `${child.name}/index.html` : child.name;
-          const displayName = toTitleCase(name);
           const icon = isDir ? '📁' : '📄';
-          items.push(`<li>${icon} <a href="${href}">${displayName}</a></li>`);
+          items.push(`<li>${icon} <a href="${href}">${label}</a></li>`);
         }
         
         if (items.length === 0) {
@@ -342,12 +407,16 @@ export async function generateAutoIndices(output, directories, source, templates
           continue;
         }
         
-        const folderDisplayName = dir === outputNorm ? 'Home' : toTitleCase(folderName);
+        // The page's own heading and <title> follow the same naming rules, so a
+        // folder labelled "BNW - Brave New World" in the menu is not "Bnw" here.
+        const folderDisplayName = dir === outputNorm
+          ? 'Home'
+          : getFolderLabel(sourceDir, getFolderConfig(sourceDir), folderName);
 
         // Generate breadcrumbs for auto-index pages
         const relDir = dir.replace(outputNorm, '').replace(/^\//, '');
         const breadcrumbDir = relDir ? relDir + '/' : '/';
-        const breadcrumbHtml = generateBreadcrumbs(breadcrumbDir, 'index', null);
+        const breadcrumbHtml = generateBreadcrumbs(breadcrumbDir, 'index', null, sourceNorm);
 
         const indexHtml = `${breadcrumbHtml}<h1>${folderDisplayName}</h1>\n<ul class="auto-index">\n${items.join('\n')}\n</ul>`;
         

package/src/helper/build/ursaMetadata.js

@@ -1,27 +1,8 @@
 // Helper for building the _ursa_metadata field embedded in generated JSON files
 import { existsSync } from "fs";
 import { readFile } from "fs/promises";
-import { dirname, join, resolve } from "path";
-import { URL } from "url";
-
-/**
- * Read the ursa version from ursa's own package.json
- * @returns {Promise<string>} The ursa version, or 'unknown' if it can't be read
- */
-async function getUrsaVersion() {
-  try {
-    // From src/helper/build/ursaMetadata.js, go up to the package root
-    const currentDir = dirname(new URL(import.meta.url).pathname);
-    const ursaPackagePath = resolve(currentDir, "..", "..", "..", "package.json");
-    if (existsSync(ursaPackagePath)) {
-      const ursaPackage = JSON.parse(await readFile(ursaPackagePath, "utf8"));
-      if (ursaPackage.version) return ursaPackage.version;
-    }
-  } catch (e) {
-    console.error(`Error reading ursa package.json: ${e.message}`);
-  }
-  return "unknown";
-}
+import { join, resolve } from "path";
+import { getUrsaVersion } from "../ursaVersion.js";
 
 /**
  * Read the documentation repo version from its package.json.
@@ -54,9 +35,5 @@ async function getDocVersion(_source) {
  * @returns {Promise<{ursaVersion: string, docVersion: string}>}
  */
 export async function getUrsaMetadata(_source) {
-  const [ursaVersion, docVersion] = await Promise.all([
-    getUrsaVersion(),
-    getDocVersion(_source),
-  ]);
-  return { ursaVersion, docVersion };
+  return { ursaVersion: getUrsaVersion(), docVersion: await getDocVersion(_source) };
 }

package/src/helper/contentHash.js

@@ -1,10 +1,12 @@
 import { createHash } from 'crypto';
-import { readFile, writeFile, mkdir } from 'fs/promises';
+import { readFile, writeFile, mkdir, rm } from 'fs/promises';
 import { existsSync } from 'fs';
 import { dirname, join } from 'path';
+import { getUrsaVersion } from './ursaVersion.js';
 
 const URSA_DIR = '.ursa';
 const HASH_CACHE_FILE = 'content-hashes.json';
+const CACHE_STAMP_FILE = 'cache-stamp.json';
 
 /**
  * Get the path to the .ursa directory for a given source directory
@@ -13,6 +15,57 @@ export function getUrsaDir(sourceDir) {
   return join(sourceDir, URSA_DIR);
 }
 
+/**
+ * Stamp `.ursa/` with the running ursa version, discarding the whole directory
+ * first if it was written by a different one.
+ *
+ * Hash-skipping compares *source* content only. It says nothing about the code
+ * that turned that source into output, so a cache warmed by an older ursa keeps
+ * whole documents from being re-rendered even after the templates, renderers and
+ * asset bundles that produced them have changed — the symptom users hit as
+ * "I had to run --clean again". Run this before loading any cache.
+ *
+ * On a first build there is nothing to discard, and `reset` is false.
+ *
+ * @param {string} sourceDir - Source directory root
+ * @param {string} [version] - Version to stamp with; defaults to ursa's own
+ * @returns {Promise<{reset: boolean, previous: string|null, version: string}>}
+ */
+export async function enforceCacheVersion(sourceDir, version = getUrsaVersion()) {
+  const ursaDir = getUrsaDir(sourceDir);
+  const stampPath = join(ursaDir, CACHE_STAMP_FILE);
+
+  let previous = null;
+  try {
+    if (existsSync(stampPath)) {
+      const stamp = JSON.parse(await readFile(stampPath, 'utf8'));
+      previous = typeof stamp?.ursaVersion === 'string' ? stamp.ursaVersion : null;
+    }
+  } catch (e) {
+    // An unreadable stamp tells us nothing about what wrote the cache, so treat
+    // it the same as a mismatch rather than trusting the caches beside it.
+    previous = null;
+  }
+
+  if (previous === version) return { reset: false, previous, version };
+
+  // A cache directory with no stamp predates stamping (or was hand-edited);
+  // either way its contents were not written by this ursa.
+  const hadCache = existsSync(ursaDir);
+  if (hadCache) await rm(ursaDir, { recursive: true, force: true });
+
+  try {
+    await mkdir(ursaDir, { recursive: true });
+    await writeFile(stampPath, JSON.stringify({ ursaVersion: version }, null, 2));
+  } catch (e) {
+    // A cache we cannot stamp is a cache we will discard again next run:
+    // correct, just slower. Not worth failing the build over.
+    console.warn('Could not write cache stamp:', e.message);
+  }
+
+  return { reset: hadCache, previous, version };
+}
+
 /**
  * Generate a short hash of content
  */

package/src/helper/folderConfig.js

@@ -11,9 +11,16 @@ const configCache = new Map();
  * {
  *   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
+ *   hidden?: boolean,     // If true, ignore the folder entirely (see below)
  *   openMenuItems?: string[]  // (root only) Array of folder names to expand by default
  * }
+ * 
+ * `hidden: true` means *ignored*, not merely unlisted. The folder and its
+ * whole subtree take no part in the build: no HTML is rendered from its
+ * documents, its images and other static assets are not copied, it does not
+ * appear in the sidebar menu, in any auto-index, in breadcrumbs, or in the
+ * search index, and `ursa serve` will not render its pages on demand. The
+ * files stay in the docroot; the site behaves as if they were not there.
  */
 
 /**
@@ -60,10 +67,33 @@ export function getRootConfig(sourceRoot) {
 }
 
 /**
- * Check if a folder or any of its ancestors is hidden via config.json
- * @param {string} folderPath - Absolute path to check
+ * True when this exact folder's own config.json says `hidden: true`, ignoring
+ * its ancestors.
+ *
+ * Use this where the ancestors have already been ruled out — walking a tree
+ * top-down, say, where reaching a node means every folder above it was
+ * visible. It needs no docroot, which is what makes it usable in the
+ * auto-index builders, where only the folder being listed is known.
+ *
+ * @param {string} folderPath - Absolute path to a folder
+ * @returns {boolean} True if that folder is marked hidden
+ */
+export function isFolderSelfHidden(folderPath) {
+  return getFolderConfig(folderPath.replace(/\/$/, ''))?.hidden === true;
+}
+
+/**
+ * Check if a path lies in a folder — its own, or any ancestor up to the
+ * docroot — that config.json marks `hidden: true`.
+ *
+ * Accepts file paths as well as directories: the walk starts at `folderPath`
+ * itself, and a file simply has no config.json of its own, so the first step
+ * misses and the ancestors decide. That is what lets the build filter a mixed
+ * list of files and directories through one predicate.
+ *
+ * @param {string} folderPath - Absolute path to check (file or directory)
  * @param {string} sourceRoot - The source root directory (stop checking at this level)
- * @returns {boolean} True if this folder should be hidden
+ * @returns {boolean} True if this path should be ignored
  */
 export function isFolderHidden(folderPath, sourceRoot) {
   let currentPath = folderPath.replace(/\/$/, '');