@heroiclands/package-build 22.22.0 → 22.24.0

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

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

@@ -0,0 +1,36 @@
+{{- /*
+  Resolve an asset path against the consuming site's asset host.
+
+  The theme carries layout, not addresses: it never names the host its
+  imagery is served from. A consumer sets `params.cdnBaseURL` to the root of
+  wherever it publishes shared artwork, and every image reference in the
+  theme resolves through here.
+
+  Resolution:
+    1. An already-absolute path (http://, https://, //) is returned as-is,
+       so page frontmatter can point anywhere.
+    2. Otherwise the path is joined onto `params.cdnBaseURL`.
+    3. With no `params.cdnBaseURL` set, the path resolves against the site
+       itself via relURL — correct under a bare root *and* under a baseURL
+       carrying a path prefix.
+
+  Usage:
+    {{ partial "cdn-url.html" (dict "site" .Site "path" "images/x.webp") }}
+
+  Params:
+    site — the site context (.Site), for reading params.
+    path — the asset path, absolute or relative to the asset root.
+*/ -}}
+{{- $path := .path -}}
+{{- $url := "" -}}
+{{- if or (hasPrefix $path "http://") (hasPrefix $path "https://") (hasPrefix $path "//") -}}
+  {{- $url = $path -}}
+{{- else -}}
+  {{- $rel := strings.TrimPrefix "/" $path -}}
+  {{- with .site.Params.cdnBaseURL -}}
+    {{- $url = printf "%s/%s" (strings.TrimSuffix "/" .) $rel -}}
+  {{- else -}}
+    {{- $url = $rel | relURL -}}
+  {{- end -}}
+{{- end -}}
+{{- return $url -}}

package/hugo-theme/layouts/partials/draft-notice.html

@@ -0,0 +1,41 @@
+{{- /*
+  A page's statement that its own content is not settled.
+
+  A draft page reads exactly like a finished one, and a reader who is not told
+  assumes it is finished — so the page says so itself, at the head of the
+  article, above the infobox and above the prose. A reader deciding whether to
+  rely on an entry has to be told before they read it.
+
+  The label alone will not do. "Draft" names the writing, so it reads as rough
+  prose; what has to land is that the facts may change. The label and the
+  sentence are one unit, and the sentence carries the meaning by itself — which
+  is the floor this is built to, because the mark is a third-party font and the
+  rule is a stylesheet, and either can be absent.
+
+  The sentence is the theme's default and a consumer overrides it with
+  `params.draftNotice`, the way `params.notfound` supplies its own wording. The
+  theme states no consumer's name and no address.
+
+  The mark is `circle-exclamation`: a notice, not a hazard. Draft-ness is a
+  status, and a page in a corpus where one page in several carries one cannot
+  wear a hazard mark without teaching a reader to discount it. `aria-hidden`
+  keeps it out of a screen reader, where the label reads the same thing.
+
+  The sentence sets in italic and the label in bold roman. Every other word on
+  the page is the world describing itself; this sentence is the page speaking
+  about its own state, and italic is how a reader is told the voice has
+  changed. It is an `em`, so the italic arrives with the markup rather than
+  with the stylesheet, and a bold italic beside the mark would be one emphasis
+  too many.
+
+  Silent-disappear: a settled page emits nothing here.
+
+  Context: the page.
+*/ -}}
+{{- if partial "draft-state.html" . -}}
+{{- $notice := .Site.Params.draftNotice | default "This entry is unfinished. What it states may change, and nothing in it is settled." -}}
+<aside class="draft-notice">
+  <i class="fa-solid fa-circle-exclamation draft-notice-icon" aria-hidden="true"></i>
+  <p class="draft-notice-text"><strong class="draft-notice-label">Draft.</strong> <em>{{ $notice }}</em></p>
+</aside>
+{{ end -}}

package/hugo-theme/layouts/partials/draft-state.html

@@ -0,0 +1,26 @@
+{{- /*
+  Whether a page's note is an unfinished draft.
+
+  The `draft` tag is the authored signal, and it is the only one either side
+  can read: the content build asks it through its own single reader
+  (package-build/engine/note-vocabulary.mjs, `DRAFT_TAG`) and a theme cannot
+  import that, so the shared fact is the tag itself. It reaches the page
+  because the build copies a note's own front matter onto it.
+
+  It is spelled once, here. Two partials act on the state — the tag row leaves
+  it out of a page's subjects, and the notice states it — and a second literal
+  is how the two come apart.
+
+  Hugo's own reserved `draft: true` is a different thing entirely and is never
+  written by the build: a page carrying it is not rendered at all.
+
+  Context: the page. Returns "true" for a draft and "" for anything else, which
+  is what `if` reads.
+*/ -}}
+{{- $draft := false -}}
+{{- range .Params.tags -}}
+  {{- if eq (lower .) "draft" -}}
+    {{- $draft = true -}}
+  {{- end -}}
+{{- end -}}
+{{- return $draft -}}

