@heroiclands/package-build 22.23.0 → 22.24.0

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`
+# (`utils/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

package/hugo-theme/layouts/404.html

@@ -0,0 +1,85 @@
+{{- /*
+  "Page not found" page.
+
+  Hugo renders this template to `public/404.html`, and a static host such as
+  Cloudflare Pages serves that file — with a genuine HTTP 404 — for any path
+  the deployment does not publish. Without it, Pages falls back to the site
+  root, so an unknown path answers 200 with the landing page: a soft-404 that
+  makes every "does this URL resolve?" check report success, and lets search
+  engines index retired content as live (issue #1416).
+
+  Every consumer needs exactly this, so it lives here rather than being copied
+  into each one (issue #1454). The theme carries layout, not addresses, so the
+  wording and the routes back are supplied by the consuming site:
+
+    [params.notfound]
+      heroimage = "images/banner.webp"   # CDN-relative or absolute
+      tagline   = "This site has no page at"
+      sitenoun  = "site"                 # used in the body prose
+      [[params.notfound.links]]
+        title = "Home"
+        url   = "/"                      # relURL'd unless already absolute
+        text  = "Everything, from the top."
+
+  Each is guarded: a consumer supplying none still builds, and simply gets the
+  generic wording with no list of routes back.
+*/ -}}
+{{ define "main" }}
+{{- $nf := .Site.Params.notfound | default dict -}}
+{{- $img := $nf.heroimage | default "images/banners/default.webp" -}}
+{{- $heroURL := partial "cdn-url.html" (dict "site" .Site "path" $img) -}}
+{{- $tagline := $nf.tagline | default "This site has no page at" -}}
+{{- $noun := $nf.sitenoun | default "site" -}}
+<section class="hero hero-with-image" style="background-image: url('{{ $heroURL }}');">
+  <div class="hero-inner" data-pagefind-ignore>
+    <h1>Page not found</h1>
+    <p class="hero-tagline">{{ $tagline }} <code id="missing-path">the address you followed</code>.</p>
+  </div>
+</section>
+
+<article class="single">
+  <div class="single-content">
+    <div class="single-body">
+      <p>
+        The page may have been renamed, moved to another part of the
+        {{ $noun }}, or retired along with the concept it described. Links
+        from older discussions, issues, and search results can outlive the
+        pages they point at.
+      </p>
+      {{- with $nf.links }}
+      <p>Start again from one of these:</p>
+      <ul class="page-list">
+        {{- range . }}
+        {{- $url := .url -}}
+        {{- if not (or (hasPrefix $url "http://") (hasPrefix $url "https://") (hasPrefix $url "//")) -}}
+          {{- /* relURL only mounts a path under the site's base when it is
+                 given relative: a leading slash means "from the origin", and
+                 the base path is left off. Trim it, so a consumer writing the
+                 obvious "/section/" gets a link inside its own site even when
+                 that site is served under a prefix. */ -}}
+          {{- $url = strings.TrimPrefix "/" $url | relURL -}}
+        {{- end }}
+        <li class="page-list-item">
+          <a class="page-list-title" href="{{ $url }}">{{ .title }}</a>
+          {{- with .text }}
+          <span class="page-list-desc">{{ . }}</span>
+          {{- end }}
+        </li>
+        {{- end }}
+      </ul>
+      {{- end }}
+    </div>
+  </div>
+</article>
+
+{{/* Name the address that failed, so a reader can see what they followed and
+     quote it in a bug report. Static hosting cannot template it — Pages serves
+     this one file for every unmatched path — so it is filled in client-side,
+     and the markup above reads sensibly without scripting. */}}
+<script>
+  (function () {
+    var el = document.getElementById("missing-path");
+    if (el) el.textContent = window.location.pathname;
+  })();
+</script>
+{{ end }}

