@heroiclands/package-build 22.22.0 → 22.24.0

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

@@ -0,0 +1,61 @@
+{{- /*
+  Holdings card.
+
+  Three small tables, rendered after the body and before the Related card
+  (see `page-body.html`), from front matter `@heroiclands/package-build`
+  derives and a note never authors itself:
+
+    contains:  [{ title, url, type, subType }]  places sitting within this one
+    held_by:   [{ title, url, type, subType }]  affiliations holding this place
+    holdings:  [{ title, url, type, subType }]  places this affiliation holds
+
+  A place page carries `contains` and/or `held_by`; an affiliation page
+  carries `holdings`. Neither is checked here — presence of the key is the
+  only test, the same silent-disappear convention the Related card follows:
+  a page carrying none of the three renders no card at all.
+
+  `contains` and `holdings` list places, so each is broken into groups by
+  kind (`holdings/kind-groups.html`) — the towns together, the hamlets
+  together. `held_by` lists affiliations, whose kinds have no fixed
+  hierarchy to group by, so it stays one flat grid with the kind printed
+  beside each name instead of as a group heading.
+
+  An entry's `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. `holdings/entry.html` renders such an entry as plain text and
+  every other entry as a link — see it for the guard and how its correctness
+  was established.
+*/ -}}
+{{- $within := .Params.contains -}}
+{{- $heldBy := .Params.held_by -}}
+{{- $holds := .Params.holdings -}}
+
+{{- if or $within $heldBy $holds -}}
+<section class="holdings" data-pagefind-ignore>
+  {{- with $within }}
+  <div class="holdings-table">
+    <h3 class="holdings-table-label">Within</h3>
+    {{ partial "holdings/kind-groups.html" . }}
+  </div>
+  {{- end }}
+  {{- with $heldBy }}
+  <div class="holdings-table">
+    <h3 class="holdings-table-label">Held by</h3>
+    <ul class="holdings-table-grid">
+      {{- range . }}
+      <li>
+        {{- partial "holdings/entry.html" (dict "entry" . "class" "holdings-entry-name") -}}
+        {{- with .subType }}<span class="holdings-entry-kind"> ({{ humanize . }})</span>{{ end -}}
+      </li>
+      {{- end }}
+    </ul>
+  </div>
+  {{- end }}
+  {{- with $holds }}
+  <div class="holdings-table">
+    <h3 class="holdings-table-label">Holdings</h3>
+    {{ partial "holdings/kind-groups.html" . }}
+  </div>
+  {{- end }}
+</section>
+{{- end -}}

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

@@ -0,0 +1,15 @@
+{{- /*
+  One entry of a `runin` group or a `list` section.
+
+  An entry is `{text, url}`. It links when the build reached the page it
+  names, and keeps its words when it did not — a panel naming something this
+  site does not publish is better than a panel silently one entry short.
+
+  Takes `entry` and the `class` its medium gives it.
+*/ -}}
+{{- $entry := .entry -}}
+{{- with $entry.url -}}
+<a class="{{ $.class }}" href="{{ . }}">{{ $entry.text }}</a>
+{{- else -}}
+<span class="{{ $.class }}">{{ $entry.text }}</span>
+{{- end -}}

package/hugo-theme/layouts/partials/infobox/items.html

@@ -0,0 +1,26 @@
+{{- /*
+  What one infobox section holds, whatever its layout.
+
+  A section carries its content under the key its layout names — `rows`,
+  `cells`, `groups` or `entries` — so one lookup answers "is there anything to
+  draw?" for every layout there is. Returns a slice, empty when there is
+  nothing.
+
+  Takes the section. Returns the items.
+
+  An unrecognised layout returns nothing and says so once: the four layouts
+  are a closed set, so a fifth means this theme is older than the content it
+  is drawing, and a silently dropped section is the expensive way to find out.
+*/ -}}
+{{- $section := . -}}
+{{- $layout := $section.layout | default "" -}}
+{{- $key := index (dict "rows" "rows" "grid" "cells" "runin" "groups" "list" "entries") $layout -}}
+{{- $items := slice -}}
+{{- with $key -}}
+  {{- with index $section . -}}
+    {{- $items = . -}}
+  {{- end -}}
+{{- else -}}
+  {{- warnidf "infobox-unknown-layout" "infobox: section layout %q is not one of rows, grid, runin or list, so the section is not drawn. Upgrade @heroiclands/hugo-theme to a version that draws it." $layout -}}
+{{- end -}}
+{{- return $items -}}

