@kenjura/ursa 0.97.0 → 0.98.0

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+# 0.98.0
+2026-09-20
+
+Named menus: `menu-<name>.md` files rendered inline where a document anchors them.
+
+A folder's `menu.md` replaces the site navigation for its subtree. That is one menu per folder, always in the chrome. Sites also want small menus that belong to the content — a strip of sibling pages at the top of each class page, say — and those have been written by hand into every page, and kept in sync by hand.
+
+- **Any `menu*.md` is a menu file.** `menu.md` (and `_menu.md`, `.txt` variants) is the folder menu as before; `menu-classes.md`, `menu-2.md` and so on are additional menus in the same folder, and the same file format.
+- **An `id` makes a menu named.** A menu file whose frontmatter has `id: classes` renders nowhere on its own. A document in that folder or below it places it with `{menu:classes}` on a line of its own, and the menu appears there as a static `<nav class="ursa-menu">` inside the article — not a fixed element. `menu.md` with an `id` is a named menu too, and stops being the folder's nav. The `id` is required for `menu-<name>.md`; a file without one is warned about and renders nowhere.
+- **`appearance: horizontal | vertical`**, default horizontal: a strip of items with hover dropdowns for nested items, or a stacked, indented list. Both mark the current page's item (`ursa-menu-current`) and its ancestors (`ursa-menu-active`). Styles live in the default template's stylesheet, scoped like the breadcrumbs so a site's `a { … }` cannot break them and a site's more specific selector can restyle them.
+- **Resolution is by nearest id.** The walk goes up from the document's folder to the docroot; the first menu file with a matching `id` wins, so a deeper folder can shadow one defined above it. `auto-generate-menu` and `menu-depth` work as in `menu.md`.
+- **Anchors fail quietly.** `{menu:x}` is inert Markdown — braces mean nothing to the renderer — and it is substituted after rendering, so an anchor never changes how the Markdown around it parses. If no menu answers, or the menu file cannot be parsed, the anchor becomes `<!-- ursa: menu "x" not found -->` and the build warns, naming the document; the page renders normally. Anchors inside code spans and code blocks stay as written. In `.mdx`, where `{…}` is an expression, an anchor alone on a line is rewritten before compilation and never reaches the compiler.
+- **A menu above the first heading stays above the title.** The default `<h1>` is injected after any leading menus rather than before them, and the default template's `sectionify.js` keeps leading menus with the breadcrumbs, outside the sections.
+- **Menus are build-graph nodes.** Editing `menu-classes.md` rewrites exactly the pages that anchor it (their `.html`, `.json` and `.xml`), nothing else; creating a missing menu file fills the anchors in the next pass without the pages being edited; deleting it puts the comments back. A page that anchors a menu depends on a projection of each candidate menu file's identity, not its body, so adding an unrelated file to the folder does not re-render it.
+- **Menu files are not documents.** They are not rendered to pages, listed in the automenu, an auto-index or a `<dir>.html` listing, indexed for search, or dated in recent activity. This applies to `menu.md` too, which used to be rendered to `menu.html`. The upgrade discards the build cache, so that stale page is not known to the new graph and is not deleted; one `--clean` removes it.
+
+The README gains a "Menus" section documenting both kinds.
+
 # 0.97.0
 2026-09-20
 

package/README.md