package/hugo-theme/layouts/_default/baseof.html

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{ if not .IsHome }}{{ .Title }} — {{ end }}{{ .Site.Title }}</title>
+  <meta name="description" content="{{ with .Params.description }}{{ . }}{{ else }}{{ .Site.Params.description }}{{ end }}">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Cinzel:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&family=Lora:ital,wght@0,400;0,500;0,600;0,700;1,400;1,500;1,600&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="{{ "css/style.css" | relURL }}">
+  {{/* Icon glyphs. SoHL documentation writes icons as <i class="fa-solid …">
+       or <i class="ginf-…">, the same markup the Foundry client renders, so a
+       page reads identically in a journal and here. Font Awesome's FREE set is
+       enough — the system deliberately uses no Pro-only icons — and the
+       game-icons webfont is subset to just the glyphs the docs reference
+       (~3 KB), generated by the SoHL repo. */}}
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.1/css/all.min.css" crossorigin="anonymous" referrerpolicy="no-referrer">
+  <link rel="stylesheet" href="{{ "css/sohl-icons.css" | relURL }}">
+</head>
+<body>
+  {{ partial "header.html" . }}
+  <main>
+    {{ block "main" . }}{{ end }}
+  </main>
+  {{ partial "footer.html" . }}
+  <script>
+  // Auto-enhance <span data-copy="URL"> elements with a clipboard copy button
+  document.querySelectorAll('[data-copy]').forEach(function(el) {
+    var url = el.getAttribute('data-copy');
+    el.classList.add('exturl');
+
+    // Wrap existing text in a code element if not already
+    if (!el.querySelector('.exturl-text')) {
+      var code = document.createElement('code');
+      code.className = 'exturl-text';
+      code.textContent = el.textContent;
+      el.textContent = '';
+      el.appendChild(code);
+    }
+
+    var btn = document.createElement('button');
+    btn.className = 'exturl-copy';
+    btn.title = 'Copy URL to clipboard';
+    btn.setAttribute('aria-label', 'Copy URL to clipboard');
+    btn.innerHTML =
+      '<svg class="exturl-icon" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' +
+        '<rect x="9" y="9" width="13" height="13" rx="2" ry="2"/>' +
+        '<path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1"/>' +
+      '</svg>' +
+      '<svg class="exturl-check" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">' +
+        '<polyline points="20 6 9 17 4 12"/>' +
+      '</svg>';
+    btn.addEventListener('click', function() {
+      navigator.clipboard.writeText(url).then(function() {
+        btn.classList.add('copied');
+        setTimeout(function() { btn.classList.remove('copied'); }, 1500);
+      });
+    });
+    el.appendChild(btn);
+  });
+  </script>
+</body>
+</html>

package/hugo-theme/layouts/_default/list.html

