@heroiclands/package-build 22.23.0 → 22.25.0

package/engine/content-blocks.mjs

@@ -50,6 +50,7 @@ import MarkdownIt from "markdown-it";
 import footnotePlugin from "markdown-it-footnote";
 import deflistPlugin from "markdown-it-deflist";
 import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
+import { poetryMarkdown, verseLines } from "./content-poetry.mjs";
 import { WITHHELD_CLASS, parseHeadingLine, withheldSections } from "./heading-attributes.mjs";
 
 const parser = new MarkdownIt({ html: true }).use(footnotePlugin).use(deflistPlugin);
@@ -63,6 +64,8 @@ const titleParser = new MarkdownIt({ html: false });
 
 const OPEN = /^:::([A-Za-z][A-Za-z0-9-]*)(?:[ \t]+(.*?))?[ \t]*$/;
 const CLOSE = /^:::[ \t]*$/;
+const INDENTED_POETRY_OPEN = /^ +:::poetry(?:[ \t]+(.*?))?[ \t]*$/;
+const INDENTED_CLOSE = /^ *:::[ \t]*$/;
 
 /** The blocks an author may open, with the heading each takes by default. */
 export const BLOCK_NAMES = Object.freeze({
@@ -98,7 +101,7 @@ const FOREIGN = Object.freeze(["figure"]);
 /** `title` is the heading. Everything else an author writes becomes an attribute. */
 const TITLE = "title";
 
-const names = () => Object.keys(BLOCK_NAMES).join(", ");
+const names = () => [...Object.keys(BLOCK_NAMES), "poetry"].join(", ");
 
 /** Text safe inside a double-quoted attribute. */
 function escapeAttribute(value) {
@@ -132,7 +135,7 @@ export function scanBlocks(source) {
 
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
-        const fence = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        const fence = opening?.name === "poetry" ? null : /^ {0,3}(`{3,}|~{3,})/.exec(line);
         if (codeFence) {
             if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length) {
                 codeFence = null;
@@ -144,7 +147,7 @@ export function scanBlocks(source) {
             continue;
         }
 
-        if (CLOSE.test(line)) {
+        if (CLOSE.test(line) || (opening?.name === "poetry" && INDENTED_CLOSE.test(line))) {
             // A closer belongs to the innermost block still open, whichever
             // pass owns it.
             if (opening && innerOpen > 0) {
@@ -163,11 +166,21 @@ export function scanBlocks(source) {
                 opening = null;
                 continue;
             }
-            const body = lines
-                .slice(opening.start + 1, i)
-                .join("\n")
-                .trim();
-            if (!body) {
+            const bodyLines = lines.slice(opening.start + 1, i);
+            const rawBody = bodyLines.join("\n");
+            const body = opening.name === "poetry" ? rawBody : rawBody.trim();
+            if (opening.name === "poetry") {
+                for (let offset = 0; offset < bodyLines.length; offset++) {
+                    const column = bodyLines[offset].indexOf("\t");
+                    if (column >= 0)
+                        errors.push({
+                            line: opening.start + offset + 2,
+                            column: column + 1,
+                            message: "tabs are not allowed in poetry",
+                        });
+                }
+            }
+            if (!body.trim()) {
                 errors.push({
                     line: opening.start + 1,
                     column: 1,
@@ -176,12 +189,23 @@ export function scanBlocks(source) {
                 opening = null;
                 continue;
             }
+            if (opening.name === "poetry" && opening.attributes.syllables) {
+                const expected = opening.attributes.syllables.split(",").length;
+                const actual = verseLines(body).length;
+                if (expected !== actual)
+                    errors.push({
+                        line: opening.start + 1,
+                        column: 1,
+                        message: `poetry syllables= gives ${expected} counts for ${actual} verse lines`,
+                    });
+            }
             // An H1, or an anchored heading at any level, starts a Foundry
             // journal page — splitting the block's own page in two and
             // publishing the rest with no wrapper around it, a GM-only
             // section included. Refused rather than split: a lower heading
             // with no anchor is still the ordinary way to structure a box.
-            for (let at = opening.start + 1; at < i; at++) {
+            // Poetry treats those same characters as verse text.
+            for (let at = opening.start + 1; opening.name !== "poetry" && at < i; at++) {
                 if (!parseHeadingLine(lines[at])?.startsPage) continue;
                 const article = /^[aeiou]/i.test(opening.name) ? "an" : "a";
                 errors.push({
@@ -198,7 +222,8 @@ export function scanBlocks(source) {
             continue;
         }
 
-        const open = OPEN.exec(line);
+        const indentedPoetry = INDENTED_POETRY_OPEN.exec(line);
+        const open = OPEN.exec(line) ?? (indentedPoetry && [line, "poetry", indentedPoetry[1]]);
         if (!open) continue;
         const [, name, raw = ""] = open;
         const at = { line: i + 1, column: 1 };
@@ -207,7 +232,7 @@ export function scanBlocks(source) {
             else foreignOutside += 1;
             continue;
         }
-        if (!Object.hasOwn(BLOCK_NAMES, name)) {
+        if (!Object.hasOwn(BLOCK_NAMES, name) && name !== "poetry") {
             errors.push({ ...at, message: `there is no ${name} block; the blocks are ${names()}` });
             opening = { start: i, rejected: true };
             continue;
@@ -254,11 +279,30 @@ export function scanBlocks(source) {
                 continue;
             }
             for (const [key, value] of Object.entries(parsed.values)) {
+                if (name === "poetry") {
+                    if (!["form", "meter", "rhyme", "syllables", "lang"].includes(key))
+                        errors.push({ ...at, message: `${key}= is not a poetry attribute` });
+                    else if (key === "syllables" && !/^[1-9]\d*(?:,[1-9]\d*)*$/.test(value))
+                        errors.push({
+                            ...at,
+                            message: "poetry syllables= needs positive comma-separated counts",
+                        });
+                    else if (key === "lang" && !/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/.test(value))
+                        errors.push({ ...at, message: "poetry lang= needs a language tag" });
+                }
                 if (key === TITLE) title = value;
                 else attributes[key] = value;
             }
         }
-        opening = { start: i, name, title, id, classes, attributes };
+        opening = {
+            start: i,
+            name,
+            title,
+            id,
+            classes,
+            attributes,
+            indent: name === "poetry" ? /^ */.exec(line)[0] : "",
+        };
     }
 
     if (opening && !opening.rejected) {
@@ -295,11 +339,26 @@ function attributeText(block, target, classes) {
     const parts = [`class="${escapeAttribute(classes.join(" "))}"`];
     if (id) parts.push(`id="${escapeAttribute(id)}"`);
     for (const [key, value] of Object.entries(block.attributes)) {
-        parts.push(`${key}="${escapeAttribute(value)}"`);
+        const attribute = block.name === "poetry" && key !== "lang" ? `data-${key}` : key;
+        parts.push(`${attribute}="${escapeAttribute(value)}"`);
     }
     return parts.join(" ");
 }
 
+/** Keep a poem in its list, without turning standalone readable indentation into code. */
+function poetryWrapperIndent(lines, block) {
+    const indent = block.indent;
+    if (indent.length < 4) return indent;
+    for (let at = block.start - 1; at >= 0; at--) {
+        const line = lines[at];
+        if (!line.trim()) continue;
+        const leading = /^ */.exec(line)[0].length;
+        if (/^ *(?:[-+*]|\d+[.)]) +/.test(line) && leading < indent.length) return indent;
+        if (leading < indent.length) break;
+    }
+    return "";
+}
+
 /**
  * Render named blocks for one publishing surface.
  *
@@ -327,7 +386,6 @@ export function renderBlocks(source, target) {
         output.push(...lines.slice(cursor, block.start));
         const classes = [block.name, ...block.classes];
         const attributes = attributeText(block, target, classes);
-        const title = titleParser.renderInline(block.title);
         // A container's body may hold a block of its own, rendered first so
         // its own wrapper is already written when the outer one wraps it in
         // turn — nesting composes because each level is markdown-with-raw-HTML
@@ -336,6 +394,17 @@ export function renderBlocks(source, target) {
             BLOCK_CONTAINERS.includes(block.name) ?
                 renderBlocks(block.body, target).markdown
             :   block.body;
+        if (block.name === "poetry") {
+            const indent = poetryWrapperIndent(lines, block);
+            const verses = poetryMarkdown(held)
+                .split("\n")
+                .map((line) => (line ? `${indent}${line}` : line))
+                .join("\n");
+            output.push("", `${indent}<div ${attributes}>`, "", verses, "", `${indent}</div>`, "");
+            cursor = block.end + 1;
+            continue;
+        }
+        const title = titleParser.renderInline(block.title);
         if (target === "foundry") {
             output.push(
                 "",

package/engine/content-figures.mjs

@@ -107,6 +107,7 @@ export const FIGURE_NAMES = Object.freeze({
     table: "Table",
     figure: "Figure",
     map: "Map",
+    poem: "Poem",
     prose: "Prose",
 });
 
@@ -204,9 +205,10 @@ function picturesAreMap(contents, resolveRole) {
  * @param {string} contents - The contents, trimmed.
  * @param {(address: string) => string|undefined} resolveRole - The caller's
  *   lookup from a picture's address to the role its asset declares.
- * @returns {"code"|"table"|"figure"|"map"|"prose"} The kind.
+ * @returns {"code"|"table"|"figure"|"map"|"poem"|"prose"} The kind.
  */
 function figureKind(first, contents, resolveRole) {
+    if (/^(?: *:::poetry(?:\s|$)|<div\b[^>]*\bclass="poetry(?:\s|"))/.test(contents)) return "poem";
     if (first?.type === "table_open") return "table";
     if (first?.type === "fence" && /^\s*sql\b/i.test(first.info ?? "")) return "table";
     if (first?.type === "fence" || first?.type === "code_block") return "code";
@@ -240,7 +242,7 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
     const lines = String(source ?? "").split("\n");
     const figures = [];
     const errors = [];
-    const counts = { code: 0, table: 0, figure: 0, map: 0, prose: 0 };
+    const counts = { code: 0, table: 0, figure: 0, map: 0, poem: 0, prose: 0 };
     const ids = new Set();
     const headingIds = [];
     let codeFence = null;
@@ -292,10 +294,17 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
         let close = start + 1;
         let split = -1;
         let nested = null;
+        let namedDepth = 0;
         const fenced = new Set();
         while (close < lines.length) {
             const body = lines[close];
             const bodyFence = FENCE.exec(body);
+            if (namedDepth) {
+                fenced.add(close);
+                if (/^ *:::[ \t]*$/.test(body)) namedDepth--;
+                close++;
+                continue;
+            }
             if (nested) {
                 fenced.add(close);
                 if (
@@ -313,6 +322,12 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
                 close++;
                 continue;
             }
+            if (/^ *:::poetry(?:\s|$)/.test(body)) {
+                namedDepth++;
+                fenced.add(close);
+                close++;
+                continue;
+            }
             if (CLOSE.test(body)) break;
             if (SPLIT.test(body)) {
                 if (split < 0) split = close;
@@ -446,7 +461,7 @@ export function renderFigureBlocks(
         output.push(...lines.slice(cursor, figure.line - 1));
         const numbered = (figure.id ? byId.get(figure.id) : null) ?? figure;
         const contents = lines.slice(figure.bodyStart, figure.bodyEnd).join("\n");
-        const classes = ["content-figure", `content-figure-${figure.kind}`, ...figure.classes];
+        const classes = ["content-figure", `content-figure-${numbered.kind}`, ...figure.classes];
         const id = figure.slug ? ` id="${escapeHtml(figure.slug)}"` : "";
         output.push(`<div${id} class="${escapeHtml(classes.join(" "))}">`);
         if (figure.kind === "figure" || figure.kind === "map") {

package/engine/content-poetry.mjs

@@ -0,0 +1,61 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+/** The authored verse lines, excluding stanza separators. */
+export function verseLines(body) {
+    return String(body ?? "")
+        .split("\n")
+        .filter((line) => line.trim());
+}
+
+/**
+ * The least-indented verse is level zero. Every two additional leading spaces
+ * add one level; a leftover space is discarded and the level stops at eight.
+ * Blank lines divide stanzas rather than contributing to the baseline.
+ */
+export function poetryStanzas(body) {
+    const lines = String(body ?? "").split("\n");
+    const verses = verseLines(body);
+    if (!verses.length) return [];
+    const baseline = Math.min(...verses.map((line) => /^ */.exec(line)[0].length));
+    const stanzas = [];
+    let stanza = [];
+    for (const line of lines) {
+        if (!line.trim()) {
+            if (stanza.length) stanzas.push(stanza);
+            stanza = [];
+            continue;
+        }
+        const spaces = /^ */.exec(line)[0].length;
+        stanza.push({
+            text: line.slice(spaces).trimEnd(),
+            level: Math.min(8, Math.floor((spaces - baseline) / 2)),
+        });
+    }
+    if (stanza.length) stanzas.push(stanza);
+    return stanzas;
+}
+
+/** A verse is inline Markdown even when it starts with block syntax. */
+export function inlineVerse(text) {
+    return String(text)
+        .replace(/^(#{1,6}\s|>\s|[-+*]\s|:{1,2}\s|`{3,}|~{3,}|-{3,}\s*$)/, "\\$1")
+        .replace(/^(\d+)([.)])\s/, "$1\\$2 ");
+}
+
+/**
+ * Keep stanzas as Markdown paragraphs and make every verse line a hard break.
+ * The surrounding renderer still sees the entire note, so links and footnote
+ * definitions remain in scope. The span carries the indent for each line.
+ */
+export function poetryMarkdown(body) {
+    return poetryStanzas(body)
+        .map((stanza) =>
+            stanza
+                .map(
+                    ({ text, level }) =>
+                        `<span class="poetry-line${level ? ` i${level}` : ""}">${inlineVerse(text)}</span>`,
+                )
+                .join("  \n"),
+        )
+        .join("\n\n");
+}

package/engine/foreign-catalog.mjs

@@ -62,7 +62,6 @@ import os from "node:os";
 import path from "node:path";
 
 import { unzipSync } from "fflate";
-import { extractPack } from "@foundryvtt/foundryvtt-cli";
 
 import log from "loglevel";
 
@@ -326,6 +325,8 @@ async function extractItemPacks(id, version, manifest, root, dir) {
                 `cannot supply an item catalogue`,
         );
     }
