@kenjura/ursa 0.98.0 → 0.99.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# 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
 

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
 
@@ -466,6 +467,12 @@ Fighters are…
 - 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.
 
@@ -476,6 +483,31 @@ 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

@@ -1503,7 +1503,24 @@
     text-decoration: none;
   }
 
-  /* --- horizontal: a strip, children in hover dropdowns --- */
+  /* 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;
@@ -1511,6 +1528,10 @@
     gap: 0.25rem;
   }
 
+  :scope.ursa-menu-vertical .ursa-menu-text {
+    padding: 0.25rem 0.7rem;
+  }
+
   :scope.ursa-menu-horizontal > ul > li {
     position: relative;
   }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.98.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

@@ -10,6 +10,10 @@ import {
   renderInlineMenuHtml,
   menuNotFoundComment,
   leadingMenusEnd,
+  parseInjectMenu,
+  mergeInjectMenus,
+  splitMenuBody,
+  rebaseMenuHtml,
 } from "../inlineMenu.js";
 import { isMenuFile, findCustomMenu } from "../customMenu.js";
 
@@ -140,3 +144,82 @@ describe("findNamedMenu / findCustomMenu", () => {
     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/build/__test__/pass.test.js

@@ -607,6 +607,20 @@ describe("named menus: menu-<name>.md rendered where a page anchors it", () => {
     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");
@@ -620,6 +634,86 @@ describe("named menus: menu-<name>.md rendered where a page anchors it", () => {
   });
 });
 
+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/site.js

@@ -65,6 +65,10 @@ import {
   renderInlineMenuHtml,
   menuNotFoundComment,
   leadingMenusEnd,
+  parseInjectMenu,
+  mergeInjectMenus,
+  splitMenuBody,
+  rebaseMenuHtml,
 } from "../inlineMenu.js";
 import { findAllStyleCss } from "../findStyleCss.js";
 import { findAllScriptJs } from "../findScriptJs.js";
@@ -109,7 +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",
+  "menuFileMeta", "namedMenuFor", "namedMenu", "injectMenusFor",
 ];
 /** Site-wide singletons. */
 export const SITE_KINDS = [
@@ -440,6 +444,27 @@ 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
@@ -448,27 +473,33 @@ export function createSite(env) {
   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"));
-      }
-    }
+    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
   // -------------------------------------------------------------------------
@@ -850,6 +881,32 @@ export function createSite(env) {
       }
     },
 
+    /**
+     * 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));
@@ -862,10 +919,20 @@ export function createSite(env) {
       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 };
+      // 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 };
     },
 
     /**
@@ -1018,8 +1085,11 @@ export function createSite(env) {
         body = renderResult;
       }
 
-      // `{menu:<id>}` anchors become the named menu, rendered in place
+      // `{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.

package/src/helper/inlineMenu.js

@@ -1,6 +1,6 @@
 /**
  * Named menus: `menu-<name>.md` files rendered inline where a document asks
- * for them.
+ * for them, or where a folder's config.json injects 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
@@ -14,6 +14,11 @@
  * as a horizontal strip (the default) or a vertical list (`appearance:
  * vertical`). The item whose href is the current page is marked.
  *
+ * A folder can also ask for a menu on every document beneath it without an
+ * anchor in each one: `"inject-menu": {"id": "classes", "position": "top"}`
+ * in its config.json (see parseInjectMenu / mergeInjectMenus below). The
+ * menu resolves by id from the document's folder exactly as an anchor does.
+ *
  * 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
@@ -21,7 +26,7 @@
  */
 
 import { readdirSync, readFileSync } from "./build/tracedFs.js";
-import { join, dirname, resolve, basename } from "path";
+import { join, dirname, resolve, basename, posix } from "path";
 import { extractMenuFrontmatter, isMenuFile } from "./customMenu.js";
 
 /** An anchor: `{menu:<id>}`. Ids are letters, digits, `_`, `-` and `.`. */