@@ -0,0 +1,139 @@
+{{- /*
+  Default list layout: hero, the authored body when there is one,
+  and an auto-list of the section's members.
+
+  Minimal by design: a package-build consumer disables Hugo's `section`,
+  `taxonomy` and `term` kinds, so this layout never runs for one — the home
+  page and its pages are all it renders through `index.html` and
+  `_default/single.html`. A site that keeps those kinds enabled — one that
+  is not a package-build consumer, publishing a hand-curated section of its
+  own — still needs a landing for them, which is what this file is for.
+
+  Content rows render "Name + description", inline rather than through a
+  shared partial: this is the only caller left, and a description is emitted
+  only when present, so a page carrying none renders a plain title row.
+*/ -}}
+{{ define "main" }}
+{{ partial "hero-banner.html" . }}
+<article class="single">
+  <div class="single-content">
+    {{ if .Content }}
+    <div class="single-body" data-pagefind-body>
+      {{ .Content }}
+    </div>
+    {{ end }}
+
+    {{- /*
+      A curated landing is the best navigation — a rules section groups its
+      pages under editorial headings like "Key Concepts", which no hierarchy
+      can infer. But gating the auto-list on "has no body" meant authoring an
+      intro silently replaced the section's ONLY navigation, and hand-curated
+      lists drift: one guide reached 41 pages linking 1, and another had
+      quietly orphaned a page.
+
+      So the auto-list is a GAP-FILLER: a section with a body lists only the
+      pages that are not reachable from that body by following links. A landing
+      whose hierarchy covers everything shows nothing extra, and a page can
+      never become unreachable — a newly added page appears under "Orphaned
+      Pages" until someone files it into the curated index.
+
+      Taxonomy and term pages keep their own listing shapes below.
+    */ -}}
+    {{- $showAutoList :=
+      or (eq .Kind "taxonomy")
+         (eq .Kind "term")
+         (eq .Kind "section")
+    -}}
+    {{- $members := .Pages -}}
+    {{- /*
+      Pages reachable from the authored body, matched on RelPermalink so the
+      comparison survives aliases and wikilink resolution.
+
+      The needle deliberately stops after the URL rather than closing the quote,
+      so a link that carries a fragment counts. A rules landing reaches its
+      Characters chapter as `…/characters-introduction/#body-structure`, and
+      demanding the closing quote made that chapter read as unlinked. A trailing
+      slash ends every RelPermalink, so the open-ended match cannot bleed into a
+      sibling (`/rules/fate/` never prefixes `/rules/fate-points/`).
+
+      Reachability is TRANSITIVE, because a curated corpus is a hierarchy rather
+      than a flat index: a rules landing links ten chapter introductions, and
+      each of those links its own pages — up to four hops deep (root → Trauma →
+      Body → Injury → Bleeding). Testing only what the landing links DIRECTLY
+      counted every page below the first hop as a leftover. So a page counts as
+      listed when the body links it, or when any page already counted as listed
+      links it.
+
+      The walk runs to a fixed point: each pass appends the newly reached pages'
+      content to the haystack, and the first pass that reaches nothing new stops
+      it. Twelve passes is far past the depth of any corpus here (the rules need
+      four), and the `$growing` guard makes the surplus passes free.
+    */ -}}
+    {{- $unlisted := $members -}}
+    {{- if and (eq .Kind "section") .Content -}}
+      {{- $haystack := .Content -}}
+      {{- $reached := slice -}}
+      {{- $growing := true -}}
+      {{- range seq 12 -}}
+        {{- if $growing -}}
+          {{- $growing = false -}}
+          {{- range $members -}}
+            {{- if not (in $reached .RelPermalink) -}}
+              {{- if in $haystack (printf "href=\"%s" .RelPermalink) -}}
+                {{- $reached = $reached | append .RelPermalink -}}
+                {{- $haystack = print $haystack .Content -}}
+                {{- $growing = true -}}
+              {{- end -}}
+            {{- end -}}
+          {{- end -}}
+        {{- end -}}
+      {{- end -}}
+      {{- $unlisted = where $members "RelPermalink" "not in" $reached -}}
+    {{- end -}}
+    {{- /*
+      Label the leftovers only when a curated body precedes them. With
+      reachability transitive, anything still here is genuinely unreachable
+      by reading — an orphan — so the heading says so rather than claiming to be
+      the section's full contents.
+    */ -}}
+    {{- $labelList := and (eq .Kind "section") .Content -}}
+    {{- if $showAutoList -}}
+      {{- with $unlisted -}}
+        {{- if eq $.Kind "taxonomy" -}}
+        <ul class="page-list">
+          {{- range . }}
+          <li class="page-list-item">
+            <a class="page-list-title" href="{{ .RelPermalink }}">{{ .Title }}</a>
+            <span class="page-list-count">{{ len .Pages }}</span>
+          </li>
+          {{- end }}
+        </ul>
+        {{- else -}}
+          {{- if $labelList }}
+          <h2 class="page-list-heading">Orphaned Pages</h2>
+          {{- end }}
+          <ul class="page-list">
+            {{- range . }}
+            <li class="page-list-item">
+              <a class="page-list-title" href="{{ .RelPermalink }}">{{ .Title }}</a>
+              {{- with .Description }}
+              <span class="page-list-desc">{{ . }}</span>
+              {{- end }}
+            </li>
+            {{- end }}
+          </ul>
+        {{- end -}}
+      {{- else -}}
+      {{- /*
+        "Nothing here yet" is the right answer for an empty auto-listed section,
+        and the wrong one for a curated landing — there a leftover list of zero
+        means the hierarchy covers everything, so nothing should be said at all.
+      */ -}}
+        {{- if not $labelList -}}
+        <p class="page-list-empty">Nothing here yet.</p>
+        {{- end -}}
+      {{- end -}}
+    {{- end }}
+  </div>
+</article>
+{{ end }}

package/hugo-theme/layouts/_default/single.html

@@ -0,0 +1,4 @@
+{{ define "main" }}
+{{ partial "hero-banner.html" . }}
+{{ partial "page-body.html" . }}
+{{ end }}

package/hugo-theme/layouts/blog/list.html