package/hugo-theme/layouts/partials/footer.html

@@ -0,0 +1,29 @@
+<footer class="site-footer" data-pagefind-ignore>
+  <div class="footer-inner">
+    <p class="footer-text">
+      &copy; 2020&ndash;{{ now.Year }} Tom Rodriguez. Content under The World of Thalorna and Song of Heroic Lands is licensed under
+      <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0</a>; all other content is &copy; Tom Rodriguez, all rights reserved.{{ with .Site.Params.brand }}{{ with .licenseURL }} See 
+      <a href="{{ . }}">License</a>.{{ end }}{{ end }}
+    </p>
+    <div class="footer-links">
+      <a href="https://creativecommons.org/licenses/by-sa/4.0/">
+        <img src="https://licensebuttons.net/l/by-sa/4.0/88x31.png" alt="CC BY-SA 4.0" class="cc-badge">
+      </a>
+      {{- with .Site.Params.brand }}{{ with .discordURL }}
+      <a href="{{ . }}">
+        <svg width="24" height="19" viewBox="0 0 71 55" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+          <path d="M60.1 4.9A58.5 58.5 0 0045.4.2a.2.2 0 00-.2.1 40.8 40.8 0 00-1.8 3.7 54 54 0 00-16.2 0A39 39 0 0025.4.3a.2.2 0 00-.2-.1A58.4 58.4 0 0010.5 5a.2.2 0 00-.1 0A60 60 0 00.3 45.3a.2.2 0 000 .2 58.7 58.7 0 0017.7 9 .2.2 0 00.3-.1 42 42 0 003.6-5.9.2.2 0 00-.1-.3 38.6 38.6 0 01-5.5-2.6.2.2 0 01 0-.4c.4-.3.7-.6 1.1-.8a.2.2 0 01.2 0 41.9 41.9 0 0035.6 0 .2.2 0 01.2 0l1 .9a.2.2 0 010 .3 36.2 36.2 0 01-5.5 2.6.2.2 0 00-.1.4 47.1 47.1 0 003.6 5.8.2.2 0 00.2.1A58.5 58.5 0 0070.3 45.5a.2.2 0 000-.2A59.7 59.7 0 0060.2 5a.2.2 0 00-.1 0zM23.7 37.3c-3.5 0-6.4-3.2-6.4-7.1s2.8-7.1 6.4-7.1 6.5 3.2 6.4 7.1c0 3.9-2.8 7.1-6.4 7.1zm23.7 0c-3.5 0-6.4-3.2-6.4-7.1s2.8-7.1 6.4-7.1 6.5 3.2 6.4 7.1c0 3.9-2.8 7.1-6.4 7.1z"/>
+        </svg>
+        Discord
+      </a>
+      {{- end }}{{ end }}
+    </div>
+  </div>
+</footer>
+
+<script>
+document.querySelector('.nav-toggle')?.addEventListener('click', function() {
+  document.querySelector('.site-nav').classList.toggle('open');
+  this.classList.toggle('open');
+});
+</script>

package/hugo-theme/layouts/partials/header.html

@@ -0,0 +1,35 @@
+<header class="site-header" data-pagefind-ignore>
+  <div class="header-inner">
+    <a href="{{ .Site.Home.RelPermalink }}" class="site-title">
+      {{- with .Site.Params.brand }}{{ with .logo }}
+      <img src="{{ partial "cdn-url.html" (dict "site" $.Site "path" .) }}" alt="Heroic Lands" class="site-logo">
+      {{- end }}{{ end }}
+      <span class="title-main">Heroic Lands</span>
+    </a>
+    <div class="header-actions">
+      <nav class="site-nav">
+        {{ range .Site.Menus.main }}
+          {{ if .HasChildren }}
+            <div class="nav-dropdown">
+              <a href="{{ .URL }}" class="nav-link{{ if $.IsMenuCurrent "main" . }} active{{ end }}">
+                {{ .Name }}
+                <svg class="dropdown-arrow" width="10" height="6" viewBox="0 0 10 6" fill="currentColor"><path d="M1 1l4 4 4-4"/></svg>
+              </a>
+              <div class="dropdown-menu">
+                {{ range .Children }}
+                  <a href="{{ .URL }}" class="dropdown-item">{{ .Name }}</a>
+                {{ end }}
+              </div>
+            </div>
+          {{ else }}
+            <a href="{{ .URL }}" class="nav-link{{ if $.IsMenuCurrent "main" . }} active{{ end }}">{{ .Name }}</a>
+          {{ end }}
+        {{ end }}
+      </nav>
+      {{ partial "search.html" . }}
+      <button class="nav-toggle" aria-label="Toggle navigation">
+        <span></span><span></span><span></span>
+      </button>
+    </div>
+  </div>
+</header>

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

