@kenjura/ursa 0.97.0 → 0.99.0

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

@@ -509,6 +509,211 @@ describe("json-only", () => {
   });
 });
 
+describe("named menus: menu-<name>.md rendered where a page anchors it", () => {
+  const MENU = "---\nid: powers\n---\n- [Absorb](./absorb.md)\n- [Blast](./blast.md)\n";
+
+  it("renders the menu inline, marks the current page, and is not itself a page", async () => {
+    await write("character/powers/menu-powers.md", MENU);
+    await write("character/powers/absorb.md", "---\nclass: Witch\n---\n\n{menu:powers}\n\n# Absorb\n\nTouch.\n");
+    await write("character/powers/blast.md", "# Blast\n\n{menu:powers}\n\nBoom.\n");
+    const built = await coldBuild();
+    await built.close();
+
+    const absorb = await read("character/powers/absorb.html");
+    expect(absorb).toContain('<nav class="ursa-menu ursa-menu-horizontal" data-menu-id="powers"');
+    expect(absorb).toContain('<li class="ursa-menu-item ursa-menu-current"><a href="/character/powers/absorb.html" aria-current="page">Absorb</a>');
+    expect(absorb).toContain('<li class="ursa-menu-item"><a href="/character/powers/blast.html">Blast</a>');
+    expect(absorb).not.toContain("{menu:powers}");
+    // Anchored above the heading: the menu stays above the title
+    expect(absorb.indexOf('data-menu-id="powers"')).toBeLessThan(absorb.indexOf("<h1>Absorb</h1>"));
+
+    const blast = await read("character/powers/blast.html");
+    expect(blast).toContain('ursa-menu-current"><a href="/character/powers/blast.html"');
+    expect(blast.indexOf("<h1>Blast</h1>")).toBeLessThan(blast.indexOf('data-menu-id="powers"'));
+
+    // The menu file is navigation, not a document
+    expect(existsSync(join(output, "character/powers/menu-powers.html"))).toBe(false);
+    expect(await read("public/menu-data.json")).not.toContain("menu-powers");
+    expect(await read("character/powers.html")).not.toContain("menu-powers");
+    expect(existsSync(join(output, "public/custom-menu-character-powers.json"))).toBe(false);
+  });
+
+  it("editing the menu rewrites exactly the pages that anchor it", async () => {
+    await write("character/powers/menu-powers.md", MENU);
+    await write("character/powers/absorb.md", "---\nclass: Witch\n---\n\n{menu:powers}\n\n# Absorb\n\nTouch.\n");
+    const built = await coldBuild();
+
+    await write("character/powers/menu-powers.md", MENU + "- [Rules](../../rules/)\n");
+    let r = await built.pass();
+    expect(r.wrote).toEqual([
+      "character/powers/absorb.html",
+      "character/powers/absorb.json",
+      "character/powers/absorb.xml",
+    ]);
+    expect(await read("character/powers/absorb.html")).toContain(">Rules</a>");
+
+    // A vertical appearance is a menu change too
+    await write("character/powers/menu-powers.md", "---\nid: powers\nappearance: vertical\n---\n- [Absorb](./absorb.md)\n");
+    r = await built.pass();
+    expect(r.wrote).toContain("character/powers/absorb.html");
+    expect(r.wrote).not.toContain("character/powers/blast.html");
+    expect(await read("character/powers/absorb.html")).toContain("ursa-menu-vertical");
+
+    await built.close();
+    await expectConverged();
+  });
+
+  it("a missing menu degrades to a comment and a warning; creating it fills the anchor", async () => {
+    await write("character/powers/blast.md", "# Blast\n\n{menu:powers}\n\nBoom.\n");
+    const warnings = [];
+    const realWarn = console.warn;
+    console.warn = (m) => warnings.push(String(m));
+    const built = await build({ clean: true });
+    try {
+      await built.pass();
+    } finally {
+      console.warn = realWarn;
+    }
+    let blast = await read("character/powers/blast.html");
+    expect(blast).toContain('<!-- ursa: menu "powers" not found -->');
+    expect(blast).not.toContain("{menu:powers}");
+    expect(blast).toContain("<p>Boom.</p>");
+    expect(warnings.some((w) => w.includes('no menu with id "powers"'))).toBe(true);
+
+    // The menu file appears one level up: the page picks it up without being edited
+    await write("character/menu-powers.md", "---\nid: powers\n---\n- [Blast](./powers/blast.md)\n");
+    const r = await built.pass();
+    expect(r.wrote).toContain("character/powers/blast.html");
+    blast = await read("character/powers/blast.html");
+    expect(blast).toContain('data-menu-id="powers"');
+    expect(blast).toContain('ursa-menu-current"><a href="/character/powers/blast.html"');
+
+    // Deleting it puts the comment back
+    await unlink(join(source, "character/menu-powers.md"));
+    await built.pass();
+    expect(await read("character/powers/blast.html")).toContain('<!-- ursa: menu "powers" not found -->');
+    await built.close();
+    await expectConverged();
+  });
+
+  it("a menu.md with an id is a named menu, not the folder's nav", async () => {
+    await write("character/menu.md", "---\nid: sidebar\nappearance: vertical\n---\n- [Absorb](./powers/absorb.md)\n");
+    await write("character/powers/blast.md", "# Blast\n\nBoom.\n\n{menu:sidebar}\n");
+    const built = await coldBuild();
+    await built.close();
+    const blast = await read("character/powers/blast.html");
+    expect(blast).not.toContain("data-custom-menu=");
+    expect(blast).toContain('data-menu-id="sidebar"');
+    expect(existsSync(join(output, "public/custom-menu-character.json"))).toBe(false);
+  });
+
+  it("prose in the menu file is kept, with its links rebased to the menu's folder", async () => {
+    await write("character/menu-powers.md", "---\nid: powers\n---\nPowers:\n- [Absorb](./powers/absorb.md)\n\nSee also [the rules](../rules/index.md).\n");
+    await write("character/powers/blast.md", "# Blast\n\n{menu:powers}\n\nBoom.\n");
+    const built = await coldBuild();
+    await built.close();
+    const blast = await read("character/powers/blast.html");
+    const nav = blast.match(/<nav class="ursa-menu[\s\S]*?<\/nav>/)[0];
+    expect(nav).toContain('<div class="ursa-menu-text"><p>Powers:</p>');
+    expect(nav.indexOf("Powers:")).toBeLessThan(nav.indexOf("<ul"));
+    expect(nav).toContain('href="/character/powers/absorb.html"');
+    expect(nav).toContain('<a href="/rules/index.html">the rules</a>');
+    expect(nav.indexOf("See also")).toBeGreaterThan(nav.indexOf("</ul>"));
+  });
+
+  it("the anchor works in MDX", async () => {
+    await write("character/powers/menu-powers.md", MENU);
+    await write("character/powers/absorb.mdx", "---\nclass: Witch\n---\n\n{menu:powers}\n\n# Absorb\n\nTouch.\n");
+    await unlink(join(source, "character/powers/absorb.md"));
+    const built = await coldBuild();
+    await built.close();
+    const absorb = await read("character/powers/absorb.html");
+    expect(absorb).toContain('data-menu-id="powers"');
+    expect(absorb).toContain('ursa-menu-current"><a href="/character/powers/absorb.html"');
+    expect(absorb).not.toContain("data-ursa-menu");
+  });
+});
+
+describe("config.json inject-menu: a folder puts a named menu on every document beneath it", () => {
+  const MENU = "---\nid: powers\n---\n- [Absorb](./absorb.md)\n- [Blast](./blast.md)\n";
+
+  it("injects at the top or bottom of every document in the subtree, above the injected title", async () => {
+    await write("character/menu-powers.md", MENU.replace(/\.\/(\w+)\.md/g, "./powers/$1.md"));
+    await write("character/config.json", JSON.stringify({ "inject-menu": [{ id: "powers", position: "top" }, { id: "powers", position: "bottom" }] }));
+    await write("character/notes.md", "# Notes\n\nText.\n");
+    const built = await coldBuild();
+    await built.close();
+
+    const blast = await read("character/powers/blast.html");
+    const navs = blast.match(/<nav class="ursa-menu[^"]*" data-menu-id="powers"/g) ?? [];
+    expect(navs).toHaveLength(2);
+    expect(blast.indexOf('data-menu-id="powers"')).toBeLessThan(blast.indexOf("<h1>Blast</h1>"));
+    expect(blast.lastIndexOf('data-menu-id="powers"')).toBeGreaterThan(blast.indexOf("<p>Boom.</p>"));
+    expect(blast).toContain('ursa-menu-current"><a href="/character/powers/blast.html"');
+    // absorb has no H1 of its own: the injected title still comes after the menu
+    const absorb = await read("character/powers/absorb.html");
+    expect(absorb.indexOf('data-menu-id="powers"')).toBeLessThan(absorb.indexOf("<h1>Absorb</h1>"));
+    expect((absorb.match(/<h1[ >]/g) ?? []).length).toBe(1);
+    // a document directly in the folder gets it too; one outside does not
+    expect(await read("character/notes.html")).toContain('data-menu-id="powers"');
+    expect(await read("rules/combat.html")).not.toContain("data-menu-id");
+  });
+
+  it("a document that already anchors the menu is not given it twice", async () => {
+    await write("character/menu-powers.md", MENU.replace(/\.\/(\w+)\.md/g, "./powers/$1.md"));
+    await write("character/config.json", JSON.stringify({ "inject-menu": { id: "powers" } }));
+    await write("character/powers/blast.md", "# Blast\n\n{menu:powers}\n\nBoom.\n");
+    const built = await coldBuild();
+    await built.close();
+    const blast = await read("character/powers/blast.html");
+    expect(blast.match(/data-menu-id="powers"/g)).toHaveLength(1);
+    expect(blast.indexOf("<h1>Blast</h1>")).toBeLessThan(blast.indexOf('data-menu-id="powers"'));
+  });
+
+  it("a deeper config.json replaces the injection unless it inherits", async () => {
+    await write("menu-site.md", "---\nid: site\n---\n- [Home](./index.md)\n");
+    await write("character/menu-powers.md", MENU.replace(/\.\/(\w+)\.md/g, "./powers/$1.md"));
+    await write("config.json", JSON.stringify({ "inject-menu": { id: "site", position: "bottom" } }));
+    await write("character/config.json", JSON.stringify({ "inject-menu": [{ inherit: true }, { id: "powers" }] }));
+    await write("rules/config.json", JSON.stringify({ "inject-menu": { id: "powers" } }));
+    const built = await coldBuild();
+    await built.close();
+
+    const blast = await read("character/powers/blast.html");
+    expect(blast).toContain('data-menu-id="site"');
+    expect(blast).toContain('data-menu-id="powers"');
+    const combat = await read("rules/combat.html");
+    expect(combat).not.toContain('data-menu-id="site"');
+    // "powers" lives under character/, so rules/ cannot resolve it: comment plus warning, page intact
+    expect(combat).toContain('<!-- ursa: menu "powers" not found -->');
+    expect(combat).toContain("<h1>Combat</h1>");
+    expect(await read("index.html")).toContain('data-menu-id="site"');
+  });
+
+  it("editing the folder's config.json rewrites exactly the subtree's documents", async () => {
+    await write("character/menu-powers.md", MENU.replace(/\.\/(\w+)\.md/g, "./powers/$1.md"));
+    const built = await coldBuild();
+
+    await write("character/config.json", JSON.stringify({ "inject-menu": { id: "powers" } }));
+    let r = await built.pass();
+    // character.html is the folder's listing page, which lists the new config.json itself
+    expect(r.wrote.filter((w) => w.endsWith(".html") && w !== "character.html").sort()).toEqual([
+      "character/powers/absorb.html",
+      "character/powers/blast.html",
+    ]);
+    expect(r.wrote).not.toContain("rules/combat.html");
+    expect(r.wrote).not.toContain("index.html");
+    expect(await read("character/powers/absorb.html")).toContain('data-menu-id="powers"');
+
+    await unlink(join(source, "character/config.json"));
+    r = await built.pass();
+    expect(r.wrote).toContain("character/powers/absorb.html");
+    expect(await read("character/powers/absorb.html")).not.toContain("data-menu-id");
+    await built.close();
+    await expectConverged();
+  });
+});
+
 describe("determinism", () => {
   it("two clean builds of the same tree are byte-identical modulo build metadata", async () => {
     const built = await coldBuild();

package/src/helper/build/autoIndex.js

@@ -2,6 +2,7 @@
 import { readdir } from "./tracedFs.js";
 import { basename, extname, join } from "path";
 import { getFolderConfig, isFolderSelfHidden } from "../folderConfig.js";
+import { isMenuFile } from "../customMenu.js";
 import {
   toDisplayName,
   getFolderLabel,
@@ -39,6 +40,7 @@ async function directoryHasDocuments(dir, extensions, sourceDir = dir) {
         const childSource = sourceDir ? join(sourceDir, child.name) : null;
         if (await directoryHasDocuments(fullPath, extensions, childSource)) return true;
       } else {
+        if (isMenuFile(child.name)) continue;
         const ext = extname(child.name).toLowerCase();
         if (extensions.includes(ext)) return true;
       }
@@ -106,6 +108,8 @@ export async function generateAutoIndexHtmlFromSource(sourceDir, depth = 1, curr
         if (child.name.startsWith('.')) return false;
         // Skip index files (we're generating into the index)
         if (child.name.match(/^index\.(md|mdx|txt|yml|html)$/i)) return false;
+        // Skip menu files (menu.md, menu-<name>.md): navigation, not content
+        if (isMenuFile(child.name)) 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

package/src/helper/build/site.js

@@ -54,7 +54,22 @@ import {
   extractMenuFrontmatter,
   parseCustomMenu,
   combineAutoAndManualMenu,
+  isMenuFile,
 } from "../customMenu.js";
+import {
+  findNamedMenu,
+  namedMenuOptions,
+  collectMenuAnchorIds,
+  prepareMdxMenuAnchors,
+  resolveMenuAnchors,
+  renderInlineMenuHtml,
+  menuNotFoundComment,
+  leadingMenusEnd,
+  parseInjectMenu,
+  mergeInjectMenus,
+  splitMenuBody,
+  rebaseMenuHtml,
+} from "../inlineMenu.js";
 import { findAllStyleCss } from "../findStyleCss.js";
 import { findAllScriptJs } from "../findScriptJs.js";
 import {
@@ -98,6 +113,7 @@ export const DIR_KINDS = ["dirIndexJson", "dirListingHtml", "autoIndexPage", "di
 export const INTERNAL_KINDS = [
   "linkResolution", "outputOwner", "customMenuFor", "cssBundle", "jsBundle",
   "metaAsset", "metaBundle", "imageInfo", "docMeta",
+  "menuFileMeta", "namedMenuFor", "namedMenu", "injectMenusFor",
 ];
 /** Site-wide singletons. */
 export const SITE_KINDS = [
@@ -428,6 +444,62 @@ export function createSite(env) {
     return finishAssets(ctx, html, docUrlPath);
   }
 
+  /**
+   * One named menu rendered for one document, or an HTML comment (and a
+   * warning) when it is missing or cannot be rendered. `how` names the
+   * requester in the warning key: an anchor or a config.json injection.
+   */
+  async function renderNamedMenu(ctx, rel, id, currentUrl, how) {
+    const dirRel = dirRelOf(rel);
+    try {
+      const menuRel = await ctx.get(nodeId("namedMenuFor", `${dirRel}|${id}`));
+      const menu = menuRel ? await ctx.get(nodeId("namedMenu", menuRel)) : null;
+      if (!menu) {
+        warn(`menu-${how}:${rel}:${id}`, `⚠️  ${rel}: no menu with id "${id}" in this folder or above it`);
+        return menuNotFoundComment(id);
+      }
+      return renderInlineMenuHtml(menu.segments, { id, appearance: menu.appearance, currentUrl });
+    } catch (e) {
+      warn(`menu-${how}:${rel}:${id}`, `⚠️  ${rel}: menu "${id}" could not be rendered: ${e.message}`);
+      return menuNotFoundComment(id, "could not be rendered");
+    }
+  }
+
+  /**
+   * Replace a document's `{menu:<id>}` anchors with the named menus they name.
+   * A menu that is missing or fails to parse becomes an HTML comment and a
+   * warning; the page still renders.
+   */
+  async function resolveNamedMenus(ctx, body, rel) {
+    const ids = collectMenuAnchorIds(body);
+    if (ids.length === 0) return body;
+    const currentUrl = "/" + outputPathFor(rel);
+    const rendered = new Map();
+    for (const id of ids) rendered.set(id, await renderNamedMenu(ctx, rel, id, currentUrl, "anchor"));
+    return resolveMenuAnchors(body, (id) => rendered.get(id) ?? menuNotFoundComment(id));
+  }
+
+  /**
+   * Add the menus the document's folder injects (config.json `inject-menu`)
+   * to the top and bottom of its body. A menu the document already anchors
+   * itself is not added again.
+   */
+  async function injectNamedMenus(ctx, body, rel, anchoredIds) {
+    const entries = await ctx.get(nodeId("injectMenusFor", dirRelOf(rel)));
+    if (entries.length === 0) return body;
+    const currentUrl = "/" + outputPathFor(rel);
+    const anchored = new Set(anchoredIds);
+    let top = "";
+    let bottom = "";
+    for (const { id, position } of entries) {
+      if (anchored.has(id)) continue;
+      const html = await renderNamedMenu(ctx, rel, id, currentUrl, "inject");
+      if (position === "bottom") bottom += "\n" + html;
+      else top += html + "\n";
+    }
+    return top + body + bottom;
+  }
+
   // -------------------------------------------------------------------------
   // Node families
   // -------------------------------------------------------------------------
@@ -474,7 +546,8 @@ export function createSite(env) {
       files.sort();
       dirs.sort();
 
-      const articles = files.filter((f) => isArticle(f));
+      // Menu files (menu.md, menu-<name>.md) configure navigation; they are not pages
+      const articles = files.filter((f) => isArticle(f) && !isMenuFile(basename(f)));
       const html = files.filter((f) => isHandwrittenHtml(f));
       const images = files.filter((f) => IMAGE_EXTENSIONS.test(f));
       const media = files.filter((f) => isMedia(f));
@@ -752,6 +825,116 @@ export function createSite(env) {
       };
     },
 
+    // ----- Named menus (inlineMenu.js) --------------------------------------
+
+    /**
+     * A menu file's identity: `{id, appearance}` from its frontmatter, or null
+     * when the file is gone. A projection, so pages that only need to know
+     * *which* file answers an anchor do not re-render for a body edit.
+     */
+    menuFileMeta: (rel) => async (ctx) => {
+      let content;
+      try {
+        content = await ctx.read(abs(rel));
+      } catch {
+        return null;
+      }
+      const { frontmatter } = extractMenuFrontmatter(content);
+      const { id, appearance, appearanceInvalid } = namedMenuOptions(frontmatter);
+      if (!id && /^_?menu-/i.test(basename(rel))) {
+        warn(`menu-id:${rel}`, `⚠️  ${rel}: a named menu needs an \`id\` in its frontmatter; this file renders nowhere`);
+      }
+      if (appearanceInvalid) {
+        warn(`menu-appearance:${rel}`, `⚠️  ${rel}: appearance "${appearanceInvalid}" is not one of horizontal, vertical; using horizontal`);
+      }
+      return { id, appearance };
+    },
+
+    /**
+     * Which menu file answers `{menu:<id>}` for pages in a folder: the nearest
+     * one up the tree with that id, or null. Key: `<dirRel>|<id>`. Reads only
+     * directory listings and `menuFileMeta` projections.
+     */
+    namedMenuFor: (key) => async (ctx) => {
+      const sep = key.lastIndexOf("|");
+      const dirRel = key.slice(0, sep);
+      const id = key.slice(sep + 1);
+      let cur = dirRel;
+      for (;;) {
+        const entries = await ctx.listDir(abs(cur));
+        const candidates = entries
+          .filter((e) => e.kind === "file" && isMenuFile(e.name))
+          .map((e) => (cur ? `${cur}/${e.name}` : e.name))
+          .sort();
+        const matches = [];
+        for (const rel of candidates) {
+          const info = await ctx.get(nodeId("menuFileMeta", rel));
+          if (info?.id === id) matches.push(rel);
+        }
+        if (matches.length > 1) {
+          warn(`menu-dup:${cur}:${id}`, `⚠️  ${matches.join(", ")} all declare menu id "${id}"; using ${matches[0]}`);
+        }
+        if (matches.length > 0) return matches[0];
+        if (!cur) return null;
+        const parent = dirname(cur);
+        cur = parent === "." ? "" : parent;
+      }
+    },
+
+    /**
+     * The menus a folder's documents get injected (config.json `inject-menu`),
+     * resolved down the chain of folder configs from the docroot. Each
+     * config.json on the way is a recorded input, present or not.
+     */
+    injectMenusFor: (dirRel) => async () => {
+      const chain = [];
+      let cur = dirRel;
+      for (;;) {
+        chain.unshift(cur);
+        if (!cur) break;
+        const parent = dirname(cur);
+        cur = parent === "." ? "" : parent;
+      }
+      const levels = chain.map((d) => {
+        const config = getFolderConfig(abs(d));
+        if (!config || !("inject-menu" in config)) return null;
+        const parsed = parseInjectMenu(config["inject-menu"]);
+        for (const problem of parsed.problems) {
+          warn(`inject-menu:${d}:${problem}`, `⚠️  ${d ? d + "/" : ""}config.json inject-menu: ${problem}`);
+        }
+        return parsed;
+      });
+      return mergeInjectMenus(levels);
+    },
+
+    /** One named menu's parsed items, or null when the file is gone. */
+    namedMenu: (rel) => async (ctx) => {
+      const info = await ctx.get(nodeId("menuFileMeta", rel));
+      if (!info?.id) return null;
+      const menuDirRel = dirRelOf(rel);
+      const found = findNamedMenu(abs(menuDirRel), source, info.id);
+      if (!found || relOf(found.path) !== rel) return null;
+      const below = await ctx.get(nodeId("dirSet", menuDirRel));
+      await preloadFrontmatter(ctx, below.articles, { nonDocuments: below.files.filter((f) => !isArticle(f)) });
+      const { frontmatter, body } = found;
+      const autoGenerate = frontmatter["auto-generate-menu"] === true || frontmatter["auto-generate-menu"] === "true";
+      const depth = parseInt(frontmatter["menu-depth"], 10) || 10;
+      // With auto-generation the body is a template around the {menu} token
+      // and only its items count; otherwise prose between the lists is kept
+      let segments;
+      if (autoGenerate) {
+        segments = [{ kind: "items", items: combineAutoAndManualMenu(body, found.menuDir, source, depth) }];
+      } else {
+        const menuUrlDir = "/" + menuDirRel;
+        segments = splitMenuBody(body).map((seg) =>
+          seg.kind === "items"
+            ? { kind: "items", items: parseCustomMenu(seg.text, found.menuDir, source) }
+            : { kind: "text", html: rebaseMenuHtml(renderFile({ fileContents: seg.text, type: ".md" }) ?? "", menuUrlDir) }
+        );
+      }
+      return { id: info.id, appearance: info.appearance, segments };
+    },
+
     /**
      * The folder's inherited stylesheets bundled into public/<folder>.bundle.css.
      * Value: {url} with `?v=<hash>`, or null when the chain is empty. The chain
@@ -870,7 +1053,7 @@ export function createSite(env) {
       const shouldHydrate = type === ".mdx" && meta?.hydrate === true;
 
       const renderResult = await renderFileAsync({
-        fileContents: raw,
+        fileContents: type === ".mdx" ? prepareMdxMenuAnchors(raw) : raw,
         type,
         dirname: dir,
         basename: base,
@@ -902,10 +1085,18 @@ export function createSite(env) {
         body = renderResult;
       }
 
-      // Inject default H1 if body doesn't start with one
-      if (!body || !body.trimStart().startsWith("<h1")) {
+      // `{menu:<id>}` anchors become the named menu, rendered in place, and
+      // the folder's config.json can inject menus at the top and bottom
+      const anchoredIds = collectMenuAnchorIds(body || "");
+      body = await resolveNamedMenus(ctx, body || "", rel);
+      body = await injectNamedMenus(ctx, body, rel, anchoredIds);
+
+      // Inject default H1 if body doesn't start with one. A menu anchored at
+      // the very top stays above the title.
+      const afterMenus = leadingMenusEnd(body);
+      if (!body.slice(afterMenus).trimStart().startsWith("<h1")) {
         const h1Title = meta?.title || title;
-        body = `<h1>${h1Title}</h1>\n` + (body || "");
+        body = body.slice(0, afterMenus) + `<h1>${h1Title}</h1>\n` + body.slice(afterMenus);
       }
 
       // Breadcrumbs before the H1 (folder labels come from docMeta projections)
@@ -1094,6 +1285,7 @@ export function createSite(env) {
       if (owner) return { ownedBy: owner };
       const below = await ctx.get(nodeId("dirSet", dirRel));
       const items = below.files
+        .filter((f) => !isMenuFile(basename(f)))
         .map((f) => {
           const ext = extname(f);
           const href = "/" + (ext ? f.slice(0, -ext.length) : f) + ".html";

package/src/helper/customMenu.js

@@ -1,4 +1,5 @@
-// Custom menu support - allows defining custom menus in menu.md, menu.txt, _menu.md, or _menu.txt
+// Custom menu support - allows defining custom menus in menu.md, menu.txt, _menu.md, or _menu.txt.
+// Named menus (menu-<name>.md with an `id`) are handled by inlineMenu.js.
 import { existsSync, readFileSync, readdirSync, statSync } from "./build/tracedFs.js";
 import { join, dirname, relative, resolve, basename, extname } from "path";
 import { extractMetadata } from "./metadataExtractor.js";
@@ -6,6 +7,24 @@ import { extractMetadata } from "./metadataExtractor.js";
 // Menu file names to look for (in order of priority)
 const MENU_FILE_NAMES = ['menu.md', 'menu.txt', '_menu.md', '_menu.txt'];
 
+/**
+ * Every menu file: the folder menu (`menu.md`, `_menu.md`, `.txt` variants)
+ * and the named menus (`menu-classes.md`, `menu-2.txt`, …) that inlineMenu.js
+ * renders where a document anchors them. None of these is a document.
+ */
+export const MENU_FILE_RE = /^_?menu(-[a-z0-9][a-z0-9_.-]*)?\.(md|txt)$/i;
+
+/** True when a basename names a menu file (folder menu or named menu). */
+export function isMenuFile(name) {
+  return MENU_FILE_RE.test(name);
+}
+
+/** True when a menu file's frontmatter makes it a named menu (rendered only by anchors). */
+export function isNamedMenuFrontmatter(frontmatter) {
+  const id = frontmatter?.id;
+  return id !== undefined && id !== null && String(id).trim() !== '';
+}
+
 // Token to mark where auto-generated menu should be inserted
 const MENU_TOKEN = '{menu}';
 
@@ -115,6 +134,7 @@ function folderHasDocuments(dirPath) {
         if (entry.name === 'img') continue;
         if (folderHasDocuments(fullPath)) return true;
       } else {
+        if (isMenuFile(entry.name)) continue;
         const ext = extname(entry.name);
         if (SOURCE_EXTENSIONS.includes(ext)) return true;
       }
@@ -236,8 +256,8 @@ export function autoGenerateMenuFromFolder(folderPath, sourceRoot, depth = 10, i
     for (const entry of entries) {
       // Skip hidden files/folders
       if (entry.name.startsWith('.') || entry.name.startsWith('_')) continue;
-      // Skip menu files themselves
-      if (MENU_FILE_NAMES.includes(entry.name)) continue;
+      // Skip menu files themselves (the folder menu and any named menus)
+      if (isMenuFile(entry.name)) continue;
       // Skip config files
       if (entry.name === 'config.json') continue;
       // Skip img folders
@@ -406,6 +426,9 @@ export function findCustomMenu(dirPath, sourceRoot) {
       if (existsSync(menuPath)) {
         try {
           const content = readFileSync(menuPath, 'utf8');
+          // A menu.md with an `id` is a named menu: it renders only where a
+          // document anchors it, and does not replace the folder's nav
+          if (isNamedMenuFrontmatter(extractMenuFrontmatter(content).frontmatter)) continue;
           return {
             path: menuPath,
             content,