package/hugo-theme/layouts/partials/infobox/section.html

@@ -0,0 +1,56 @@
+{{- /*
+  One infobox section, arranged the way its `layout` says.
+
+  Four layouts, a closed set, and the key a section carries its content under
+  is what names it:
+
+    rows   — label/value pairs, one per line          `rows`
+    grid   — short label/value cells packed together  `cells`
+    runin  — groups of comma-joined entries           `groups`
+    list   — one entry per line                       `entries`
+
+  Takes the section.
+
+  **A value of `0` is a value.** Armour that stops nothing edged is a fact
+  about the armour, so a cell is printed as it comes rather than guarded with
+  `with`, which would drop a zero along with an absence.
+*/ -}}
+{{- $section := . -}}
+{{- $layout := $section.layout | default "" -}}
+{{- if eq $layout "rows" -}}
+<dl class="info-profile-grid">
+  {{- range $section.rows }}
+  <dt>{{ .label }}</dt>
+  <dd>{{ partial "infobox/value.html" . }}</dd>
+  {{- end }}
+</dl>
+{{- else if eq $layout "grid" -}}
+<div class="info-attrs-grid">
+  {{- range $section.cells }}
+  <div class="info-attr">
+    <span class="attr-label">{{ .label }}</span>
+    <span class="attr-value">{{ .value }}</span>
+  </div>
+  {{- end }}
+</div>
+{{- else if eq $layout "runin" -}}
+  {{- range $section.groups }}
+  <p class="info-skill-line">
+    {{- with .label }}<span class="skill-cat">{{ . }}:</span>{{ end }}
+    <span class="skill-entries">
+      {{- range $i, $entry := .entries -}}
+        {{- if $i }}, {{ end -}}
+        {{- partial "infobox/entry.html" (dict "entry" $entry "class" "skill-entry") -}}
+      {{- end -}}
+    </span>
+  </p>
+  {{- end }}
+{{- else if eq $layout "list" -}}
+<ul class="info-mystical-list">
+  {{- range $section.entries }}
+  <li class="info-mystical-item">
+    {{- partial "infobox/entry.html" (dict "entry" . "class" "mystical-name") -}}
+  </li>
+  {{- end }}
+</ul>
+{{- end -}}

package/hugo-theme/layouts/partials/infobox/value.html

@@ -0,0 +1,43 @@
+{{- /*
+  One row's value, drawn by its `kind`.
+
+  Five kinds, a closed set:
+
+    text   — a string
+    number — a number
+    link   — `{text, url}`
+    links  — a list of those, comma-joined
+    list   — a list of strings, comma-joined
+
+  Takes the row.
+
+  **A value of `0` is a value**, so a number is printed as it comes rather
+  than guarded with `with`, which would drop a zero along with an absence.
+  Anything the build did not classify is set as text, which is what an
+  unlabelled scalar is.
+*/ -}}
+{{- $kind := .kind | default "text" -}}
+{{- if eq $kind "link" -}}
+  {{- partial "infobox/entry.html" (dict "entry" .value "class" "info-link") -}}
+{{- else if eq $kind "links" -}}
+  {{- range $i, $entry := .value -}}
+    {{- if $i }}, {{ end -}}
+    {{- partial "infobox/entry.html" (dict "entry" $entry "class" "info-link") -}}
+  {{- end -}}
+{{- else if eq $kind "list" -}}
+  {{- delimit .value ", " -}}
+{{- else if eq $kind "number" -}}
+  {{- /* A whole number is grouped, so a population reads as 500,000 rather
+         than as a run of digits a reader has to count. Grouping is
+         typography and belongs to the medium; the number itself is the
+         build's. Anything that is not a plain integer — a measurement, or a
+         value the build did not classify — is set as written. */ -}}
+  {{- $digits := printf "%v" .value -}}
+  {{- if findRE `^-?[0-9]+$` $digits -}}
+    {{- lang.FormatNumberCustom 0 (int $digits) -}}
+  {{- else -}}
+    {{- .value -}}
+  {{- end -}}
+{{- else -}}
+  {{- .value -}}
+{{- end -}}

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