@@ -404,6 +404,78 @@ useEffect(() => {
 
 `contentChanged(root)` dispatches `ursa:content-changed` on `document` with the changed element in `event.detail.root` (the article, if omitted). Sticky headings and the table of contents re-read the article on it; calls within the same task are coalesced into one event. A site's own scripts can listen for the same event.
 
+## Menus
+
+The site's navigation is generated from the folder tree. A folder can replace
+it with its own menu by holding a `menu.md` (or `menu.txt`, `_menu.md`,
+`_menu.txt`); that menu applies to the folder and everything below it, until a
+deeper folder holds a menu of its own.
+
+```markdown
+---
+auto-generate-menu: true   # start from the folder tree…
+menu-position: top         # top (default) or side
+menu-depth: 3
+---
+
+- [Custom link](./somewhere.md)
+{menu}                     # …and put the generated items here
+- [Another](https://example.com)
+```
+
+Items are Markdown list links (`- [Label](./path.md)`, nested by indentation)
+or wikitext (`* [[path|Label]]`). Relative paths resolve from the menu file's
+folder.
+
+### Named menus
+
+A menu file whose frontmatter has an `id` is a **named menu**. It does not
+replace the folder's navigation; instead any document in that folder or below
+it places the menu in its body with an anchor on a line of its own:
+
+```markdown
+---
+id: classes
+appearance: horizontal     # horizontal (default) or vertical
+---
+
+- [Arcanist](./arcanist.md)
+- [Fighter](./fighter.md)
+- [Witch](./witch.mdx)
+```
+
+```markdown
+# Fighter
+
+{menu:classes}
+
+Fighters are…
+```
+
+- Name the file `menu.md` or `menu-<anything>.md` (`menu-classes.md`,
+  `menu-2.txt`); a folder can hold several. The `id` is required for
+  `menu-<anything>.md`; `menu.md` without one is the folder menu above.
+- The anchor renders as a static `<nav class="ursa-menu ursa-menu-<appearance>">`
+  exactly where it stands in the document, not as a fixed element. The item
+  whose link is the current page gets `ursa-menu-current` (its ancestors
+  `ursa-menu-active`), so a menu of sibling pages works as a category switcher.
+  `horizontal` is a strip of items with hover dropdowns for nested items;
+  `vertical` is a stacked, indented list.
+- The nearest file with that `id` wins, so a deeper folder can shadow a menu
+  defined above it. `auto-generate-menu` and `menu-depth` work as in `menu.md`.
+- A menu anchored above the first heading stays above the page title.
+- The anchor must be on its own line. It works in `.md`, `.txt` and `.mdx`.
+  An anchor inside a code span or code block is left as written.
+- Menu files are navigation, not documents: they are not rendered to pages,
+  listed in menus or indices, or searched.
+
+**Failure is quiet.** An anchor whose menu does not exist, or whose menu file
+cannot be parsed, is replaced by `<!-- ursa: menu "id" not found -->` and
+reported as a build warning naming the document. The page renders normally
+with nothing where the menu would have been, and the surrounding Markdown is
+untouched. Under `ursa serve`, creating the missing menu file fills the anchor
+without editing the page.
+
 ## Auto-Index Generation
 
 Ursa automatically generates index pages for folders that don't have one. You can also explicitly control auto-index generation in your index documents using frontmatter:

package/meta/templates/default-template/default.css

@@ -1465,6 +1465,150 @@
   }
 }
 