+    // Loaded here so importing the content index does not load the extractor.
+    const { extractPack } = await import("@foundryvtt/foundryvtt-cli");
     for (const pack of itemPacks) {
         const src = resolvePackPath(root, pack.path);
         if (!src) {

package/engine/helpers.mjs

@@ -617,9 +617,11 @@ export function makeFilename(name, id) {
  * apply to.
  *
  * **`banner:` does not follow it either, deliberately.** It is not a file
- * inside a Foundry install: it reaches no compiled document and no book, its
- * only consumer is the Hugo theme, and the theme resolves it against the site's
- * own asset root. See `docs/content-format.md`.
+ * inside a Foundry install: it reaches no compiled document, and the site build
+ * resolves it through the website's own resolver before a page is written, so
+ * the theme receives a URL rather than an address. The book's section plates
+ * read a banner of their own, from the book plan's `presentation.page.banner`
+ * rather than from a note. See `docs/guides/site.md`.
  *
  * For items, the default is the art paired with the type's builder, reached
  * through `itemArt()`, which runs the pathname back through this function so a

package/engine/note-vocabulary.mjs

@@ -105,7 +105,7 @@ import { checkSocialTies } from "./social-ties.mjs";
 import { checkStandings } from "./standings.mjs";
 import { STANDING_BODY_TYPES } from "./standing-terms.mjs";
 import { checkDatedOffices } from "./office-holders.mjs";
-import { checkRankLadder } from "./rank-ladder.mjs";
+import { checkAffiliationRankFloor, checkRankLadder } from "./rank-ladder.mjs";
 import { checkCalendarChoice } from "./calendar-choice.mjs";
 import { checkLoreEvents } from "./lore-events.mjs";
 import { checkCultureChoice } from "./culture-choice.mjs";
@@ -1014,6 +1014,7 @@ export const NOTE_VOCABULARY = Object.freeze({
 
     affiliation: Object.freeze({
         stubbable: true,
+        check: checkAffiliationRankFloor,
         subTypes: Object.freeze([
             "guild",
             "order",

package/engine/pdf-build.mjs

@@ -744,7 +744,7 @@ export async function buildPdf({
      * @param {number} columns - The entry's page columns.
      * @returns {string} Typst markup.
      */
-    const figureCounts = { code: 0, table: 0, figure: 0, map: 0, prose: 0 };
+    const figureCounts = { code: 0, table: 0, figure: 0, map: 0, poem: 0, prose: 0 };
     // The role lookup a `:::figure` fence's `map` counter reaches through —
     // see `engine/content-figures.mjs`'s `resolveRole`. Addressed form, for a
     // page's own scan below, which runs before its embeds are rewritten into

package/engine/pdf-render.mjs

@@ -88,6 +88,7 @@ export const BOOK_IMAGE_WIDTHS = Object.freeze({
 import { slugify } from "./content-slug.mjs";
 import { scanFigures } from "./content-figures.mjs";
 import { BLOCK_CONTAINERS, scanBlocks, BLOCK_NAMES } from "./content-blocks.mjs";
+import { inlineVerse, poetryStanzas } from "./content-poetry.mjs";
 import { matchAllOutsideCode, replaceOutsideCode } from "./code-fences.mjs";
 import { HTML_TAG, htmlMessage } from "./content-html.mjs";
 import { EXPRESSION } from "./markdown-expressions.mjs";
@@ -526,7 +527,16 @@ export function markdownToTypst(markdown, opts = {}) {
         }
     }
     if (!opts.insideAdmonition) {
-        const { blocks } = scanBlocks(source);
+        const figuresHoldingPoetry = scanFigures(source).figures;
+        const blocks = scanBlocks(source).blocks.filter(
+            (block) =>
+                !figuresHoldingPoetry.some(
+                    (figure) =>
+                        block.name === "poetry" &&
+                        block.start >= figure.bodyStart &&
+                        block.end < figure.bodyEnd,
+                ),
+        );
         if (blocks.length) {
             const lines = source.split("\n");
             const output = [];
@@ -538,6 +548,24 @@ export function markdownToTypst(markdown, opts = {}) {
                         insideAdmonition: true,
                     }),
                 );
+                if (block.name === "poetry") {
+                    const content = poetryStanzas(block.body)
+                        .map((stanza) =>
+                            stanza
+                                .map(({ text, level }) => {
+                                    const verse = markdownToTypst(inlineVerse(text), {
+                                        ...sharedOptions,
+                                        insideAdmonition: true,
+                                    });
+                                    return `${level ? `#h(${level * 1.25}em)` : ""}${verse}`;
+                                })
+                                .join(" \\\n"),
+                        )
+                        .join("\n\n");
+                    output.push(`\n#block(width: 100%)[${content}]\n`);
+                    cursor = block.end + 1;
+                    continue;
+                }
                 const { color, background, symbol } = BLOCK_PRINT[block.name];
                 // The title is inline markdown, rendered the way every other
                 // phrase in the book is. Set as it was written it would be read
@@ -601,7 +629,9 @@ export function markdownToTypst(markdown, opts = {}) {
                 { ...caption, imagesRemaining: { n: countImages(block) } }
             :   caption;
         const segments = [
-            renderMarkdownSegment(block, md, { ...ctx, caption: captioned }, definitions),
+            caption.kind === "poem" ?
+                markdownToTypst(block, { ...sharedOptions, captions: undefined })
+            :   renderMarkdownSegment(block, md, { ...ctx, caption: captioned }, definitions),
         ];
         if (caption.kind !== "table" && caption.kind !== "figure" && caption.kind !== "map") {
             segments.push(

package/engine/rank-ladder.mjs

@@ -50,6 +50,38 @@ const RUNG_KEYS = Object.freeze(["level", "title", "description", "lore"]);
 /** The keys a rung must carry a value for. */
 const REQUIRED_TEXT = Object.freeze(["title", "description"]);
 
+/** Every affiliation has an ordinary standing that a being can name as rank 1. */
+export function checkAffiliationRankFloor(note) {
+    if (note.fm?.type !== "affiliation") return [];
+    const governance = note.fm?.data?.governance;
+    const ranks = governance?.ranks;
+    // A non-list already has a shape finding. Do not repeat it here.
+    if (ranks !== undefined && ranks !== null && !Array.isArray(ranks)) return [];
+    if (
+        Array.isArray(ranks) &&
+        ranks.some((rung) => integer(rung?.level) && Number(rung.level) === 1)
+    )
+        return [];
+
+    const path = Array.isArray(ranks) ? ["data", "governance", "ranks"] : ["data", "governance"];
+    const atRankOrGovernance = positionOfFrontmatterPath(note.raw ?? "", path, { key: true });
+    const position =
+        atRankOrGovernance.line !== undefined ?
+            atRankOrGovernance
+        :   positionOfFrontmatterPath(note.raw ?? "", ["data"], { key: true });
+    return [
+        {
+            file: note.file,
+            ...position,
+            severity: "error",
+            message:
+                !Array.isArray(ranks) || ranks.length === 0 ?
+                    "affiliation needs data.governance.ranks with a level 1 standing"
+                :   "affiliation data.governance.ranks needs a level 1 standing",
+        },
+    ];
+}
+
 /**
  * Whether a value is a YAML mapping rather than a list or a scalar.
  *

package/engine/site-config.mjs

@@ -42,6 +42,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { stringify as stringifyToml } from "smol-toml";
 
 import { checkHomepage, fail } from "../config.mjs";
@@ -61,10 +62,15 @@ export const HUGO_CONTENT = `${HUGO_SOURCE}/content`;
  */
 export const DEPLOY_ROOT = "build/site";
 
-/** The npm package the shared theme arrives as. */
-export const THEME_PACKAGE = "@heroiclands/hugo-theme";
+/**
+ * This package's own root, which is the directory Hugo reads themes from.
+ *
+ * The theme ships inside this package, so the directory holding it is found
+ * from this module's own location rather than searched for.
+ */
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
-/** The theme's name under `themesDir`, which is the package's unscoped name. */
+/** The theme's directory name under `themesDir`. */
 export const THEME = "hugo-theme";
 
 /** The locale every site renders in. */
@@ -308,33 +314,22 @@ export async function fetchNavigation(
 
 /**
  * The `themesDir` for a repository, as the path from `build/hugo/` to the
- * directory holding the installed theme.
+ * directory holding the theme.
+ *
+ * The theme ships inside this package at `hugo-theme/`, so the directory Hugo
+ * reads themes from is {@link PACKAGE_ROOT}. `theme` stays {@link THEME}, so
+ * Hugo opens `<themesDir>/hugo-theme/layouts`.
  *
- * Resolved the way Node resolves a package — `node_modules/` in the
- * repository root, then in each parent — and written as a path rather than
- * assumed, so a worktree that resolves its parent's install says so in the
- * generated file.
+ * Written as a path rather than assumed: `build/hugo/` and the installed
+ * package sit at whatever distance the install put them, and a worktree
+ * resolving its parent's install says so in the generated file.
  *
  * @param {string} rootDir - The repository root.
  * @returns {string} The relative path, POSIX-separated.
- * @throws {Error} When the theme is installed nowhere above the root.
  */
 export function resolveThemesDir(rootDir) {
-    let dir = path.resolve(rootDir);
-    for (;;) {
-        const scope = path.join(dir, "node_modules", path.dirname(THEME_PACKAGE));
-        if (fs.existsSync(path.join(scope, path.basename(THEME_PACKAGE), "theme.toml"))) {
-            const rel = path.relative(path.resolve(rootDir, HUGO_SOURCE), scope);
-            return rel.split(path.sep).join("/");
-        }
-        const parent = path.dirname(dir);
-        if (parent === dir) break;
-        dir = parent;
-    }
-    throw new Error(
-        `${THEME_PACKAGE} is not installed anywhere above ${rootDir} — add it to ` +
-            "`devDependencies` and run `npm ci`",
-    );
+    const from = path.resolve(rootDir, HUGO_SOURCE);
+    return path.relative(from, PACKAGE_ROOT).split(path.sep).join("/");
 }
 
 /**

package/hugo-theme/data/banners.yaml

@@ -0,0 +1,69 @@
+# Which banner images exist in the shared artwork set.
+#
+# `partials/hero-banner.html` resolves a page's hero image to a path under
+# `images/banners/`, and that path is emitted into a `background-image` with no
+# way to test it: the artwork is served from the consuming site's
+# `params.cdnBaseURL`, and Hugo cannot ask a remote host whether a URL exists.
+# So a banner that was never drawn used to 404 in silence — the band rendered
+# with its title, palette and gradient intact and a dead image URL behind it,
+# and nothing failed: not the build, not Hugo, not the deploy guard
+# (issue #36).
+#
+# This file is the declaration that replaces that missing test. A name listed
+# here is asserted to exist; a resolved banner whose name is absent falls back
+# to `default.webp` and Hugo warns once for it during the consumer's build.
+#
+# It speaks for the names this theme resolves itself — a hand-authored
+# `banner:` and the subtype defaults below. A note's own `data.banner` arrives
+# already resolved from an asset Address, against a real asset record, so it is
+# used as given and never looked for here.
+#
+# Keeping it in step is not left to hope: `npm run lint:banners`
+# (`ci/check-banners.mjs`, part of `npm run lint`) fetches every name below
+# from a real asset host and fails on any non-200. Add a name here only after
+# the file is published, or the check will say so.
+#
+# A consumer publishing its own artwork set overrides the whole list by
+# shipping its own `data/banners.yaml` — Hugo reads the site's data directory
+# in preference to the theme's.
+
+# The asset root every name below is resolved under, and the name used when a
+# resolved banner is not in `available`. Both are relative to the consuming
+# site's `params.cdnBaseURL`, like every other image path in this theme.
+dir: images/banners
+fallback: default.webp
+
+# Verified against https://cdn.heroiclands.org on 2026-08-29.
+available:
+    - affliction
+    - armor-clothing
+    - character
+    - company
+    - containers
+    - continent
+    - creature
+    - default
+    - dev-docs
+    - faith
+    - fvtt-add-on-modules
+    - fvtt-cc-anvil
+    - misc-gear
+    - module-dnload
+    - mystical-abilities
+    - orators-chance
+    - organization
+    - pantheon
+    - people
+    - projectiles
+    - region
+    - rules
+    - settlement
+    - site
+    - skills-attributes
+    - sohl-icon-3d-1920x1080
+    - ta-kheperu-banner
+    - tamzir-banner
+    - tapestry-of-dreams
+    - trauma
+    - user-guide
+    - weapons