@kenjura/ursa 0.97.0 → 0.99.0

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+# 0.99.0
+2026-09-21
+
+`inject-menu` in config.json puts a named menu on every document in a folder.
+
+0.98.0's named menus had to be anchored by hand in every page that wanted one — ten class pages, each carrying its own `{menu:classes}`. Now the folder can do it once.
+
+- **`"inject-menu": {"id": "classes", "position": "top"}`** in a folder's `config.json` renders that menu into every document in the folder and its subfolders, at the top (above the page title, like a first-line anchor) or the bottom. The value can be one object or an array of them. The `id` resolves from each document's folder exactly as an anchor does; a menu that cannot be resolved becomes the same comment-plus-warning.
+- **Deeper configs replace, or inherit.** A subfolder's own `inject-menu` replaces the injection for its subtree, unless one of its entries is `{"inherit": true}`, in which case the ancestors' menus come first and the subfolder's are added after them. A folder without the key is transparent. The same id at the same position is injected once.
+- **Anchors still win.** A document that anchors an id itself is not also given it by injection, so a page can place the folder's menu somewhere particular.
+- **Graph-native.** `injectMenusFor:<dir>` reads the chain of `config.json` files as recorded inputs, so adding, editing or removing one re-renders exactly the documents beneath it and nothing else. Injection happens only for documents; generated index and listing pages are not touched.
+
+**Named menus keep their prose.** The menu parser reads list-item links and nothing else, which is all a fixed nav can show — so a label such as "Feat Categories:" written above the list in `menu-feats.md` silently vanished. A named menu's body is now split into its item lists and the text between them; the text is rendered as Markdown inside the `<nav>` in document order (`.ursa-menu-text`), and in a horizontal menu it sits in the same row as the strip, so a label reads as a label. Relative links and images in that text are rebased to the menu file's folder, since the menu is inlined into pages elsewhere. `auto-generate-menu` menus are unchanged: their body is a template around `{menu}`.
+
+# 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

@@ -234,6 +234,7 @@ sits in:
 | `label` | string | Name to show for this folder in menus and indices |
 | `icon` | string | URL of an icon to show beside it in the menu |
 | `openMenuItems` | string[] | Root `config.json` only: folders to expand by default |
+| `inject-menu` | object or object[] | Put a named menu on every document in this folder and below; see [Injected menus](#injected-menus) |
 
 ### Large Workloads
 
@@ -404,6 +405,109 @@ 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.
+- Anything in the menu file that is not a list item — a label before the
+  list, a note after it — is rendered as Markdown inside the menu, in order.
+  Its relative links and images are resolved against the menu file's own
+  folder, since the menu is shown on pages elsewhere. (With
+  `auto-generate-menu` the body is a template around `{menu}` and only its
+  items count, as in `menu.md`.)
+- 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.
+
+### Injected menus
+
+To put a named menu on every document in a folder and its subfolders without
+anchoring it in each one, name it in the folder's `config.json`:
+
+```json
+{ "inject-menu": { "id": "classes", "position": "top" } }
+```
+
+- `id` is the menu's frontmatter `id`, resolved from each document's folder
+  exactly as an anchor is (nearest file up the tree with that id). `position`
+  is `top` (default) or `bottom`. An array injects several:
+  `[{ "id": "classes" }, { "id": "footer-links", "position": "bottom" }]`.
+- A menu injected at the top goes above the page title, like an anchor on the
+  first line; one at the bottom goes after the last content. A document that
+  already anchors the same id is left alone — it is not given the menu twice.
+- A deeper folder's `config.json` with its own `inject-menu` **replaces** the
+  injection for its subtree. To add to it instead, include `{ "inherit": true }`
+  among the entries: `[{ "inherit": true }, { "id": "subsection" }]` keeps
+  the ancestors' menus and adds this one after them. A folder without the
+  key changes nothing.
+- A menu that cannot be resolved from a document's folder gets the same quiet
+  treatment as an anchor: an HTML comment and a warning naming the document.
+- Editing a `config.json` re-renders exactly the documents beneath it.
+
 ## 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,171 @@
   }
 }
 
