@kenjura/ursa 0.90.0 → 0.93.0

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

@@ -6,10 +6,15 @@
  * dropdown panels. One widget can be open per side at a time.
  * 
  * Widget state (open/closed) is persisted in localStorage so it survives page reloads.
+ *
+ * An open panel carries data-active-widget naming whichever widget is showing,
+ * and loses it when it closes. The panels are shared containers, so this is what
+ * lets CSS — Ursa's own and a site's — tell one widget's panel from another's.
+ * See "Styling one widget at a time" in the README.
  * 
  * Built-in widgets:
  *   Left: Recent Activity (open by default)
- *   Right: TOC, Search, Profile
+ *   Right: TOC (open by default, persistent), Search, Profile
  */
 class WidgetManager {
   constructor() {
@@ -19,8 +24,31 @@ class WidgetManager {
     this.activeRight = null;
     this.activeLeft = null;
 
-    // Widgets that default to open on first visit
-    this.defaultOpen = new Set(['recent-activity']);
+    // Widgets that default to open on first visit. The TOC is here because it
+    // is reference furniture rather than a tool you go and fetch: it belongs
+    // beside the article the way page numbers belong on a page. It costs
+    // nothing to leave up — the stylesheet gives it the right margin, and
+    // takes it away again on a viewport with no margin to spare.
+    this.defaultOpen = new Set(['recent-activity', 'toc']);
+
+    // Widgets that are furniture rather than a drawer. Two things follow.
+    //
+    // A click elsewhere on the page does not dismiss them. Light dismissal is
+    // right for something you pull open, glance at and are done with, but the
+    // first half of following a link is a click on the page — so for a widget
+    // meant to stay up it fired constantly, and, because dismissal is recorded,
+    // it wrote down "the reader closed this" every time. One click on an
+    // article and the TOC was off for good, on that page and every page after.
+    // Escape is out for the same reason: it would be remembered.
+    //
+    // And they own their side of the nav. Another widget opening there is
+    // borrowing it, not replacing them — the loan is not recorded as a closure,
+    // and they come back when it is handed back.
+    //
+    // Which leaves the button in the nav and the panel's own close button as
+    // the only two things that decide whether a persistent widget is showing.
+    // Those are unambiguous, and those are remembered.
+    this.persistent = new Set(['toc']);
     
     if (this.buttons.length === 0) return;
     
@@ -86,12 +114,14 @@ class WidgetManager {
     document.addEventListener('click', (e) => {
       // Close right-side widget if click is outside
       if (this.activeRight && this.dropdownRight &&
+          !this.persistent.has(this.activeRight) &&
           !this.dropdownRight.contains(e.target) &&
           !e.target.closest('.widget-button')) {
         this.close('right');
       }
       // Close left-side widget if click is outside
       if (this.activeLeft && this.dropdownLeft &&
+          !this.persistent.has(this.activeLeft) &&
           !this.dropdownLeft.contains(e.target) &&
           !e.target.closest('.widget-button')) {
         this.close('left');
@@ -101,8 +131,8 @@ class WidgetManager {
     // Close on Escape
     document.addEventListener('keydown', (e) => {
       if (e.key === 'Escape') {
-        if (this.activeRight) this.close('right');
-        if (this.activeLeft) this.close('left');
+        if (this.activeRight && !this.persistent.has(this.activeRight)) this.close('right');
+        if (this.activeLeft && !this.persistent.has(this.activeLeft)) this.close('left');
       }
     });
 
@@ -130,6 +160,29 @@ class WidgetManager {
     } catch (e) { /* localStorage not available */ }
   }
   
+  /**
+   * Whether a widget should be showing, as far as the reader's own choices go:
+   * what they last decided, or the default if they have not decided anything.
+   */
+  wantsToBeOpen(widgetName) {
+    let saved;
+    try {
+      saved = localStorage.getItem(`ursa-widget-${widgetName}`);
+    } catch (e) { /* localStorage not available */ }
+    
+    return saved === 'open' || (saved == null && this.defaultOpen.has(widgetName));
+  }
+  
+  /**
+   * The widget that owns a side of the nav when nothing else is using it.
+   */
+  residentOf(side) {
+    for (const widgetName of this.persistent) {
+      if (this.getSide(widgetName) === side) return widgetName;
+    }
+    return null;
+  }
+  
   /**
    * Restore widget states from localStorage. 
    * For widgets with no saved state, use their default (defaultOpen set).
@@ -140,19 +193,24 @@ class WidgetManager {
     this.buttons.forEach(btn => widgetNames.add(btn.dataset.widget));
     
     for (const widgetName of widgetNames) {
-      const key = `ursa-widget-${widgetName}`;
-      let saved;
-      try {
-        saved = localStorage.getItem(key);
-      } catch (e) { /* localStorage not available */ }
-      
-      const shouldOpen = saved === 'open' || (saved === null && this.defaultOpen.has(widgetName));
-      if (shouldOpen) {
+      if (this.wantsToBeOpen(widgetName) && this.hasContent(widgetName)) {
         this.open(widgetName);
       }
     }
   }
   
+  /**
+   * Whether a widget has anything to show. A widget that has hidden its own
+   * button has nothing — the TOC generator does exactly that on a page with no
+   * headings — and restoring it would put an empty panel on screen with no
+   * button to shut it again. Only relevant on restore: a widget the reader
+   * opens by hand plainly has a button to have clicked.
+   */
+  hasContent(widgetName) {
+    const btn = document.querySelector(`.widget-button[data-widget="${widgetName}"]`);
+    return !btn || btn.style.display !== 'none';
+  }
+
   /**
    * Toggle a widget open/closed.
    */
@@ -178,8 +236,12 @@ class WidgetManager {
     const currentActive = this.getActive(side);
     if (currentActive) {
       this.deactivateContent(currentActive);
-      // Save the closed widget's state
-      this.saveState(currentActive, false);
+      // Save the closed widget's state — unless it is only lending its side out,
+      // in which case it has not been closed and should not be written down as
+      // closed. close() hands the side back when the borrower is done.
+      if (!this.persistent.has(currentActive)) {
+        this.saveState(currentActive, false);
+      }
     }
     
     this.setActive(side, widgetName);
@@ -233,6 +295,17 @@ class WidgetManager {
     
     // Fire event
     document.dispatchEvent(new CustomEvent('widget-closed', { detail: { widget: active, side } }));
+    
+    // Give the side back to its resident, if it has one and the reader has not
+    // put it away themselves. Guarded against the resident being the very thing
+    // just closed — otherwise closing the TOC would reopen it. (It cannot
+    // recurse either way: the side is already empty by this point, so the open()
+    // below finds nothing to displace.)
+    const resident = this.residentOf(side);
+    if (resident && resident !== active &&
+        this.wantsToBeOpen(resident) && this.hasContent(resident)) {
+      this.open(resident);
+    }
   }
   
   /**

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.90.0",
+  "version": "0.93.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {
@@ -44,13 +44,14 @@
     "remark-directive": "^4.0.0",
     "remark-gfm": "^4.0.1",
     "remark-supersub": "^1.0.0",
-    "sharp": "^0.33.2",
+    "sharp": "^0.34.5",
     "unist-util-visit": "^5.1.0",
     "ws": "^8.19.0",
     "yaml": "^2.1.3",
     "yargs": "^17.7.2"
   },
   "devDependencies": {
+    "@tabler/icons": "^3.46.0",
     "jest": "^29.6.2",
     "node-static": "^0.7.11",
     "nodemon": "^2.0.15"
@@ -79,7 +80,8 @@
   ],
   "pnpm": {
     "onlyBuiltDependencies": [
-      "esbuild"
+      "esbuild",
+      "sharp"
     ]
   },
   "publishConfig": {

package/src/dev.js

@@ -428,7 +428,7 @@ async function renderDocument(urlPath) {
   }
 
   // Inject breadcrumbs before the H1
-  const breadcrumbs = generateBreadcrumbs(dir, base, fileMeta);
+  const breadcrumbs = generateBreadcrumbs(dir, base, fileMeta, source);
   if (breadcrumbs) {
     body = breadcrumbs + body;
   }

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

@@ -0,0 +1,71 @@
+import { join } from "path";
+import { mkdtemp, mkdir, writeFile, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { generateBreadcrumbs } from "../breadcrumbs.js";
+import { clearConfigCache } from "../folderConfig.js";
+
+let source;
+beforeEach(async () => {
+  source = await mkdtemp(join(tmpdir(), "ursa-breadcrumbs-"));
+  clearConfigCache();
+});
+afterEach(async () => {
+  await rm(source, { recursive: true, force: true });
+  clearConfigCache();
+});
+
+describe("generateBreadcrumbs", () => {
+  it("names folder segments the way the menu does", async () => {
+    await mkdir(join(source, "campaigns", "bnw"), { recursive: true });
+    await writeFile(
+      join(source, "campaigns", "bnw", "index.md"),
+      "---\nmenu-label: 'BNW - Brave New World'\n---\n# Brave New World\n"
+    );
+
+    const html = generateBreadcrumbs("campaigns/bnw/", "quests", null, source);
+
+    expect(html).toContain(">BNW - Brave New World</a>");
+    expect(html).toContain('aria-current="page">Quests</span>');
+  });
+
+  it("falls back to config.json when a folder has no index", async () => {
+    await mkdir(join(source, "campaigns", "hfr"), { recursive: true });
+    await writeFile(
+      join(source, "campaigns", "hfr", "config.json"),
+      JSON.stringify({ label: "HFR - Hyacinth: Fury Road" })
+    );
+
+    const html = generateBreadcrumbs("campaigns/hfr/", "sessions", null, source);
+
+    expect(html).toContain(">HFR - Hyacinth: Fury Road</a>");
+  });
+
+  it("uses the folder label for the current crumb on a folder's index page", async () => {
+    await mkdir(join(source, "campaigns", "bnw"), { recursive: true });
+    await writeFile(
+      join(source, "campaigns", "bnw", "index.md"),
+      "---\nmenu-label: 'BNW - Brave New World'\n---\n# Brave New World\n"
+    );
+
+    const html = generateBreadcrumbs("campaigns/bnw/", "index", null, source);
+
+    expect(html).toContain('aria-current="page">BNW - Brave New World</span>');
+  });
+
+  it("keeps the document's own frontmatter override for the last crumb", () => {
+    const withMenuLabel = generateBreadcrumbs("guides/", "setup", {
+      "menu-label": "Getting Started",
+      title: "Setup Guide",
+    });
+    expect(withMenuLabel).toContain('aria-current="page">Getting Started</span>');
+
+    // menu-label absent: title still wins, as it always has
+    const withTitle = generateBreadcrumbs("guides/", "setup", { title: "Setup Guide" });
+    expect(withTitle).toContain('aria-current="page">Setup Guide</span>');
+  });
+
+  it("preserves interior capitalization without a source root", () => {
+    const html = generateBreadcrumbs("campaigns/SoL/", "index", null);
+    expect(html).toContain('aria-current="page">SoL</span>');
+  });
+});

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

@@ -0,0 +1,114 @@
+import { join } from "path";
+import { mkdtemp, rm, mkdir, writeFile, readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { tmpdir } from "os";
+import {
+  enforceCacheVersion,
+  getUrsaDir,
+  loadHashCache,
+  saveHashCache,
+} from "../contentHash.js";
+
+let sourceDir;
+beforeEach(async () => {
+  sourceDir = await mkdtemp(join(tmpdir(), "ursa-cachestamp-"));
+});
+afterEach(async () => {
+  await rm(sourceDir, { recursive: true, force: true });
+});
+
+/** Write a populated `.ursa/` as an older build of ursa would have left it. */
+async function seedCache(stampVersion) {
+  const ursaDir = getUrsaDir(sourceDir);
+  await mkdir(ursaDir, { recursive: true });
+  await saveHashCache(sourceDir, new Map([["/site/a.md", "abc123"]]));
+  if (stampVersion !== null) {
+    await writeFile(
+      join(ursaDir, "cache-stamp.json"),
+      JSON.stringify({ ursaVersion: stampVersion })
+    );
+  }
+}
+
+describe("enforceCacheVersion", () => {
+  it("stamps a first build without reporting a reset", async () => {
+    const result = await enforceCacheVersion(sourceDir, "1.0.0");
+
+    expect(result).toEqual({ reset: false, previous: null, version: "1.0.0" });
+    const stamp = JSON.parse(
+      await readFile(join(getUrsaDir(sourceDir), "cache-stamp.json"), "utf8")
+    );
+    expect(stamp.ursaVersion).toBe("1.0.0");
+  });
+
+  it("keeps the cache when the stamp matches", async () => {
+    await seedCache("1.0.0");
+
+    const result = await enforceCacheVersion(sourceDir, "1.0.0");
+
+    expect(result.reset).toBe(false);
+    expect(await loadHashCache(sourceDir)).toEqual(
+      new Map([["/site/a.md", "abc123"]])
+    );
+  });
+
+  it("discards the cache when ursa has been upgraded", async () => {
+    await seedCache("1.0.0");
+
+    const result = await enforceCacheVersion(sourceDir, "1.1.0");
+
+    expect(result).toEqual({ reset: true, previous: "1.0.0", version: "1.1.0" });
+    expect(await loadHashCache(sourceDir)).toEqual(new Map());
+  });
+
+  it("discards the cache when ursa has been downgraded", async () => {
+    await seedCache("1.1.0");
+
+    const result = await enforceCacheVersion(sourceDir, "1.0.0");
+
+    expect(result.reset).toBe(true);
+    expect(await loadHashCache(sourceDir)).toEqual(new Map());
+  });
+
+  it("discards a cache left by a version that predates stamping", async () => {
+    await seedCache(null);
+
+    const result = await enforceCacheVersion(sourceDir, "1.0.0");
+
+    expect(result).toEqual({ reset: true, previous: null, version: "1.0.0" });
+    expect(await loadHashCache(sourceDir)).toEqual(new Map());
+  });
+
+  it("discards the cache when the stamp is unreadable", async () => {
+    await seedCache("1.0.0");
+    await writeFile(join(getUrsaDir(sourceDir), "cache-stamp.json"), "not json");
+
+    const result = await enforceCacheVersion(sourceDir, "1.0.0");
+
+    expect(result.reset).toBe(true);
+    expect(await loadHashCache(sourceDir)).toEqual(new Map());
+  });
+
+  it("leaves a stamp that the next run accepts", async () => {
+    await seedCache("1.0.0");
+
+    await enforceCacheVersion(sourceDir, "1.1.0");
+    await saveHashCache(sourceDir, new Map([["/site/a.md", "def456"]]));
+    const second = await enforceCacheVersion(sourceDir, "1.1.0");
+
+    expect(second.reset).toBe(false);
+    expect(await loadHashCache(sourceDir)).toEqual(
+      new Map([["/site/a.md", "def456"]])
+    );
+  });
+
+  it("removes every cache file in .ursa, not just the hashes", async () => {
+    await seedCache("1.0.0");
+    const navCache = join(getUrsaDir(sourceDir), "nav-cache.json");
+    await writeFile(navCache, JSON.stringify({ stale: true }));
+
+    await enforceCacheVersion(sourceDir, "1.1.0");
+
+    expect(existsSync(navCache)).toBe(false);
+  });
+});

package/src/helper/automenu.js

@@ -3,8 +3,15 @@ import { isHiddenOrSystemPath } from "./hiddenPaths.js";
 import { extname, basename, join, dirname } from "path";
 import { existsSync, readFileSync } from "fs";
 import { getFolderConfig, isFolderHidden, getRootConfig } from "./folderConfig.js";
-import { extractMetadata, isMetadataOnly } from "./metadataExtractor.js";
-import { stripHtml } from "./stripHtml.js";
+import { isMetadataOnly } from "./metadataExtractor.js";
+import {
+  INDEX_EXTENSIONS,
+  toDisplayName,
+  getMenuLabelFromFile,
+  getMenuSortAsFromFile,
+  getFolderLabel,
+  getFolderSortKey,
+} from "./menuLabels.js";
 
 // Icon extensions to check for custom icons
 const ICON_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico'];
@@ -14,93 +21,6 @@ const FOLDER_ICON = '📁';
 const DOCUMENT_ICON = '📄';
 const HOME_ICON = '🏠';
 
-// Index file extensions to check for folder links
-const INDEX_EXTENSIONS = ['.md', '.mdx', '.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
-}
-
-/**
- * Get the menu label from a file's frontmatter
- * @param {string} filePath - Path to the markdown file
- * @returns {string|null} The menu-label value (with HTML stripped), or null if not found
- */
-function getMenuLabelFromFile(filePath) {
-  try {
-    if (!existsSync(filePath)) return null;
-    const content = readFileSync(filePath, 'utf8');
-    const metadata = extractMetadata(content);
-    if (metadata && metadata['menu-label']) {
-      return stripHtml(String(metadata['menu-label']));
-    }
-  } catch (e) {
-    // Ignore read errors
-  }
-  return null;
-}
-
-/**
- * Get the menu-sort-as value from a file's frontmatter
- * @param {string} filePath - Path to the markdown file
- * @returns {string|null} The menu-sort-as value (with HTML stripped), or null if not found
- */
-function getMenuSortAsFromFile(filePath) {
-  try {
-    if (!existsSync(filePath)) return null;
-    const content = readFileSync(filePath, 'utf8');
-    const metadata = extractMetadata(content);
-    if (metadata && metadata['menu-sort-as']) {
-      return stripHtml(String(metadata['menu-sort-as']));
-    }
-  } catch (e) {
-    // Ignore read errors
-  }
-  return null;
-}
-
-/**
- * Get the menu label for a folder from its index.md frontmatter
- * Falls back to config.json label (deprecated), then display name
- * @param {string} dirPath - Path to the folder
- * @param {object|null} folderConfig - The folder's config.json if any
- * @param {string} baseName - The folder's base name
- * @returns {string} The label to display
- */
-function getFolderLabel(dirPath, folderConfig, baseName) {
-  // First, check index.md for menu-label (preferred method)
-  for (const ext of INDEX_EXTENSIONS) {
-    const indexPath = join(dirPath, `index${ext}`);
-    const label = getMenuLabelFromFile(indexPath);
-    if (label) return label;
-  }
-  
-  // Fall back to config.json label (deprecated)
-  if (folderConfig?.label) {
-    return folderConfig.label;
-  }
-  
-  // Default to display name from folder name
-  return toDisplayName(baseName);
-}
-
-/**
- * Get the sort key for a folder from its index.md frontmatter
- * @param {string} dirPath - Path to the folder
- * @returns {string|null} The menu-sort-as value, or null if not found
- */
-function getFolderSortKey(dirPath) {
-  for (const ext of INDEX_EXTENSIONS) {
-    const indexPath = join(dirPath, `index${ext}`);
-    const sortKey = getMenuSortAsFromFile(indexPath);
-    if (sortKey) return sortKey;
-  }
-  return null;
-}
-
 /**
  * Check if a file is an index file
  * @param {string} baseName - The file's base name (without extension)

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,7 @@ 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";
 
 let tempDir;
 let source;
@@ -93,3 +93,70 @@ 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>');
+  });
+});