@heroiclands/package-build 22.23.0 → 22.25.0

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

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

@@ -0,0 +1,30 @@
+{{- /*
+  A page's own subject-tag chips, rendered from .Params.tags.
+
+  `draft` is suppressed here: it is a presentation fact about the writing,
+  not a fact about the subject (package-build/engine/note-vocabulary.mjs,
+  `DRAFT_TAG`) — a draft compiles, validates, publishes and resolves like any
+  other note. It does not belong beside subject tags in a reader-facing tag
+  list; `draft-notice.html` is where the state is stated,
+  and `draft-state.html` is the one place either partial spells the tag.
+
+  The taxonomy itself is untouched: a draft page still carries the tag, still
+  lists on its term page, and the term still appears in a site-wide taxonomy
+  listing. This partial decides only what a page's own chip row shows.
+
+  Silent-disappear: a page whose only tag is `draft` emits nothing here, the
+  same as a page with no tags at all.
+
+  Context: the page.
+*/ -}}
+{{- $tags := slice -}}
+{{- range .Params.tags -}}
+  {{- if ne (lower .) "draft" -}}
+    {{- $tags = $tags | append . -}}
+  {{- end -}}
+{{- end -}}
+{{- with $tags }}
+<div class="single-tags">
+  {{ range . }}<a href="{{ printf "tags/%s/" (. | urlize) | relURL }}" class="tag">{{ . }}</a>{{ end }}
+</div>
+{{ end -}}

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

@@ -0,0 +1,28 @@
+{{- /*
+  Table of Contents partial.
+
+  Renders a sticky right-rail TOC on pages that have more than 3 H2
+  headings. We detect the threshold by grepping the raw content source
+  (`.RawContent`) for lines starting with "## " — this is faster and
+  more reliable than parsing the rendered HTML, and catches authored
+  headings regardless of markdown extensions that Hugo might apply.
+
+  The caller is responsible for:
+    - wrapping the page in a CSS grid when this partial renders
+      (see `.single.single-with-toc` in style.css)
+    - gating invocation with `partialCached` if desired
+
+  This partial prints nothing when the H2 count is 3 or less, so it's
+  safe to include unconditionally.
+*/ -}}
+
+{{- $raw := .RawContent | default "" -}}
+{{- $h2Count := len (findRE `(?m)^##\s+\S` $raw) -}}
+{{- if gt $h2Count 3 -}}
+<aside class="toc" aria-label="Table of contents" data-pagefind-ignore>
+  <div class="toc-inner">
+    <p class="toc-label">On this page</p>
+    {{ .TableOfContents }}
+  </div>
+</aside>
+{{- end -}}

package/hugo-theme/layouts/partials/warn-missing-banner.html

@@ -0,0 +1,3 @@
+{{- warnidf (printf "hero-banner-missing-%s" .name)
+    "hero-banner: no banner named %q in the shared artwork set; falling back to %s/%s. Draw it and add %q to data/banners.yaml, or name a hero image on the page — `data.banner` on a note, `banner:` on a hand-authored page. A blank `data.banner`, or `banner: none`, declines a hero image. First seen on %s."
+    .name .dir .fallback .name .context -}}

package/hugo-theme/layouts/shortcodes/cartouche.html