@@ -0,0 +1,86 @@
+{{- /*
+  Hero banner partial.
+
+  Displays a full-width banner band (using the same .hero.hero-with-image
+  classes as the homepage) with a centered page title and description
+  above the content.
+
+  Every path below resolves through cdn-url.html against the consuming
+  site's `params.cdnBaseURL`; the theme names no host of its own.
+
+  The resolution itself lives in `banner-url.html`, which a derived landing card
+  calls too. The order is documented in both places because this is where a
+  reader looking at a banner starts; that partial is where it happens.
+
+  Banner image resolution order:
+    1. .Params.data.banner         — a note's own hero image, which the content
+                                     build resolved from an asset Address into
+                                     the address its asset host serves. Used
+                                     exactly as given. A blank declines a hero
+                                     image; unset or `null` carries on.
+    2. .Params.banner              — a hand-authored page's value. `none` (or
+                                     `false`) declines a hero image entirely —
+                                     see "Declining" below. A full URL is used
+                                     as-is; anything else is treated as a
+                                     fragment under images/.
+    3. images/banners/{subtype}.webp — subtype-specific default, where
+                                     subtype = category for type=doc pages,
+                                     otherwise type
+    4. images/banners/default.webp — used when the page has no type, *and*
+                                     whenever the name picked by 2 or 3 is not
+                                     in the declared inventory (see below).
+
+  Existence, and why step 4 is a declaration rather than a test.
+  The image is served from the consumer's asset host, and Hugo cannot ask a
+  remote host whether a URL exists — so a name that was never drawn would be
+  emitted unchecked and 404 in silence, the band rendering with its title,
+  palette and gradient intact behind a dead URL. `data/banners.yaml`
+  is the declaration that stands in for the test it cannot make: a resolved name
+  absent from `available` falls back to `fallback` and warns once. That file
+  documents how the list is kept honest (`npm run lint:banners` fetches every
+  name and fails on a non-200), and a consumer publishing its own artwork set
+  overrides the whole list by shipping its own `data/banners.yaml`.
+
+  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 not checked either — the build resolved it against a real asset
+  record, so the question has already been answered.
+
+  Declining a hero image.
+  `banner: none` on a hand-authored page, and a blank `data.banner` on a note,
+  render the band with no image at all — the title, the palette
+  and the .hero-with-image gradient, which is what gives the band its presence.
+  This is not the same as having no banner yet: a package may have a standing
+  editorial reason to publish no imagery, and the fan-material carve-outs do.
+  Falling back to a default for them would substitute artwork where the
+  considered answer was "none", so declining has to be sayable.
+*/ -}}
+
+{{- /* For narrative content (type=doc) the meaningful kind of page lives in
+       `category` — continent, region, polity, faith, lore, etc. — so prefer
+       that when picking a default banner. */ -}}
+{{- $type := .Params.type | default "" -}}
+{{- $subtype := cond (eq $type "doc") (.Params.category | default "") $type -}}
+{{- if not $subtype }}{{ $subtype = "default" }}{{ end -}}
+
+{{- /* The order above, the `none` decision and the declared-existence check
+       all live in `banner-url.html`, which a derived landing card calls too
+       (issue #41). A hero band always wants the subtype default; a card never
+       does. */ -}}
+{{- $bannerURL := partial "banner-url.html" (dict
+    "site" .Site
+    "data" .Params.data
+    "banner" .Params.banner
+    "subtype" $subtype
+    "context" .RelPermalink) -}}
+
+<section class="hero hero-with-image"{{ with $bannerURL }} style="background-image: url('{{ . }}');"{{ end }}>
+  <div class="hero-inner" data-pagefind-ignore>
+    <h1>{{ .Title }}</h1>
+    {{- with .Params.description }}
+    <p class="hero-tagline">{{ . }}</p>
+    {{- end }}
+  </div>
+</section>