@@ -0,0 +1,57 @@
+{{- /*
+  The infobox rail — every box a page declares, drawn in the order declared.
+
+  **The content is not decided here.** A page's `infoboxes:` front matter
+  carries an ordered list of boxes, each holding ordered sections, each holding
+  ordered rows, cells, groups or entries, already labelled. This partial and
+  the three under `infobox/` switch on a section's `layout` and a value's
+  `kind` and on nothing else — never on a note type, never on a field name.
+  That is what lets a field added to a type appear here with no edit.
+
+  A box is a `<details>` disclosure, open by default: native, accessible, and
+  no JavaScript. It is what lets several boxes stack for nothing — a note box
+  and one box per system are three summary lines when closed, rather than
+  three panels burying the prose.
+
+  Two kinds of box, and they answer emptiness differently:
+
+  - A **note box** with no section holding anything is not drawn. A heading
+    over nothing asserts a fact that is not there.
+  - A **system box** carries a `statement` where it has nothing to show, and
+    the statement is drawn in place of the sections. Which silence this is —
+    the system compiled no document, or it compiled one holding nothing the
+    profile has not already said — is decided by the build, because a reader
+    meeting one page cannot tell the two apart and neither can a template. A
+    system that does not map the note's type at all sends no box, and nothing
+    is drawn.
+
+  Returns an empty string when the page declares no box, so a caller can test
+  what comes back rather than reaching into the data itself.
+*/ -}}
+{{- range .Params.infoboxes -}}
+  {{- $box := . -}}
+  {{- $sections := slice -}}
+  {{- range $box.sections -}}
+    {{- if gt (len (partial "infobox/items.html" .)) 0 -}}
+      {{- $sections = $sections | append . -}}
+    {{- end -}}
+  {{- end -}}
+  {{- $system := eq ($box.kind | default "") "system" -}}
+  {{- if or $system (gt (len $sections) 0) }}
+<details class="info-sidebar info-box{{ with $box.id }} info-box-{{ . }}{{ end }}" open data-pagefind-ignore>
+  <summary class="info-sidebar-title"><h2>{{ $box.title }}</h2></summary>
+  {{- with $box.statement }}
+  <p class="info-statement">{{ . }}</p>
+  {{- else }}
+    {{- range $sections }}
+  <section class="info-section{{ with .id }} info-section-{{ . }}{{ end }}">
+    {{- with .label }}
+    <h3 class="info-section-title">{{ . }}</h3>
+    {{- end }}
+    {{ partial "infobox/section.html" . }}
+  </section>
+    {{- end }}
+  {{- end }}
+</details>
+  {{- end -}}
+{{- end -}}

package/hugo-theme/layouts/partials/page-body.html