@@ -0,0 +1,64 @@
+{{- /*
+  Cartouche shortcode — renders a named cartouche SVG as an ornamental
+  accent on culture-flavored pages. The canonical use is Kheperi
+  cartouches on Ta'Kheperu and Kemetian-pantheon pages, but the same
+  pipeline works for any "named seal" SVG.
+
+  Usage (shown with plain angle brackets so the Go template parser
+  doesn't try to close this comment). Hugo forbids MIXING positional
+  and named parameters in one call, so pick a form per call:
+
+    { {< cartouche "takheperu" >} }                               positional
+    { {< cartouche slug="takheperu" >} }                          named, centered
+    { {< cartouche slug="takheperu" align="right" >} }            floated right
+    { {< cartouche slug="ra" size="inline" >} }                   inline
+    { {< cartouche slug="anubis" caption="Anpu" >} }              figure + caption
+
+  Parameters (all optional except slug):
+    slug    - The cartouche SVG basename. May also be passed positionally
+              (as the first positional argument) when no other params
+              are needed — Hugo disallows mixing the two styles.
+    size    - "inline" to flow with text. Otherwise block-level.
+    align   - "left" or "right" to float so prose wraps. Default centered.
+    height  - CSS length override for the cartouche's height, e.g.
+              "10rem" or "160px". Default comes from .cartouche CSS
+              (13rem block, 9rem floated). Width scales from aspect ratio.
+    alt     - Override screen-reader text. Defaults to humanized slug.
+    caption - Optional figcaption (block mode only).
+
+  SVG is expected at /static/img/cartouches/<slug>.svg. Design note:
+  cartouche SVGs should draw with stroke="currentColor" and fill="none"
+  (or a hard-coded brand color) so they tint cleanly against any
+  background.
+*/ -}}
+{{- /* Accept slug as either the first positional arg or the named
+       "slug" parameter, so a caller can pick the style that fits the
+       rest of their arguments. */ -}}
+{{- $slug := .Get "slug" -}}
+{{- if not $slug }}{{ $slug = .Get 0 }}{{ end -}}
+{{- if not $slug -}}
+  {{- errorf "cartouche shortcode at %s needs a slug (positional arg 0 or slug=\"…\")" .Position -}}
+{{- end -}}
+{{- $altDefault := humanize (replace $slug "-" " ") | title -}}
+{{- $alt    := .Get "alt"     | default $altDefault -}}
+{{- $size   := .Get "size"    | default "" -}}
+{{- $align  := .Get "align"   | default "" -}}
+{{- $cap    := .Get "caption" | default "" -}}
+{{- $height := .Get "height"  | default "" -}}
+{{- $src    := printf "img/cartouches/%s.svg" $slug | relURL -}}
+{{- $classes := slice "cartouche" -}}
+{{- with $size  }}{{ $classes = $classes | append (printf "cartouche-%s" .) }}{{ end -}}
+{{- with $align }}{{ $classes = $classes | append (printf "cartouche-%s" .) }}{{ end -}}
+{{- $class := delimit $classes " " -}}
+{{- /* When `height` is given, apply it as an inline style directly on
+       the <img>. Inline styles on the target element are unambiguous —
+       they trump any .cartouche img CSS rule on specificity and don't
+       depend on custom-property inheritance. */ -}}
+{{- if eq $size "inline" -}}
+<span class="{{ $class }}"><img src="{{ $src }}" alt="{{ $alt }}" loading="lazy"{{ with $height }} style="height: {{ . }}; width: auto; max-width: none;"{{ end }} /></span>
+{{- else -}}
+<figure class="{{ $class }}">
+  <img src="{{ $src }}" alt="{{ $alt }}" loading="lazy"{{ with $height }} style="height: {{ . }}; width: auto; max-width: none;"{{ end }} />
+  {{- with $cap }}<figcaption>{{ . }}</figcaption>{{ end }}
+</figure>
+{{- end -}}

package/hugo-theme/layouts/shortcodes/exturl.html

@@ -0,0 +1,12 @@
+<span class="exturl">
+  <code class="exturl-text">{{ .Get 0 }}</code>
+  <button class="exturl-copy" onclick="navigator.clipboard.writeText('{{ .Get 0 }}').then(()=>{const b=this;b.classList.add('copied');setTimeout(()=>b.classList.remove('copied'),1500)})" title="Copy URL to clipboard" aria-label="Copy URL to clipboard">
+    <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>
+  </button>
+</span>

package/hugo-theme/layouts/shortcodes/glyph.html