@@ -0,0 +1,54 @@
+{{ define "main" }}
+{{ partial "hero-banner.html" . }}
+<article class="single">
+  <div class="single-content">
+    {{ if .Content }}
+    <div class="single-body">
+      {{ .Content }}
+    </div>
+    {{ end }}
+
+    {{- /* Blog list: walk every descendant page in any /blog/YYYY/MM/
+           date bucket, filter to actual blog posts, sort newest-first,
+           and emit a list of entries with date + series + title +
+           description. The default list.html skips auto-listing for
+           hand-crafted section indexes (any _index.md), which is
+           correct for most sections but wrong for a blog landing. */ -}}
+    {{- $posts := where .Site.RegularPages "Section" "blog" -}}
+    {{- $posts = where $posts "Type" "blog-post" -}}
+    {{- $posts = $posts.ByDate.Reverse -}}
+
+    {{- with $posts }}
+    <ul class="blog-list">
+      {{- range . }}
+      <li class="blog-list-item">
+        {{ if .Date }}
+        <time class="blog-list-date" datetime="{{ .Date.Format "2006-01-02" }}">{{ .Date.Format "January 2, 2006" }}</time>
+        {{ end }}
+        <a class="blog-list-title" href="{{ .RelPermalink }}">{{ .Title }}</a>
+        {{- /* Auto-generate a ~100-word preview from the rendered body.
+               `.Plain` strips HTML tags. `htmlUnescape` then decodes
+               entities so smart quotes Goldmark emitted as `&rsquo;`
+               etc. become real characters (otherwise the browser
+               displays them literally after Hugo re-escapes the `&`).
+               Collapse paragraph-break whitespace into single spaces,
+               and append an ellipsis only if we actually truncated. */ -}}
+        {{- $plain := .Plain | htmlUnescape -}}
+        {{- $collapsed := trim (replaceRE `\s+` " " $plain) " " -}}
+        {{- $words := split $collapsed " " -}}
+        {{- $preview := $collapsed -}}
+        {{- if gt (len $words) 100 -}}
+          {{- $preview = printf "%s…" (delimit (first 100 $words) " ") -}}
+        {{- end -}}
+        {{- with $preview }}
+        <p class="blog-list-desc">{{ . }}</p>
+        {{- end }}
+      </li>
+      {{- end }}
+    </ul>
+    {{- else }}
+    <p class="page-list-empty">No posts yet.</p>
+    {{- end }}
+  </div>
+</article>
+{{ end }}

package/hugo-theme/layouts/blog-post/single.html

@@ -0,0 +1,36 @@
+{{ define "main" }}
+{{ partial "hero-banner.html" . }}
+
+{{- /* Blog posts use the same content chrome as other pages but with
+       a blog-specific meta line (series + date) and no right-rail
+       sidebar or auto-generated TOC. If a post grows long enough to
+       warrant a TOC, we can opt it in via a frontmatter flag later. */ -}}
+
+<article class="single">
+  <div class="single-content">
+    <div class="single-meta blog-meta">
+      {{ with .Params.series }}
+      <div class="blog-series">
+        <span class="blog-series-label">Series</span>
+        <span class="blog-series-name">{{ . }}</span>
+      </div>
+      {{ end }}
+      {{ if .Params.date }}
+      <time class="single-date" datetime="{{ .Date.Format "2006-01-02" }}">{{ .Date.Format "January 2, 2006" }}</time>
+      {{ end }}
+      {{ partial "tags.html" . }}
+    </div>
+
+    <div class="single-body" data-pagefind-body>
+      {{ .Content }}
+    </div>
+
+    {{ partial "related.html" . }}
+
+    <nav class="single-nav">
+      {{ with .PrevInSection }}<a href="{{ .Permalink }}" class="nav-prev">&larr; {{ .Title }}</a>{{ end }}
+      {{ with .NextInSection }}<a href="{{ .Permalink }}" class="nav-next">{{ .Title }} &rarr;</a>{{ end }}
+    </nav>
+  </div>
+</article>
+{{ end }}

package/hugo-theme/layouts/index.html