@@ -0,0 +1,154 @@
+{{- /*
+  A note's body — the infobox rail, the content, and prev/next through its
+  catalog. Shared by `_default/single.html`, for a page, and `index.html`,
+  for the homepage note rendered as a page: the two are the same family, and
+  this is the shape they share. The caller renders the hero; this partial
+  starts at the article.
+
+  Context: the page.
+*/ -}}
+{{- /* The boxes a page declares, drawn by one generic renderer. What each box
+       holds is decided by the build and carried in `infoboxes:` front matter;
+       this file decides only where the rail goes. A page declaring none gets
+       back an empty string and no rail. */ -}}
+{{- $infobox := partial "infobox.html" . -}}
+{{- $hasSidebar := ne (trim $infobox " \r\n\t") "" -}}
+
+{{- /* The TOC partial only emits markup when the page has more than
+       3 H2 headings. To avoid laying the page out as a two-column
+       grid for nothing, detect the same condition here so we can
+       apply the `.single-with-toc` class conditionally. A page that
+       already has a rail gets its contents list at the foot of that
+       rail rather than a second column. */ -}}
+{{- $h2Count := len (findRE `(?m)^##\s+\S` (.RawContent | default "")) -}}
+{{- $hasToc := gt $h2Count 3 -}}
+
+{{- /* A draft page states it, which also decides the article's first grid
+       row — see the notice partial and `.single-with-notice`. */ -}}
+{{- $isDraft := partial "draft-state.html" . -}}
+
+<article class="single{{ if $hasSidebar }} single-with-sidebar{{ else if $hasToc }} single-with-toc{{ end }}{{ if $isDraft }} single-with-notice{{ end }}">
+  {{- /* A statement about the page rather than about its subject, so it leads
+         the article: above the rail and above the prose, at every width. It
+         spans the grid for that reason — inside `.single-content` it would sit
+         beside the boxes on a wide screen and below them on a narrow one,
+         where the rail comes first. */ -}}
+  {{ partial "draft-notice.html" . }}
+  {{- /* Filter values a search can narrow on, invisible and excluded from
+         indexing themselves — `data-pagefind-filter` is read wherever it
+         sits, `data-pagefind-body`/`data-pagefind-ignore` scoping included
+         (see the README's "Search" section). */ -}}
+  {{- with .Params.type }}<span data-pagefind-filter="type" hidden>{{ . }}</span>{{ end -}}
+  {{- with .Params.package }}<span data-pagefind-filter="package" hidden>{{ . }}</span>{{ end -}}
+  {{- if $hasSidebar }}
+  {{- /* The rail comes first in document order, because the infobox is
+         generated content prepended before the prose: on a narrow screen the
+         grid collapses and the boxes land where they were written, above the
+         text they summarise. */ -}}
+  <aside class="info-rail">
+    {{ $infobox }}
+    {{ if $hasToc }}{{ partial "toc.html" . }}{{ end }}
+  </aside>
+  {{- end }}
+  <div class="single-content">
+    {{- $tagChips := partial "tags.html" . -}}
+    {{- $beingSubtype := "" -}}
+    {{- if and (eq .Params.type "being") .Params.subType -}}
+      {{- $beingSubtype = cond (eq .Params.subType "npc") "NPC" (humanize .Params.subType) -}}
+    {{- end -}}
+    {{ if or .Params.date (ne (trim $tagChips " \r\n\t") "") $beingSubtype }}
+    <div class="single-meta">
+      {{ if .Params.date }}
+      <time class="single-date" datetime="{{ .Date.Format "2006-01-02" }}">{{ .Date.Format "January 2, 2006" }}</time>
+      {{ end }}
+      {{- with $beingSubtype }}<span class="single-subtype">{{ . }}</span>{{ end }}
+      {{ $tagChips }}
+    </div>
+    {{ end }}
+
+    <div class="single-body" data-pagefind-body>
+      {{ .Content }}
+    </div>
+
+    {{ partial "holdings.html" . }}
+    {{ partial "place-map.html" . }}
+    {{ partial "related.html" . }}
+
+    {{- /*
+      Prev/next walk the page's own catalog, not its Hugo section (issue #48).
+      `.PrevInSection` / `.NextInSection` mean "the neighbouring page in this
+      directory", which was the same thing only while a page lived in a
+      directory named for its catalog. `@heroiclands/package-build`
+      (package-build#204) emits every content page flat under the content
+      mount, so a consumer's whole catalog is one section and these two links
+      would walk every page of every type — reading through the afflictions
+      silently left them.
+
+      So where a section holds more than one catalog, the sibling set is
+      narrowed to the pages sharing this page's catalog key. A section holding
+      a single catalog is left alone, because `.PrevInSection` already walks
+      exactly that catalog there — which is what makes this a no-op for a site
+      whose pages still sit in catalog-named directories. A page declaring no
+      catalog keeps the section-scoped result. The home page declares no
+      catalog and has no section siblings either way.
+
+      The catalog key: `type` for structured content, whose type *is* its
+      catalog (`affliction`, `skill`, `weapongear`, …); for `type: doc`, which
+      is prose rather than a catalog of its own, `subType` (what package-build
+      compiles from a note's classification) or, failing that, `category`
+      (what a documentation tree mounted from a repository directory
+      carries); "" for a page with no `type`, which has no catalog.
+
+      Ordering follows Hugo's: in a page collection `.PrevInSection` is the
+      *following* entry and `.NextInSection` the preceding one, so the
+      neighbours are taken at index+1 and index-1 respectively.
+    */ -}}
+    {{- $prev := .PrevInSection -}}
+    {{- $next := .NextInSection -}}
+    {{- $type := .Params.type | default "" -}}
+    {{- $key := $type -}}
+    {{- if eq $type "doc" -}}
+      {{- $key = .Params.subType | default (.Params.category | default "") -}}
+    {{- end -}}
+    {{- $siblings := slice -}}
+    {{- with .CurrentSection -}}
+      {{- if $key -}}
+        {{- $mixed := false -}}
+        {{- $matching := slice -}}
+        {{- range .RegularPages -}}
+          {{- $pageType := .Params.type | default "" -}}
+          {{- $pageKey := $pageType -}}
+          {{- if eq $pageType "doc" -}}
+            {{- $pageKey = .Params.subType | default (.Params.category | default "") -}}
+          {{- end -}}
+          {{- if eq $pageKey $key -}}
+            {{- $matching = $matching | append . -}}
+          {{- else if ne $pageKey "" -}}
+            {{- $mixed = true -}}
+          {{- end -}}
+        {{- end -}}
+        {{- if $mixed -}}{{- $siblings = $matching -}}{{- end -}}
+      {{- end -}}
+    {{- end -}}
+    {{- if $siblings -}}
+      {{- $index := -1 -}}
+      {{- range $i, $p := $siblings -}}
+        {{- if eq $p.Path $.Path -}}{{- $index = $i -}}{{- end -}}
+      {{- end -}}
+      {{- if ge $index 0 -}}
+        {{- $prev = "" -}}
+        {{- $next = "" -}}
+        {{- if lt (add $index 1) (len $siblings) -}}{{- $prev = index $siblings (add $index 1) -}}{{- end -}}
+        {{- if gt $index 0 -}}{{- $next = index $siblings (sub $index 1) -}}{{- end -}}
+      {{- end -}}
+    {{- end -}}
+    <nav class="single-nav">
+      {{ with $prev }}<a href="{{ .Permalink }}" class="nav-prev">&larr; {{ .Title }}</a>{{ end }}
+      {{ with $next }}<a href="{{ .Permalink }}" class="nav-next">{{ .Title }} &rarr;</a>{{ end }}
+    </nav>
+  </div>
+
+  {{ if and (not $hasSidebar) $hasToc }}
+    {{ partial "toc.html" . }}
+  {{ end }}
+</article>