+/* Named menus (`{menu:<id>}` anchors) render inside the article too, as a
+   static block where the author put them.  Same treatment as the breadcrumbs:
+   Ursa's chrome, scoped, unlayered.  Horizontal is a strip of items with
+   hover dropdowns for children; vertical is a stacked list, TOC-like. */
+@scope (nav.ursa-menu) {
+  :scope {
+    font-size: 0.9rem;
+    margin: 0.5rem 0 1rem;
+    color: var(--text-color);
+  }
+
+  ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  li {
+    margin: 0;
+    padding: 0;
+  }
+
+  a, span {
+    display: block;
+    text-decoration: none;
+    white-space: nowrap;
+  }
+
+  /* Same colour as the top menu, visited or not: this is navigation, not
+     prose, and it may sit outside any section the site colours. */
+  a, a:visited {
+    color: var(--text-color);
+  }
+
+  a:hover {
+    text-decoration: none;
+  }
+
+  /* --- horizontal: a strip, children in hover dropdowns --- */
+  :scope.ursa-menu-horizontal > ul {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.25rem;
+  }
+
+  :scope.ursa-menu-horizontal > ul > li {
+    position: relative;
+  }
+
+  :scope.ursa-menu-horizontal > ul > li > a,
+  :scope.ursa-menu-horizontal > ul > li > span {
+    padding: 0.3rem 0.75rem;
+    border-radius: 4px;
+    transition: background-color 0.15s ease;
+  }
+
+  :scope.ursa-menu-horizontal > ul > li > a:hover {
+    background-color: color-mix(in srgb, var(--text-color) 10%, transparent);
+  }
+
+  :scope.ursa-menu-horizontal > ul > li.ursa-menu-current > a,
+  :scope.ursa-menu-horizontal > ul > li.ursa-menu-active > a {
+    font-weight: 600;
+    background-color: var(--widget-bg);
+    box-shadow: inset 0 0 0 1px var(--widget-border);
+  }
+
+  :scope.ursa-menu-horizontal > ul > li.ursa-menu-has-children > a::after,
+  :scope.ursa-menu-horizontal > ul > li.ursa-menu-has-children > span::after {
+    content: '▼';
+    font-size: 0.4em;
+    margin-left: 6px;
+    opacity: 0.6;
+    vertical-align: middle;
+  }
+
+  :scope.ursa-menu-horizontal li > ul {
+    display: none;
+    position: absolute;
+    top: 100%;
+    left: 0;
+    min-width: 12rem;
+    background-color: var(--widget-bg);
+    border: 1px solid var(--widget-border);
+    border-radius: 4px;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
+    z-index: 1005;
+  }
+
+  :scope.ursa-menu-horizontal li:hover > ul {
+    display: block;
+  }
+
+  :scope.ursa-menu-horizontal li li {
+    position: relative;
+  }
+
+  :scope.ursa-menu-horizontal li li > a,
+  :scope.ursa-menu-horizontal li li > span {
+    padding: 0.5rem 1rem;
+  }
+
+  :scope.ursa-menu-horizontal li li > a:hover {
+    background-color: color-mix(in srgb, var(--text-color) 10%, transparent);
+  }
+
+  :scope.ursa-menu-horizontal li li.ursa-menu-current > a {
+    font-weight: 600;
+  }
+
+  /* third level and deeper fly out to the side */
+  :scope.ursa-menu-horizontal li li > ul {
+    top: 0;
+    left: 100%;
+  }
+
+  /* --- vertical: stacked, nested levels indented --- */
+  :scope.ursa-menu-vertical a,
+  :scope.ursa-menu-vertical span {
+    padding: 0.25rem 0.7rem;
+    border-left: 2px solid transparent;
+    white-space: normal;
+  }
+
+  :scope.ursa-menu-vertical a:hover {
+    background-color: color-mix(in srgb, var(--text-color) 8%, transparent);
+  }
+
+  :scope.ursa-menu-vertical li.ursa-menu-current > a {
+    font-weight: 600;
+    border-left-color: var(--text-color);
+  }
+
+  :scope.ursa-menu-vertical li.ursa-menu-active > a {
+    font-weight: 600;
+  }
+
+  :scope.ursa-menu-vertical li > ul {
+    margin-left: 0.7rem;
+    border-left: 1px solid var(--widget-border);
+  }
+}
+
 
 /* --------------------------------------------------------------------------
    Document content.  Layered *and* scoped: layered so site CSS always wins,

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

@@ -7,10 +7,23 @@ document.addEventListener('DOMContentLoaded', () => {
     let currentSection = document.createElement('section');
     currentSection.classList.add('sectionOuter');
 
+    // The page header stays outside any section: the breadcrumbs, and any
+    // named menu (`{menu:…}`) anchored above the first heading. A menu placed
+    // further down is part of its section like any other content.
+    const preamble = [];
+    let inPreamble = true;
+
     for (let i = 0; i < children.length; i++) {
         const el = children[i];
-        // Skip breadcrumb nav — it stays outside sections
-        if (el.classList && el.classList.contains('breadcrumbs')) continue;
+        if (el.classList && el.classList.contains('breadcrumbs')) {
+            preamble.push(el);
+            continue;
+        }
+        if (inPreamble && el.classList && el.classList.contains('ursa-menu')) {
+            preamble.push(el);
+            continue;
+        }
+        inPreamble = false;
         if (el.tagName === 'H1' && currentSection.childNodes.length > 0) {
             sections.push(currentSection);
             currentSection = document.createElement('section');
@@ -22,18 +35,13 @@ document.addEventListener('DOMContentLoaded', () => {
         sections.push(currentSection);
     }
 
-    // Preserve breadcrumb nav before clearing
-    const breadcrumbs = article.querySelector('.breadcrumbs');
-
     // Remove all existing children
     while (article.firstChild) {
         article.removeChild(article.firstChild);
     }
 
-    // Re-insert breadcrumbs at the top, outside any section
-    if (breadcrumbs) {
-        article.appendChild(breadcrumbs);
-    }
+    // Re-insert the header at the top, outside any section
+    preamble.forEach(el => article.appendChild(el));
 
     // Append new sections
     sections.forEach(section => article.appendChild(section));

package/package.json

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

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

@@ -0,0 +1,142 @@
+import { join } from "path";
+import { mkdtemp, mkdir, writeFile, rm } from "fs/promises";
+import { tmpdir } from "os";
+import {
+  namedMenuOptions,
+  findNamedMenu,
+  collectMenuAnchorIds,
+  prepareMdxMenuAnchors,
+  resolveMenuAnchors,
+  renderInlineMenuHtml,
+  menuNotFoundComment,
+  leadingMenusEnd,
+} from "../inlineMenu.js";
+import { isMenuFile, findCustomMenu } from "../customMenu.js";
+
+describe("isMenuFile", () => {
+  it("matches the folder menu and named menus, not documents", () => {
+    for (const name of ["menu.md", "_menu.md", "menu.txt", "menu-2.md", "menu-classes.md", "_menu-x.txt", "Menu-Classes.md"]) {
+      expect(isMenuFile(name)).toBe(true);
+    }
+    for (const name of ["menus.md", "menu.mdx", "my-menu.md", "menu-.md", "menu_x.md", "index.md", "menu"]) {
+      expect(isMenuFile(name)).toBe(false);
+    }
+  });
+});
+
+describe("namedMenuOptions", () => {
+  it("defaults appearance to horizontal and reports an invalid value", () => {
+    expect(namedMenuOptions({ id: "classes" })).toEqual({ id: "classes", appearance: "horizontal", appearanceInvalid: null });
+    expect(namedMenuOptions({ id: "x", appearance: "Vertical" }).appearance).toBe("vertical");
+    expect(namedMenuOptions({ id: "x", appearance: "sideways" })).toMatchObject({ appearance: "horizontal", appearanceInvalid: "sideways" });
+    expect(namedMenuOptions({}).id).toBeNull();
+    expect(namedMenuOptions({ id: "" }).id).toBeNull();
+  });
+});
+
+describe("anchors", () => {
+  it("collects ids in both forms, once each", () => {
+    const html = '<p>{menu:a}</p><div data-ursa-menu="b"></div><p>x {menu:a} y</p>';
+    expect(collectMenuAnchorIds(html)).toEqual(["b", "a"]);
+  });
+
+  it("rewrites MDX anchors alone on a line into the element form", () => {
+    const src = "---\nx: 1\n---\n\n{menu:classes}\n\nText with {menu:inline} stays.\n  {menu:indented}  \n";
+    const out = prepareMdxMenuAnchors(src);
+    expect(out).toContain('<div data-ursa-menu="classes"></div>');
+    expect(out).toContain('<div data-ursa-menu="indented"></div>');
+    expect(out).toContain("Text with {menu:inline} stays.");
+  });
+
+  it("replaces a paragraph that is only the anchor", () => {
+    const out = resolveMenuAnchors("<h1>T</h1>\n<p>{menu:classes}</p>\n<p>Body.</p>", (id) => `<nav>${id}</nav>`);
+    expect(out).toBe("<h1>T</h1>\n<nav>classes</nav>\n<p>Body.</p>");
+  });
+
+  it("splits a paragraph with text around the anchor so the nav is not inside a <p>", () => {
+    const out = resolveMenuAnchors("<p>Before {menu:x} after</p>", (id) => `<nav>${id}</nav>`);
+    expect(out).toBe("<p>Before</p>\n<nav>x</nav><p>after</p>\n");
+  });
+
+  it("leaves anchors quoted in code alone", () => {
+    const html = "<p>Write <code>{menu:x}</code> on its own line.</p>\n<pre><code>{menu:y}</code></pre>";
+    expect(resolveMenuAnchors(html, () => "NO")).toBe(html);
+  });
+
+  it("replaces the element form anywhere", () => {
+    const out = resolveMenuAnchors('<div data-ursa-menu="c"></div><div data-ursa-menu="d"/>', (id) => `[${id}]`);
+    expect(out).toBe("[c][d]");
+  });
+
+  it("is a no-op for bodies without anchors", () => {
+    const html = "<p>Nothing here { menu } either</p>";
+    expect(resolveMenuAnchors(html, () => "X")).toBe(html);
+  });
+
+  it("finds where leading menus end", () => {
+    const nav = '<nav class="ursa-menu ursa-menu-horizontal" data-menu-id="a"><ul></ul></nav>';
+    expect(leadingMenusEnd(`${nav}\n<p>x</p>`)).toBe(nav.length);
+    expect(leadingMenusEnd(`\n${nav}${menuNotFoundComment("b")}<h1>T</h1>`)).toBe(1 + nav.length + menuNotFoundComment("b").length);
+    expect(leadingMenusEnd("<h1>T</h1>")).toBe(0);
+  });
+});
+
+describe("renderInlineMenuHtml", () => {
+  const data = [
+    { label: "Arcanist", href: "/character/classes/arcanist.html", children: [] },
+    { label: "Fighter & Co", href: "/character/classes/fighter.html", children: [] },
+    {
+      label: "More",
+      href: null,
+      children: [{ label: "Witch", href: "/character/classes/witch.html", children: [] }],
+    },
+  ];
+
+  it("renders a horizontal nav by default, escaping labels", () => {
+    const html = renderInlineMenuHtml(data, { id: "classes" });
+    expect(html).toMatch(/^<nav class="ursa-menu ursa-menu-horizontal" data-menu-id="classes"/);
+    expect(html).toContain("Fighter &amp; Co");
+    expect(html).toContain('<ul class="ursa-menu-level" data-depth="1">');
+    expect(html).toContain('<li class="ursa-menu-item ursa-menu-has-children"><span>More</span>');
+  });
+
+  it("marks the current page and its ancestors", () => {
+    const html = renderInlineMenuHtml(data, { id: "classes", appearance: "vertical", currentUrl: "/character/classes/witch.html" });
+    expect(html).toContain("ursa-menu-vertical");
+    expect(html).toContain('<li class="ursa-menu-item ursa-menu-current"><a href="/character/classes/witch.html" aria-current="page">Witch</a>');
+    expect(html).toContain('<li class="ursa-menu-item ursa-menu-has-children ursa-menu-active"><span>More</span>');
+    expect(html).not.toContain('ursa-menu-current"><a href="/character/classes/arcanist.html"');
+  });
+
+  it("treats index.html, a trailing slash and no extension as the same page", () => {
+    const items = [{ label: "Classes", href: "/character/classes/index.html", children: [] }];
+    for (const url of ["/character/classes/", "/character/classes", "/character/classes/index.html"]) {
+      expect(renderInlineMenuHtml(items, { id: "x", currentUrl: url })).toContain("ursa-menu-current");
+    }
+  });
+});
+
+describe("findNamedMenu / findCustomMenu", () => {
+  let root;
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "ursa-inline-menu-"));
+    await mkdir(join(root, "a/b"), { recursive: true });
+    await writeFile(join(root, "menu.md"), "---\nauto-generate-menu: true\n---\n");
+    await writeFile(join(root, "menu-classes.md"), "---\nid: classes\n---\n- [Root](./index.md)\n");
+    await writeFile(join(root, "a/menu-classes.md"), "---\nid: classes\nappearance: vertical\n---\n- [Deep](./x.md)\n");
+    await writeFile(join(root, "a/b/menu.md"), "---\nid: named-main\n---\n- [Hidden](./y.md)\n");
+  });
+  afterEach(() => rm(root, { recursive: true, force: true }));
+
+  it("nearest file with the id wins", () => {
+    expect(findNamedMenu(join(root, "a/b"), root, "classes").menuDir).toBe(join(root, "a"));
+    expect(findNamedMenu(root, root, "classes").menuDir).toBe(root);
+    expect(findNamedMenu(join(root, "a/b"), root, "named-main").path).toBe(join(root, "a/b/menu.md"));
+    expect(findNamedMenu(join(root, "a/b"), root, "nope")).toBeNull();
+  });
+
+  it("a menu.md with an id is not the folder's nav menu", () => {
+    const info = findCustomMenu(join(root, "a/b"), root);
+    expect(info.menuDir).toBe(root);
+  });
+});

package/src/helper/automenu.js

@@ -2,6 +2,7 @@ import { isHiddenOrSystemPath } from "./hiddenPaths.js";
 import { extname, basename, join, dirname } from "path";
 import { existsSync, readFileSync, readdirSync, isIgnoredDirEntry } from "./build/tracedFs.js";
 import { getFolderConfig, isFolderHidden, getRootConfig } from "./folderConfig.js";
+import { isMenuFile } from "./customMenu.js";
 import {
   INDEX_EXTENSIONS,
   toDisplayName,
@@ -200,8 +201,8 @@ function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug =
     const relativePath = item.path.replace(source, '');
     const folderPath = parentPath ? `${parentPath}/${baseName}` : baseName;
     
-    // Skip hidden files (config.json, style.css, etc.)
-    if (!hasChildren && hiddenFiles.includes(fileName)) {
+    // Skip hidden files (config.json, style.css, etc.) and menu files
+    if (!hasChildren && (hiddenFiles.includes(fileName) || isMenuFile(fileName))) {
       continue;
     }
     

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

@@ -509,6 +509,117 @@ 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("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("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,18 @@ import {
   extractMenuFrontmatter,
   parseCustomMenu,
   combineAutoAndManualMenu,
+  isMenuFile,
 } from "../customMenu.js";
+import {
+  findNamedMenu,
+  namedMenuOptions,
+  collectMenuAnchorIds,
+  prepareMdxMenuAnchors,
+  resolveMenuAnchors,
+  renderInlineMenuHtml,
+  menuNotFoundComment,
+  leadingMenusEnd,
+} from "../inlineMenu.js";
 import { findAllStyleCss } from "../findStyleCss.js";
 import { findAllScriptJs } from "../findScriptJs.js";
 import {
@@ -98,6 +109,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",
 ];
 /** Site-wide singletons. */
 export const SITE_KINDS = [
@@ -428,6 +440,35 @@ export function createSite(env) {
     return finishAssets(ctx, html, docUrlPath);
   }
 
+  /**
+   * 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 dirRel = dirRelOf(rel);
+    const currentUrl = "/" + outputPathFor(rel);
+    const rendered = new Map();
+    for (const id of ids) {
+      try {
+        const menuRel = await ctx.get(nodeId("namedMenuFor", `${dirRel}|${id}`));
+        const menu = menuRel ? await ctx.get(nodeId("namedMenu", menuRel)) : null;
+        if (!menu) {
+          warn(`menu-anchor:${rel}:${id}`, `⚠️  ${rel}: no menu with id "${id}" in this folder or above it`);
+          rendered.set(id, menuNotFoundComment(id));
+          continue;
+        }
+        rendered.set(id, renderInlineMenuHtml(menu.menuData, { id, appearance: menu.appearance, currentUrl }));
+      } catch (e) {
+        warn(`menu-anchor:${rel}:${id}`, `⚠️  ${rel}: menu "${id}" could not be rendered: ${e.message}`);
+        rendered.set(id, menuNotFoundComment(id, "could not be rendered"));
+      }
+    }
+    return resolveMenuAnchors(body, (id) => rendered.get(id) ?? menuNotFoundComment(id));
+  }
+
   // -------------------------------------------------------------------------
   // Node families
   // -------------------------------------------------------------------------
@@ -474,7 +515,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 +794,80 @@ 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;
+      }
+    },
+
+    /** 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;
+      const menuData = autoGenerate
+        ? combineAutoAndManualMenu(body, found.menuDir, source, depth)
+        : parseCustomMenu(body, found.menuDir, source);
+      return { id: info.id, appearance: info.appearance, menuData };
+    },
+
     /**
      * 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 +986,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 +1018,15 @@ 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
+      body = await resolveNamedMenus(ctx, body || "", rel);
+
+      // 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 +1215,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,

package/src/helper/inlineMenu.js

@@ -0,0 +1,275 @@
+/**
+ * Named menus: `menu-<name>.md` files rendered inline where a document asks
+ * for them.
+ *
+ * `menu.md` defines a folder's navigation menu and replaces the site's nav for
+ * the folder and everything below it. A menu file whose frontmatter carries an
+ * `id` is different: it renders nowhere on its own. Instead any document in
+ * the folder (or below it) places it with an anchor on a line of its own:
+ *
+ *     {menu:classes}
+ *
+ * The anchor becomes a static `<nav class="ursa-menu">` at that point in the
+ * body — part of the document, not a fixed element — with the menu's items
+ * as a horizontal strip (the default) or a vertical list (`appearance:
+ * vertical`). The item whose href is the current page is marked.
+ *
+ * Failure is quiet by design: an anchor whose menu is not found, or whose menu
+ * file cannot be parsed, is replaced by an HTML comment and reported as a
+ * build warning. The page still renders, with nothing visible where the menu
+ * would have been, and the surrounding Markdown is untouched.
+ */
+
+import { readdirSync, readFileSync } from "./build/tracedFs.js";
+import { join, dirname, resolve, basename } from "path";
+import { extractMenuFrontmatter, isMenuFile } from "./customMenu.js";
+
+/** An anchor: `{menu:<id>}`. Ids are letters, digits, `_`, `-` and `.`. */
+const ANCHOR_ID = "[A-Za-z0-9_][A-Za-z0-9_.-]*";
+const ANCHOR_RE = new RegExp(`\\{menu:(${ANCHOR_ID})\\}`, "g");
+/** The anchor alone on a line (leading/trailing blanks allowed). */
+const ANCHOR_LINE_RE = new RegExp(`^[ \\t]*\\{menu:(${ANCHOR_ID})\\}[ \\t]*$`, "gm");
+/** The element form of the anchor, which is what the MDX pipeline sees. */
+const ANCHOR_ELEMENT_RE = /<div\s+data-ursa-menu="([^"]+)"\s*(?:\/>|>\s*<\/div>)/g;
+
+export const APPEARANCES = ["horizontal", "vertical"];
+const DEFAULT_APPEARANCE = "horizontal";
+
+/**
+ * Normalise a menu file's frontmatter into the fields named menus use.
+ * `id` is required for a named menu; without it the file is a folder menu
+ * (menu.md) or invalid (menu-x.md), which the caller decides.
+ * @param {object} frontmatter
+ * @returns {{id: string|null, appearance: string, appearanceInvalid: string|null}}
+ */
+export function namedMenuOptions(frontmatter) {
+  const rawId = frontmatter?.id;
+  const id = rawId === undefined || rawId === null || rawId === "" ? null : String(rawId).trim();
+  const rawAppearance = frontmatter?.appearance;
+  let appearance = DEFAULT_APPEARANCE;
+  let appearanceInvalid = null;
+  if (rawAppearance !== undefined && rawAppearance !== "") {
+    const a = String(rawAppearance).trim().toLowerCase();
+    if (APPEARANCES.includes(a)) appearance = a;
+    else appearanceInvalid = String(rawAppearance);
+  }
+  return { id, appearance, appearanceInvalid };
+}
+
+/**
+ * Menu files in one directory, sorted. Reads the listing through tracedFs so
+ * a file appearing later is an observed change.
+ * @param {string} dirPath - Absolute directory
+ * @returns {string[]} - Absolute paths
+ */
+export function menuFilesIn(dirPath) {
+  let entries;
+  try {
+    entries = readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && isMenuFile(e.name))
+    .map((e) => join(dirPath, e.name))
+    .sort();
+}
+
+/**
+ * Find the nearest menu file with the given id, walking up from `dirPath` to
+ * the source root. A deeper file with the same id shadows a shallower one.
+ * @param {string} dirPath - Absolute directory to start from
+ * @param {string} sourceRoot - Absolute docroot; the walk stops here
+ * @param {string} id - The menu id an anchor named
+ * @returns {{path: string, menuDir: string, content: string, frontmatter: object, body: string} | null}
+ */
+export function findNamedMenu(dirPath, sourceRoot, id) {
+  const root = resolve(sourceRoot);
+  let current = resolve(dirPath);
+  while (current.startsWith(root)) {
+    for (const menuPath of menuFilesIn(current)) {
+      let content;
+      try {
+        content = readFileSync(menuPath, "utf8");
+      } catch {
+        continue;
+      }
+      const { frontmatter, body } = extractMenuFrontmatter(content);
+      if (namedMenuOptions(frontmatter).id === id) {
+        return { path: menuPath, menuDir: current, content, frontmatter, body };
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+/**
+ * Every menu id a rendered body anchors, in both forms, in order of first
+ * appearance. Used to demand the menus before substituting them.
+ * @param {string} html
+ * @returns {string[]}
+ */
+export function collectMenuAnchorIds(html) {
+  const ids = [];
+  const seen = new Set();
+  const add = (id) => {
+    if (!seen.has(id)) {
+      seen.add(id);
+      ids.push(id);
+    }
+  };
+  for (const m of html.matchAll(ANCHOR_ELEMENT_RE)) add(m[1]);
+  for (const m of html.matchAll(ANCHOR_RE)) add(m[1]);
+  return ids;
+}
+
+/**
+ * MDX reads `{menu:x}` as a JavaScript expression and fails to compile it.
+ * Before compiling, an anchor alone on a line becomes the element form, which
+ * is JSX the compiler passes through and `resolveMenuAnchors` recognises.
+ * @param {string} source - Raw .mdx source
+ * @returns {string}
+ */
+export function prepareMdxMenuAnchors(source) {
+  if (!source.includes("{menu:")) return source;
+  return source.replace(ANCHOR_LINE_RE, (_, id) => `\n<div data-ursa-menu="${id}"></div>\n`);
+}
+
+/**
+ * Replace every anchor in rendered HTML with what `render(id)` returns.
+ *
+ * Handles the element form anywhere, and the `{menu:x}` form inside a
+ * paragraph: a paragraph that is only the anchor is replaced whole, and a
+ * paragraph with text around the anchor is split so the `<nav>` never sits
+ * inside a `<p>`. Anchors inside `<code>` are left alone — they are being
+ * talked about, not used.
+ *
+ * @param {string} html - Rendered body
+ * @param {(id: string) => string} render - Markup for one id (never throws; see `menuNotFoundComment`)
+ * @returns {string}
+ */
+export function resolveMenuAnchors(html, render) {
+  if (!html || (!html.includes("{menu:") && !html.includes("data-ursa-menu"))) return html;
+
+  html = html.replace(ANCHOR_ELEMENT_RE, (_, id) => render(id));
+
+  if (!html.includes("{menu:")) return html;
+  return html.replace(/<p>([\s\S]*?)<\/p>/g, (paragraph, inner) => {
+    if (!inner.includes("{menu:")) return paragraph;
+    // Anchors quoted in code spans stay as written
+    const codeSpans = [];
+    const masked = inner.replace(/<code[\s>][\s\S]*?<\/code>/g, (span) => {
+      codeSpans.push(span);
+      return `\u0000${codeSpans.length - 1}\u0000`;
+    });
+    const unmask = (s) => s.replace(/\u0000(\d+)\u0000/g, (_, i) => codeSpans[Number(i)]);
+    const parts = masked.split(new RegExp(`\\{menu:(${ANCHOR_ID})\\}`));
+    if (parts.length === 1) return paragraph;
+    let out = "";
+    for (let i = 0; i < parts.length; i++) {
+      if (i % 2 === 1) {
+        out += render(parts[i]);
+      } else {
+        const text = unmask(parts[i]).trim();
+        if (text) out += `<p>${text}</p>\n`;
+      }
+    }
+    return out;
+  });
+}
+
+/** What an anchor becomes when its menu cannot be rendered. */
+export function menuNotFoundComment(id, reason = "not found") {
+  return `<!-- ursa: menu "${escapeHtml(id)}" ${escapeHtml(reason)} -->`;
+}
+
+/**
+ * True when a rendered body begins with inline menus (after optional
+ * whitespace), so the default-title injection can place its `<h1>` after them
+ * rather than pushing a top-of-page menu below the title.
+ * @param {string} html
+ * @returns {number} - Index just past the leading menus (0 when there are none)
+ */
+export function leadingMenusEnd(html) {
+  let i = 0;
+  const re = /^\s*(<nav class="ursa-menu[^"]*"[^>]*>[\s\S]*?<\/nav>|<!-- ursa: menu [^>]*-->)/;
+  for (;;) {
+    const m = re.exec(html.slice(i));
+    if (!m) return i;
+    i += m[0].length;
+  }
+}
+
+/**
+ * Static markup for a named menu.
+ *
+ * @param {Array} menuData - Items as `parseCustomMenu` produces them ({label, href, children})
+ * @param {object} opts
+ * @param {string} opts.id
+ * @param {string} [opts.appearance="horizontal"]
+ * @param {string|null} [opts.currentUrl] - The page's root-absolute `.html` URL, to mark the current item
+ * @returns {string}
+ */
+export function renderInlineMenuHtml(menuData, { id, appearance = DEFAULT_APPEARANCE, currentUrl = null }) {
+  const current = currentUrl ? normalizeUrl(currentUrl) : null;
+  const list = renderLevel(menuData || [], current, 0);
+  return `<nav class="ursa-menu ursa-menu-${appearance}" data-menu-id="${escapeHtml(id)}" aria-label="${escapeHtml(id)}">${list}</nav>`;
+}
+
+function renderLevel(items, current, depth) {
+  if (!items || items.length === 0) return "";
+  const lis = items.map((item) => {
+    const children = item.children || [];
+    const isCurrent = current !== null && item.href && normalizeUrl(item.href) === current;
+    const hasCurrentBelow = !isCurrent && containsCurrent(children, current);
+    const classes = ["ursa-menu-item"];
+    if (children.length > 0) classes.push("ursa-menu-has-children");
+    if (isCurrent) classes.push("ursa-menu-current");
+    if (hasCurrentBelow) classes.push("ursa-menu-active");
+    const label = escapeHtml(item.label ?? "");
+    const link = item.href
+      ? `<a href="${escapeHtml(item.href)}"${isCurrent ? ' aria-current="page"' : ""}>${label}</a>`
+      : `<span>${label}</span>`;
+    return `<li class="${classes.join(" ")}">${link}${renderLevel(children, current, depth + 1)}</li>`;
+  });
+  return `<ul class="ursa-menu-level" data-depth="${depth}">${lis.join("")}</ul>`;
+}
+
+function containsCurrent(items, current) {
+  if (current === null) return false;
+  for (const item of items || []) {
+    if (item.href && normalizeUrl(item.href) === current) return true;
+    if (containsCurrent(item.children, current)) return true;
+  }
+  return false;
+}
+
+/** `/a/b/index.html`, `/a/b/`, `/a/b` and `/a/b.html` compare by the same key. */
+function normalizeUrl(url) {
+  let u = String(url).split("#")[0].split("?")[0];
+  try {
+    u = decodeURIComponent(u);
+  } catch {
+    // leave as written
+  }
+  u = u.replace(/\/index\.html$/i, "/").replace(/\.html$/i, "");
+  if (u.length > 1) u = u.replace(/\/$/, "");
+  return u.toLowerCase();
+}
+
+export function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/** The menu id a `menu-<id>.md` filename suggests; for messages only. */
+export function menuFileSuffix(path) {
+  const m = basename(path).match(/^_?menu-(.+)\.(md|txt)$/i);
+  return m ? m[1] : null;
+}