@@ -0,0 +1,75 @@
+{{- /*
+  Home layout. Two shapes share it, chosen by what the home page carries.
+
+  **A package homepage** — the entry point to one published package, at its
+  own prefix (/sohl/, /thalorna/, /kethira/, …), mounted as the package's
+  `_index.md` and selected when it declares `type: homepage`. It renders
+  through the same structure `_default/single.html` gives a note — the hero
+  from its `banner`, then its body — through the shared `page-body.html`
+  partial, so a homepage and a page look like one family. A package supplies
+  only its own title, description, banner and body; the theme owns the
+  arrangement.
+
+  **The featured grid** — a site whose home page is a set of entry points into
+  everything it publishes. This is the older shape and stays the default, so a
+  consumer that has not adopted the homepage note keeps rendering exactly as
+  before.
+
+  The theme owns the arrangement; the consuming site owns every address and
+  every word. The grid reads them from `params.home`:
+
+    heroimage    Banner behind the hero band. Resolved through cdn-url.html,
+                 so it may be absolute or relative to `params.cdnBaseURL`.
+    herotitle    Hero heading.
+    herotagline  Hero standfirst.
+    headings     Column headings across the top row of the featured grid.
+                 Each: `title`, and an optional `class`, appended as
+                 `home-section-title--<class>` for grid placement.
+    cards        The entry-point cards. Each: `title`, `url`, `text`, and
+                 optional `image`, `alt` (image alt text, defaulting to
+                 `title`) and `key` (appended as `home-card--<key>` for
+                 grid placement).
+
+  Headings and cards render flat, as direct children of `.home-featured`,
+  because they are the grid's items — the CSS places each one by its
+  modifier class.
+*/ -}}
+{{ define "main" }}
+{{- if eq (.Params.type | default "") "homepage" -}}
+{{- partial "hero-banner.html" . -}}
+{{- partial "page-body.html" . -}}
+{{- else -}}
+{{- with .Site.Params.home }}
+<section class="hero hero-with-image"{{ with .heroimage }} style="background-image: url('{{ partial "cdn-url.html" (dict "site" $.Site "path" .) }}');"{{ end }}>
+  <div class="hero-inner" data-pagefind-ignore>
+    <h1>{{ .herotitle }}</h1>
+    {{- with .herotagline }}
+    <p class="hero-tagline">{{ . }}</p>
+    {{- end }}
+  </div>
+</section>
+
+<section class="home-sections">
+  <div class="home-featured">
+    {{- range .headings }}
+    <h2 class="home-section-title{{ with .class }} home-section-title--{{ . }}{{ end }}">{{ .title }}</h2>
+    {{- end }}
+    {{- range .cards }}
+
+    <div class="home-card{{ with .key }} home-card--{{ . }}{{ end }}">
+      {{- $url := .url }}{{ $title := .title }}{{ $alt := .alt | default .title }}
+      {{- with .image }}
+      <a href="{{ $url }}">
+        <img src="{{ partial "cdn-url.html" (dict "site" $.Site "path" .) }}" alt="{{ $alt }}" class="card-image">
+      </a>
+      {{- end }}
+      <h2><a href="{{ $url }}">{{ $title }}</a></h2>
+      <p>{{ .text }}</p>
+      <a href="{{ $url }}" class="card-button">More Info →</a>
+    </div>
+    {{- end }}
+  </div>
+</section>
+{{- end }}
+{{- end }}
+{{ end }}

package/hugo-theme/layouts/partials/banner-url.html