+/* 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;
+  }
+
+  /* Prose from the menu file (a label before the list, a note after it) */
+  .ursa-menu-text {
+    margin: 0;
+  }
+
+  .ursa-menu-text p {
+    margin: 0;
+  }
+
+  /* --- horizontal: a strip, children in hover dropdowns; any prose sits
+     in the same row, so "Categories:" reads as a label for the strip --- */
+  :scope.ursa-menu-horizontal {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.25rem 0.75rem;
+  }
+
+  :scope.ursa-menu-horizontal > ul {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.25rem;
+  }
+
+  :scope.ursa-menu-vertical .ursa-menu-text {
+    padding: 0.25rem 0.7rem;
+  }
+
+  :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.99.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {

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

@@ -0,0 +1,225 @@
+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,
+  parseInjectMenu,
+  mergeInjectMenus,
+  splitMenuBody,
+  rebaseMenuHtml,
+} 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);
+  });
+});
+
+describe("config.json inject-menu", () => {
+  it("accepts one object or an array, defaults position to top, reports bad entries", () => {
+    expect(parseInjectMenu({ id: "classes" })).toEqual({ entries: [{ id: "classes", position: "top" }], inherit: false, problems: [] });
+    expect(parseInjectMenu([{ id: "a", position: "bottom" }, { id: "b", position: "TOP" }]).entries).toEqual([
+      { id: "a", position: "bottom" },
+      { id: "b", position: "top" },
+    ]);
+    const bad = parseInjectMenu([{ id: "a", position: "left" }, { position: "top" }, "x"]);
+    expect(bad.entries).toEqual([{ id: "a", position: "top" }]);
+    expect(bad.problems).toHaveLength(3);
+    expect(parseInjectMenu(undefined).entries).toEqual([]);
+  });
+
+  it("recognises the inherit marker, alone or beside entries", () => {
+    expect(parseInjectMenu({ inherit: true })).toEqual({ entries: [], inherit: true, problems: [] });
+    const p = parseInjectMenu([{ inherit: true }, { id: "sub", position: "bottom" }]);
+    expect(p.inherit).toBe(true);
+    expect(p.entries).toEqual([{ id: "sub", position: "bottom" }]);
+  });
+
+  it("merges down the folder chain: replace by default, extend with inherit, pass through when unset", () => {
+    const root = parseInjectMenu({ id: "site", position: "top" });
+    const mid = parseInjectMenu([{ inherit: true }, { id: "section", position: "bottom" }]);
+    const leaf = parseInjectMenu({ id: "leaf" });
+    expect(mergeInjectMenus([root])).toEqual([{ id: "site", position: "top" }]);
+    expect(mergeInjectMenus([root, null])).toEqual([{ id: "site", position: "top" }]);
+    expect(mergeInjectMenus([root, mid])).toEqual([{ id: "site", position: "top" }, { id: "section", position: "bottom" }]);
+    expect(mergeInjectMenus([root, mid, leaf])).toEqual([{ id: "leaf", position: "top" }]);
+    expect(mergeInjectMenus([root, mid, null, parseInjectMenu({ inherit: true })])).toEqual([
+      { id: "site", position: "top" },
+      { id: "section", position: "bottom" },
+    ]);
+    // same id and position inherited and restated: once
+    expect(mergeInjectMenus([root, parseInjectMenu([{ inherit: true }, { id: "site" }])])).toEqual([{ id: "site", position: "top" }]);
+    expect(mergeInjectMenus([])).toEqual([]);
+  });
+});
+
+describe("menu bodies with prose", () => {
+  it("splits item lists from the text around them, in order", () => {
+    const body = "Feat Categories:\n* [Ancestry](./ancestry/index.md)\n* [Class](./class/index.md)\n\nBlargo\n\n[foo](#)\n\n*bar* _baz_\n- [Last](./last.md)\n";
+    expect(splitMenuBody(body)).toEqual([
+      { kind: "text", text: "Feat Categories:" },
+      { kind: "items", text: "* [Ancestry](./ancestry/index.md)\n* [Class](./class/index.md)" },
+      { kind: "text", text: "Blargo\n\n[foo](#)\n\n*bar* _baz_" },
+      { kind: "items", text: "- [Last](./last.md)" },
+    ]);
+    // nested items and blank lines inside a list stay with the list
+    expect(splitMenuBody("- [A](a.md)\n  - [B](b.md)\n\n- [C](c.md)\n")).toEqual([
+      { kind: "items", text: "- [A](a.md)\n  - [B](b.md)\n\n- [C](c.md)" },
+    ]);
+    expect(splitMenuBody("\n\n")).toEqual([]);
+  });
+
+  it("rebases a menu's relative links and images to the menu file's folder", () => {
+    const html = '<p><a href="./x.md">x</a> <a href="../y/index.md#top">y</a> <a href="/abs.html">a</a> <a href="https://e.com">e</a> <a href="#h">h</a> <img src="img/pic.png?v=1"></p>';
+    expect(rebaseMenuHtml(html, "/character/feats")).toBe(
+      '<p><a href="/character/feats/x.html">x</a> <a href="/character/y/index.html#top">y</a> <a href="/abs.html">a</a> <a href="https://e.com">e</a> <a href="#h">h</a> <img src="/character/feats/img/pic.png?v=1"></p>'
+    );
+  });
+
+  it("renders text segments inside the nav, in order with the lists", () => {
+    const html = renderInlineMenuHtml(
+      [
+        { kind: "text", html: "<p>Feat Categories:</p>" },
+        { kind: "items", items: [{ label: "Class", href: "/character/feats/class/index.html", children: [] }] },
+        { kind: "text", html: "<p>Blargo</p>" },
+      ],
+      { id: "feats", currentUrl: "/character/feats/class/" }
+    );
+    expect(html).toBe(
+      '<nav class="ursa-menu ursa-menu-horizontal" data-menu-id="feats" aria-label="feats">' +
+      '<div class="ursa-menu-text"><p>Feat Categories:</p></div>' +
+      '<ul class="ursa-menu-level" data-depth="0"><li class="ursa-menu-item ursa-menu-current"><a href="/character/feats/class/index.html" aria-current="page">Class</a></li></ul>' +
+      '<div class="ursa-menu-text"><p>Blargo</p></div></nav>'
+    );
+  });
+});

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;
     }