@@ -181,6 +186,130 @@ export function resolveMenuAnchors(html, render) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Injected menus: config.json `inject-menu`
+// ---------------------------------------------------------------------------
+
+export const INJECT_POSITIONS = ["top", "bottom"];
+
+/**
+ * Normalise a folder's `inject-menu` value: one object or an array of them,
+ * each `{id, position}` or the `{inherit: true}` marker.
+ *
+ * @param {unknown} value - The raw `inject-menu` value from config.json
+ * @returns {{entries: {id: string, position: string}[], inherit: boolean, problems: string[]}}
+ */
+export function parseInjectMenu(value) {
+  const out = { entries: [], inherit: false, problems: [] };
+  if (value === undefined || value === null) return out;
+  const list = Array.isArray(value) ? value : [value];
+  for (const item of list) {
+    if (!item || typeof item !== "object") {
+      out.problems.push(`entry ${JSON.stringify(item)} is not an object`);
+      continue;
+    }
+    if (item.inherit === true) {
+      out.inherit = true;
+      if (item.id === undefined) continue;
+    }
+    const id = item.id === undefined || item.id === null ? "" : String(item.id).trim();
+    if (!id) {
+      out.problems.push(`entry ${JSON.stringify(item)} has no id`);
+      continue;
+    }
+    let position = item.position === undefined ? "top" : String(item.position).trim().toLowerCase();
+    if (!INJECT_POSITIONS.includes(position)) {
+      out.problems.push(`"${id}": position "${item.position}" is not top or bottom; using top`);
+      position = "top";
+    }
+    out.entries.push({ id, position });
+  }
+  return out;
+}
+
+/**
+ * The menus a folder injects, from the chain of parsed `inject-menu` values
+ * on the way down from the docroot (`levels[0]` is the root, the last is the
+ * folder itself; a level with no `inject-menu` is null).
+ *
+ * A level that sets `inject-menu` replaces what was inherited unless one of
+ * its entries is `{inherit: true}`, in which case the ancestors' menus come
+ * first and the level's own are added after them. A level without the key
+ * changes nothing. The same id at the same position is injected once.
+ *
+ * @param {(ReturnType<typeof parseInjectMenu>|null)[]} levels
+ * @returns {{id: string, position: string}[]}
+ */
+export function mergeInjectMenus(levels) {
+  let effective = [];
+  for (const level of levels) {
+    if (!level) continue;
+    const base = level.inherit ? effective : [];
+    const merged = [...base];
+    for (const entry of level.entries) {
+      if (!merged.some((e) => e.id === entry.id && e.position === entry.position)) merged.push(entry);
+    }
+    effective = merged;
+  }
+  return effective;
+}
+
+// ---------------------------------------------------------------------------
+// Menu file bodies: item lists and the prose between them
+// ---------------------------------------------------------------------------
+
+/** A line the menu parser treats as an item: `- [..](..)`, `* [..](..)`, `* [[..]]`. */
+const ITEM_LINE_RE = /^\s*(?:-\s*\[[^\]]*\]\(|\*+\s*\[)/;
+
+/**
+ * Split a menu file's body into item lists and the text around them, in
+ * order. `menu.md` only ever needed the items — a fixed nav shows nothing
+ * else — but a menu rendered into the page can carry a label before its list
+ * or a note after it. Text segments are Markdown; item segments are what
+ * `parseCustomMenu` reads.
+ *
+ * @param {string} body
+ * @returns {{kind: 'items'|'text', text: string}[]}
+ */
+export function splitMenuBody(body) {
+  const segments = [];
+  let current = null;
+  for (const line of body.split("\n")) {
+    if (!line.trim()) {
+      if (current) current.lines.push(line);
+      continue;
+    }
+    const kind = ITEM_LINE_RE.test(line) ? "items" : "text";
+    if (!current || current.kind !== kind) {
+      current = { kind, lines: [] };
+      segments.push(current);
+    }
+    current.lines.push(line);
+  }
+  return segments
+    .map(({ kind, lines }) => ({ kind, text: lines.join("\n").trim() }))
+    .filter((seg) => seg.text);
+}
+
+/**
+ * A menu's prose is rendered once and inlined into pages in other folders,
+ * so its relative links and images must be made root-absolute against the
+ * menu file's own folder before that happens.
+ *
+ * @param {string} html - Rendered text segment
+ * @param {string} menuUrlDir - The menu file's folder as a URL path, e.g. "/character/feats"
+ */
+export function rebaseMenuHtml(html, menuUrlDir) {
+  const base = menuUrlDir.endsWith("/") ? menuUrlDir : menuUrlDir + "/";
+  return html.replace(/(<(?:a|img|source|video|audio)\b[^>]*?\s(?:href|src)=["'])([^"']+)(["'])/gi, (m, before, url, quote) => {
+    if (/^(?:[a-z][a-z0-9+.-]*:|\/\/|\/|#|\?)/i.test(url)) return m;
+    const [pathPart, rest = ""] = url.split(/(?=[?#])/, 2);
+    let resolved = posix.normalize(base + pathPart);
+    resolved = resolved.replace(/\.(md|mdx|txt)$/i, ".html");
+    return `${before}${resolved}${rest}${quote}`;
+  });
+}
+
 /** What an anchor becomes when its menu cannot be rendered. */
 export function menuNotFoundComment(id, reason = "not found") {
   return `<!-- ursa: menu "${escapeHtml(id)}" ${escapeHtml(reason)} -->`;
@@ -206,17 +335,26 @@ export function leadingMenusEnd(html) {
 /**
  * Static markup for a named menu.
  *
- * @param {Array} menuData - Items as `parseCustomMenu` produces them ({label, href, children})
+ * @param {Array} content - Either items as `parseCustomMenu` produces them
+ *   ({label, href, children}), or segments: `{kind: 'items', items}` and
+ *   `{kind: 'text', html}` in document order
  * @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 }) {
+export function renderInlineMenuHtml(content, { 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>`;
+  const segments = Array.isArray(content) && content.length > 0 && content[0]?.kind
+    ? content
+    : [{ kind: "items", items: content || [] }];
+  const inner = segments.map((seg) =>
+    seg.kind === "text"
+      ? `<div class="ursa-menu-text">${seg.html}</div>`
+      : renderLevel(seg.items || [], current, 0)
+  ).join("");
+  return `<nav class="ursa-menu ursa-menu-${appearance}" data-menu-id="${escapeHtml(id)}" aria-label="${escapeHtml(id)}">${inner}</nav>`;
 }
 
 function renderLevel(items, current, depth) {