@@ -0,0 +1,117 @@
+{{- /*
+  Resolve a `banner:` value to a URL, or to "" when there is none.
+
+  Split out of `hero-banner.html` (issue #41): a single implementation is what
+  keeps a second caller from drifting the way issue #36 already failed once —
+  silently, behind a dead URL.
+
+  Resolution, in order:
+    1. `data.banner` — a note's own hero image, which the content build has
+       already resolved from an asset Address into the address its asset host
+       serves. It is used exactly as given. A blank one is a note naming no
+       hero image on purpose and declines an image.
+    2. `banner` — a hand-authored page's value. `none` (or `false`) declines an
+       image and returns "". A full URL is used as-is; anything else is a
+       fragment under `images/`.
+    3. `images/banners/{subtype}.webp`, when neither is set and a `subtype` is
+       supplied. A caller that passes no subtype gets "" instead, which is
+       what a card wants: a section with no banner of its own renders as the
+       text card it rendered before.
+    4. `images/banners/{fallback}` — whenever the name picked by 2 or 3 is not
+       in `data/banners.yaml`'s declared inventory. Hugo cannot ask a remote
+       host whether a URL exists, so the declaration stands in for the test;
+       see `hero-banner.html` for why, and `data/banners.yaml` for how the
+       list is kept honest.
+
+  The check applies only to a relative path resolving directly inside the
+  declared banner directory. An absolute URL, and a fragment pointing anywhere
+  else under `images/`, pass through untouched: the theme has no inventory for
+  either and must not second-guess an address it cannot know about. A step 1
+  address is never checked either — the build resolved it against a real asset
+  record and dropped one nothing answered, so there is no question left to
+  ask.
+
+  Whatever survives resolves through `cdn-url.html`, so the theme names a path
+  and never a host.
+
+  Usage:
+    {{ partial "banner-url.html" (dict "site" .Site "banner" .Params.banner
+                                       "subtype" $subtype "context" .RelPermalink) }}
+
+  Params:
+    site     — the site context (.Site), for `params.cdnBaseURL`.
+    data     — the page's `data` map (`.Params.data`), read for the `banner`
+               the content build resolved. Omit for a page that carries none.
+    banner   — the raw `banner:` value; may be unset, `none`/`false`, a
+               fragment or an absolute URL.
+    subtype  — optional. The name to default to when `banner` is unset. Omit
+               for "no banner means no image".
+    context  — optional. A page address, named in the missing-banner warning so
+               the report says where the want came from.
+*/ -}}
+{{- $site := .site -}}
+{{- $subtype := .subtype | default "" -}}
+{{- $context := .context | default "" -}}
+{{- $data := .data | default dict -}}
+
+{{- $banners := hugo.Data.banners | default dict -}}
+{{- $dir := $banners.dir | default "images/banners" -}}
+{{- $fallback := $banners.fallback | default "default.webp" -}}
+{{- $available := $banners.available | default slice -}}
+
+{{- /* `none`/`false` is a decision, not an absence, so it is read before the
+       resolution order rather than as a step in it. Formatted rather than
+       tested for truth, and deliberately not passed through `default`: both
+       `false` and an unset banner are falsy, and only formatting tells them
+       apart. */ -}}
+{{- $raw := printf "%v" .banner -}}
+{{- $declined := or (eq (lower $raw) "none") (eq $raw "false") -}}
+
+{{- /* A note's resolved banner, formatted for the same reason the decline
+       above is: an unset key and a deliberate blank are both falsy, and only
+       formatting tells them apart. `<nil>` covers both an absent key and an
+       explicit `null`, which the note format reads as *unset* — so the
+       resolution carries on to the subtype default. `""` is the format's
+       deliberate blank: a note naming no hero image, which declines one. */ -}}
+{{- $resolved := printf "%v" (index $data "banner") -}}
+{{- $fromBuild := ne $resolved "<nil>" -}}
+
+{{- $banner := "" -}}
+{{- $absolute := false -}}
+{{- if $fromBuild -}}
+  {{- $banner = $resolved -}}
+  {{- $absolute = true -}}
+{{- else if not $declined -}}
+  {{- with .banner -}}
+    {{- $banner = printf "images/%s" (strings.TrimPrefix "/" .) -}}
+    {{- if or (hasPrefix . "http://") (hasPrefix . "https://") (hasPrefix . "//") -}}
+      {{- $banner = . -}}
+      {{- $absolute = true -}}
+    {{- end -}}
+  {{- else -}}
+    {{- with $subtype -}}
+      {{- $banner = printf "%s/%s.webp" $dir . -}}
+    {{- end -}}
+  {{- end -}}
+
+  {{- /* The declared-existence check. Deduplicated by name, so a subtype with
+         no artwork is reported once per build rather than once per page. */ -}}
+  {{- if and $banner (not $absolute) (eq (path.Dir $banner) $dir) -}}
+    {{- $name := strings.TrimSuffix (path.Ext $banner) (path.Base $banner) -}}
+    {{- if not (in $available $name) -}}
+      {{- partialCached "warn-missing-banner.html" (dict
+          "name" $name
+          "dir" $dir
+          "fallback" $fallback
+          "context" $context
+        ) $name -}}
+      {{- $banner = printf "%s/%s" $dir $fallback -}}
+    {{- end -}}
+  {{- end -}}
+{{- end -}}
+
+{{- $url := "" -}}
+{{- if $banner -}}
+  {{- $url = partial "cdn-url.html" (dict "site" $site "path" $banner) -}}
+{{- end -}}
+{{- return $url -}}