package/hugo-theme/layouts/partials/holdings/entry.html

@@ -0,0 +1,21 @@
+{{- /*
+  One entry of a holdings list — `{title, url, type, subType}`, as
+  `@heroiclands/package-build` derives from `contains`, `held_by` and
+  `holdings` (see the "holdings card" section of the README).
+
+  `url` is absent for a stub: a note with an empty body, which carries its
+  facts into every list that names it but publishes no page of its own. The
+  build omits the key outright rather than writing `url: null` — confirmed by
+  stringifying a stub entry through the same `gray-matter`/`js-yaml` path the
+  build writes frontmatter with — but `with` guards both the same way, since
+  a missing map key and an empty string both read false. This is the same
+  guard `infobox/entry.html` already applies to its own `{text, url}` shape.
+
+  Takes `entry` and the `class` its medium gives it.
+*/ -}}
+{{- $entry := .entry -}}
+{{- with $entry.url -}}
+<a class="{{ $.class }}" href="{{ . }}">{{ $entry.title }}</a>
+{{- else -}}
+<span class="{{ $.class }}">{{ $entry.title }}</span>
+{{- end -}}

package/hugo-theme/layouts/partials/holdings/kind-groups.html

@@ -0,0 +1,71 @@
+{{- /*
+  The kind-grouped body of a "Within" or "Holdings" table: its entries
+  broken into named groups by `subType`, in the closed order region,
+  settlement, site, structure, feature — the order a reader wants a place
+  hierarchy read in, not alphabetical. A `subType` outside that order, or
+  missing entirely, is grouped last, one group per remaining kind,
+  alphabetically by its `humanize`d label.
+
+  Each group is a CSS grid (`repeat(auto-fill, minmax(14em, 1fr))`, the same
+  the Related card uses) so a region with forty settlements stays scannable.
+
+  Takes the entries (a `HoldingsEntry` list). Renders nothing for an empty
+  list, so a caller can include it unconditionally once its own presence
+  check on the list has passed.
+*/ -}}
+{{- $entries := . -}}
+{{- $kindOrder := slice "region" "settlement" "site" "structure" "feature" -}}
+{{- $kindLabels := dict
+  "region"     "Regions"
+  "settlement" "Settlements"
+  "site"       "Sites"
+  "structure"  "Structures"
+  "feature"    "Features"
+-}}
+
+{{- /* Bucket entries by subType, defaulting an absent one to "". */ -}}
+{{- $byKind := dict -}}
+{{- range $entries -}}
+  {{- $kind := .subType | default "" -}}
+  {{- $existing := index $byKind $kind | default slice -}}
+  {{- $byKind = merge $byKind (dict $kind ($existing | append .)) -}}
+{{- end -}}
+
+{{- /* The closed order first. */ -}}
+{{- $groups := slice -}}
+{{- $seen := slice -}}
+{{- range $kindOrder -}}
+  {{- $kind := . -}}
+  {{- with index $byKind $kind -}}
+    {{- $groups = $groups | append (dict "label" (index $kindLabels $kind) "entries" .) -}}
+    {{- $seen = $seen | append $kind -}}
+  {{- end -}}
+{{- end -}}
+
+{{- /* Anything else — a kind outside the closed set, or none at all —
+       grouped last, alphabetically by its rendered label. */ -}}
+{{- $leftover := slice -}}
+{{- range $kind, $group := $byKind -}}
+  {{- if not (in $seen $kind) -}}
+    {{- $label := humanize $kind -}}
+    {{- if eq $kind "" -}}{{- $label = "Other" -}}{{- end -}}
+    {{- $leftover = $leftover | append (dict "label" $label "entries" $group) -}}
+  {{- end -}}
+{{- end -}}
+{{- if $leftover -}}
+  {{- $leftover = sort $leftover "label" "asc" -}}
+  {{- range $leftover -}}
+    {{- $groups = $groups | append . -}}
+  {{- end -}}
+{{- end -}}
+
+{{- range $groups }}
+<div class="holdings-kind-group">
+  <h4 class="holdings-kind-label">{{ .label }}</h4>
+  <ul class="holdings-table-grid">
+    {{- range .entries }}
+    <li>{{ partial "holdings/entry.html" (dict "entry" . "class" "holdings-entry-name") }}</li>
+    {{- end }}
+  </ul>
+</div>
+{{- end -}}