@@ -0,0 +1,43 @@
+{{- /*
+  Glyph shortcode — renders a hieroglyphic deity-name cluster (or any
+  "icon-scale" SVG) from the project CDN. Parallel to cartouche.html
+  but for smaller, non-royal glyph groups: Kemetían deity names,
+  category icons, ornamental marks, etc.
+
+  Usage (Hugo disallows mixing positional and named params in one
+  call; pick a form per call):
+
+    { {< glyph "anubis" >} }                             inline, plain
+    { {< glyph slug="anubis" >} }                        same, named form
+    { {< glyph slug="anubis" frame="tablet" >} }         inside stone tablet
+    { {< glyph slug="ra" size="inline" >} }              scales with text
+    { {< glyph slug="ra" size="block" >} }               centered block
+    { {< glyph slug="ra" alt="Sun god Ra" >} }           override alt text
+
+  Parameters (all optional except slug):
+    slug    - Filename (without .svg). Passed positionally or as slug=.
+    frame   - "tablet" wraps in a limestone rectangular frame (good for
+              catalog layouts like the pantheon table where visual
+              parallelism across rows matters more than intrinsic width).
+    size    - "inline" (small, flows with text), "block" (centered
+              standalone). Default sits at 1.8em height.
+    alt     - Screen-reader text. Defaults to humanized slug.
+
+  SVG source: icons/<slug>.svg, resolved against the consuming site's
+  `params.cdnBaseURL` — the theme names no host of its own.
+*/ -}}
+{{- $slug := .Get "slug" -}}
+{{- if not $slug }}{{ $slug = .Get 0 }}{{ end -}}
+{{- if not $slug -}}
+  {{- errorf "glyph shortcode at %s needs a slug (positional arg 0 or slug=\"…\")" .Position -}}
+{{- end -}}
+{{- $altDefault := humanize (replace $slug "-" " ") | title -}}
+{{- $alt   := .Get "alt"   | default $altDefault -}}
+{{- $frame := .Get "frame" | default "" -}}
+{{- $size  := .Get "size"  | default "" -}}
+{{- $src   := partial "cdn-url.html" (dict "site" .Site "path" (printf "icons/%s.svg" $slug)) -}}
+{{- $classes := slice "glyph" -}}
+{{- with $frame }}{{ $classes = $classes | append (printf "glyph-%s" .) }}{{ end -}}
+{{- with $size  }}{{ $classes = $classes | append (printf "glyph-%s" .) }}{{ end -}}
+{{- $class := delimit $classes " " -}}
+<span class="{{ $class }}"><img src="{{ $src }}" alt="{{ $alt }}" loading="lazy" /></span>

package/hugo-theme/layouts/shortcodes/pagelist.html

@@ -0,0 +1,63 @@
+{{- /*
+  pagelist — the pages carrying a tag, as a plain list.
+
+  Curated landings are the right front door, but hand-enumerated link lists
+  drift: a page gets added and nobody updates the index. This expresses a group
+  by INTENT instead. Tag a page and it files itself; untag it and it leaves.
+
+  Usage:
+
+    { {< pagelist tag="key-concept" >} }                  every tagged page
+    { {< pagelist tag="key-concept" section="rules" >} }  restricted to a section
+    { {< pagelist tag="key-concept" sort="weight" >} }    title (default) | weight | date
+    { {< pagelist tag="key-concept" desc="true" >} }      include page descriptions
+
+  Parameters:
+    tag      - (required) taxonomy term. Matched case-insensitively.
+    section  - (optional) restrict to one top-level section, e.g. "rules".
+    sort     - (optional) "title" (default), "weight", or "date" (newest first).
+    desc     - (optional) "true" to show each page's description beneath it.
+
+  An unknown or empty tag warns at build time rather than rendering nothing
+  silently — a typo in a tag is exactly the drift this is meant to prevent.
+*/ -}}
+{{- $tag := .Get "tag" -}}
+{{- if not $tag }}{{ $tag = .Get 0 }}{{ end -}}
+{{- if not $tag -}}
+  {{- errorf "pagelist shortcode at %s needs a tag (tag=\"…\" or positional arg 0)" .Position -}}
+{{- end -}}
+
+{{- $term := $tag | urlize -}}
+{{- $pages := slice -}}
+{{- with index .Site.Taxonomies.tags $term -}}
+  {{- $pages = .Pages -}}
+{{- end -}}
+
+{{- with $.Get "section" -}}
+  {{- $sec := . -}}
+  {{- $pages = where $pages "Section" $sec -}}
+{{- end -}}
+
+{{- $sort := $.Get "sort" | default "title" -}}
+{{- if eq $sort "weight" -}}
+  {{- $pages = sort $pages "Weight" -}}
+{{- else if eq $sort "date" -}}
+  {{- $pages = sort $pages "Date" "desc" -}}
+{{- else -}}
+  {{- $pages = sort $pages "Title" -}}
+{{- end -}}
+
+{{- if not $pages -}}
+  {{- warnf "pagelist at %s: no pages carry the tag %q — check the spelling, or tag some pages." $.Position $tag -}}
+{{- else -}}
+<ul class="page-list pagelist">
+  {{- range $pages }}
+  <li class="page-list-item">
+    <a class="page-list-title" href="{{ .RelPermalink }}">{{ .Title }}</a>
+    {{- if and (eq ($.Get "desc") "true") .Description }}
+    <span class="page-list-desc">{{ .Description }}</span>
+    {{- end }}
+  </li>
+  {{- end }}
+</ul>
+{{- end -}}