package/hugo-theme/layouts/partials/place-map.html

@@ -0,0 +1,9 @@
+{{- /* A page bundle's generated itinerary. The SVG carries its own place links. */ -}}
+{{- with .Params.map -}}
+  {{- with $.Resources.GetMatch . -}}
+    <section class="place-map" aria-labelledby="place-map-heading" data-pagefind-ignore>
+      <h2 id="place-map-heading" class="place-map-heading">From here</h2>
+      <div class="place-map-drawing">{{ .Content | safeHTML }}</div>
+    </section>
+  {{- end -}}
+{{- end -}}

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

@@ -0,0 +1,121 @@
+{{- /*
+  Related partial.
+
+  Renders a compact "Related" block at the bottom of a single page from the
+  page's `related` front matter, if it carries any.
+
+  Structure in front matter:
+    related:
+      backlinks: [{ title, url, type }, ...]   # pages that link here
+      mentions:  [{ title, url, type }, ...]   # pages this page links to
+
+  Rendering strategy:
+    - Merge both directions into a single deduped pool (direction
+      doesn't matter to a reader — a connection is a connection).
+    - Group by the referenced page's `type`.
+    - Emit one labelled group per type, its entries laid out as a
+      CSS grid (`repeat(auto-fill, minmax(14em, 1fr))`) so a wide
+      screen shows two or three columns and a narrow one falls back
+      to a single column with no media query.
+    - The whole block is wrapped in a bordered, tinted card so it
+      visually sets off the end of the article.
+
+  Silent disappear: a page with no `related`, or whose two lists are both
+  empty, emits nothing at all rather than an empty heading. The rows are
+  computed first and the <section> is rendered only when there is something
+  to put in it.
+
+  `return` cannot be used to bail out early here. It sets the partial's
+  return value; it does not discard template text the partial has already
+  emitted, so a guard written that way still prints the empty shell. Hence
+  the emptiness test wraps the markup instead of preceding it.
+*/ -}}
+
+{{- /* `default dict` keeps the lookups below safe on a page with no
+       `related` at all, so the whole computation stays flat. */ -}}
+{{- $rel := .Params.related | default dict -}}
+{{- $backlinks := or $rel.backlinks slice -}}
+{{- $mentions  := or $rel.mentions  slice -}}
+
+{{- /* Merge both directions, deduped by URL. `union` can't hash
+       slices of maps, so we walk the two lists in order and dedupe
+       by URL manually. Mentions come first so explicit author
+       choices win when a page appears in both directions. */ -}}
+{{- $seen := slice -}}
+{{- $merged := slice -}}
+{{- range $mentions -}}
+  {{- if not (in $seen .url) -}}
+    {{- $seen = $seen | append .url -}}
+    {{- $merged = $merged | append . -}}
+  {{- end -}}
+{{- end -}}
+{{- range $backlinks -}}
+  {{- if not (in $seen .url) -}}
+    {{- $seen = $seen | append .url -}}
+    {{- $merged = $merged | append . -}}
+  {{- end -}}
+{{- end -}}
+
+{{- /* Plural, human-readable label for each type. Falls back to
+       `humanize` for any type not listed here. */ -}}
+{{- $labels := dict
+  "affiliation"  "Affiliations"
+  "being"        "Beings"
+  "blog-post"    "Posts"
+  "character"    "People"
+  "continent"    "Continents"
+  "creature"     "Creatures"
+  "faith"        "Faiths"
+  "language"     "Languages"
+  "lore"         "Lore"
+  "organization" "Organizations"
+  "page"         "Pages"
+  "pantheon"     "Pantheons"
+  "people"       "Peoples"
+  "polity"       "Polities"
+  "project-page" "Projects"
+  "region"       "Regions"
+  "religion"     "Religions"
+  "settlement"   "Settlements"
+  "site"         "Places"
+  "world"        "Worlds"
+-}}
+
+{{- /* Group refs by type, preserving alphabetical order within a
+       group (the input lists arrive already sorted). */ -}}
+{{- $groups := dict -}}
+{{- range $merged -}}
+  {{- $t := .type | default "page" -}}
+  {{- $existing := index $groups $t | default slice -}}
+  {{- $groups = merge $groups (dict $t ($existing | append .)) -}}
+{{- end -}}
+
+{{- /* Sort the group keys alphabetically by their rendered label
+       so the list reads A → Z regardless of insertion order. */ -}}
+{{- $rows := slice -}}
+{{- range $type, $refs := $groups -}}
+  {{- $label := index $labels $type | default (humanize $type) -}}
+  {{- $rows = $rows | append (dict "label" $label "type" $type "refs" $refs) -}}
+{{- end -}}
+{{- if $rows -}}
+  {{- $rows = sort $rows "label" "asc" -}}
+{{- end -}}
+
+{{- /* Deliberately not indented under the `if`: keeping the markup at
+       column 0 leaves the emitted HTML byte-identical to what pages with
+       `related` rendered before the guard was added. */ -}}
+{{- if $rows -}}
+<section class="related" aria-labelledby="related-heading" data-pagefind-ignore>
+  <h2 id="related-heading" class="related-heading">Related</h2>
+  {{- range $rows }}
+  <div class="related-group">
+    <h3 class="related-group-label">{{ .label }}</h3>
+    <ul class="related-group-grid">
+      {{- range .refs }}
+      <li><a href="{{ .url }}">{{ .title }}</a></li>
+      {{- end }}
+    </ul>
+  </div>
+  {{- end }}
+</section>
+{{ end -}}

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

@@ -0,0 +1,84 @@
+{{- /*
+  The header search box, rendered only when a consumer sets `params.search`
+  (silent-disappear otherwise — see the README's "Search" section).
+
+  `@heroiclands/package-build`'s `package-build site-root` step writes a
+  Pagefind index beside the rendered pages, at `pagefind/` under the site's
+  own base URL, when a consumer leaves `site.search` at its default of `true`
+  (see that package's `docs/configuration.md`, `site.search`). Pagefind's own
+  UI — `pagefind-ui.js` and `pagefind-ui.css` — ships inside that generated
+  directory, so nothing here is bundled or pinned to a Pagefind version; the
+  index and the UI that reads it travel together.
+
+  Both files are referenced the same way every other theme-bundled asset is
+  — `relURL`, exactly as `"css/style.css" | relURL` resolves in
+  `baseof.html` — so a package served under a prefix (`/thalorna/`) finds
+  its own index rather than another package's.
+
+  A `/search/` results page would need a consumer content file at that
+  address, and a site is its homepage and its pages with nothing generated
+  between them (package-build's `docs/configuration.md`, "A site is its
+  homepage and its pages") — so a dedicated results page is not this
+  theme's to invent. Pagefind's own panel UI needs no page of its own, so
+  the header box opens that instead.
+
+  Context: the page (only .Site is read, so this partial can also be called
+  with just `.Site` in a dict).
+*/ -}}
+{{- if .Site.Params.search }}
+<div class="site-search" data-pagefind-ignore>
+  <button
+    type="button"
+    class="search-toggle"
+    aria-label="Search"
+    aria-expanded="false"
+    aria-controls="site-search-panel"
+  ><i class="fa-solid fa-magnifying-glass" aria-hidden="true"></i></button>
+  <div id="site-search-panel" class="search-panel" hidden>
+    <div class="search-panel-inner" id="search"></div>
+  </div>
+</div>
+<link rel="stylesheet" href="{{ "pagefind/pagefind-ui.css" | relURL }}">
+<script src="{{ "pagefind/pagefind-ui.js" | relURL }}" defer></script>
+<script>
+(function () {
+  var toggle = document.querySelector(".search-toggle");
+  var panel = document.getElementById("site-search-panel");
+  if (!toggle || !panel) return;
+  var ui = null;
+
+  function open() {
+    panel.hidden = false;
+    toggle.setAttribute("aria-expanded", "true");
+    if (!ui && typeof PagefindUI !== "undefined") {
+      ui = new PagefindUI({
+        element: "#search",
+        showSubResults: true,
+        showImages: false
+      });
+    }
+    var input = panel.querySelector("input");
+    if (input) input.focus();
+  }
+
+  function close() {
+    panel.hidden = true;
+    toggle.setAttribute("aria-expanded", "false");
+  }
+
+  toggle.addEventListener("click", function () {
+    if (panel.hidden) { open(); } else { close(); }
+  });
+
+  document.addEventListener("keydown", function (e) {
+    if (e.key === "Escape" && !panel.hidden) close();
+  });
+
+  document.addEventListener("click", function (e) {
+    if (panel.hidden) return;
+    if (panel.contains(e.target) || toggle.contains(e.target)) return;
+    close();
+  });
+})();
+</script>
+{{- end }}

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

@@ -0,0 +1,32 @@
+{{- /*
+  Resolve a consumer-supplied link against the site it is rendered on.
+
+  The theme carries layout, not addresses, so every URL it renders comes from
+  a consuming site's configuration or front matter — and a package published
+  under a path prefix (`/sohl/`, `/thalorna/`) needs its own links to carry
+  that prefix without writing it down anywhere.
+
+  Resolution:
+    1. An already-absolute URL (http://, https://, //) is returned as-is, so a
+       consumer can point at another host.
+    2. A page fragment or query alone (#anchor, ?q=) is returned as-is.
+    3. Anything else is treated as a path within this site and resolved with
+       `relURL`. A leading slash is trimmed first: `relURL` reads a leading
+       slash as "from the origin" and leaves the base path off, so trimming it
+       means a consumer writing the obvious "/section/" still gets a link
+       inside its own site when that site is served under a prefix.
+
+  Usage:
+    {{ partial "site-url.html" (dict "site" .Site "url" "kb/rules/") }}
+
+  Params:
+    site — the site context (.Site). Accepted for symmetry with cdn-url.html
+           and so this partial can never be tempted to read a page.
+    url  — the address to resolve. An empty value resolves to the site root.
+*/ -}}
+{{- $url := .url | default "" -}}
+{{- $resolved := $url -}}
+{{- if not (or (hasPrefix $url "http://") (hasPrefix $url "https://") (hasPrefix $url "//") (hasPrefix $url "#") (hasPrefix $url "?")) -}}
+  {{- $resolved = strings.TrimPrefix "/" $url | relURL -}}
+{{- end -}}
+{{- return $resolved -}}