abqari 1.1.0

data/app/views/partials/_related_items.html.erb

@@ -0,0 +1,105 @@
+<!--
+  Related items — renders below a show view (post, photo, publication)
+  with up to N pages from the same collection that share tags / series
+  / countries / etc. with the current page.
+
+  Usage from any layout:
+
+      <%%= render 'partials/related_items' %>
+
+  Optional locals:
+      <%%= render 'partials/related_items', limit: 6, match_by: %w[tags] %>
+
+  Wired into post.html.erb, photo.html.erb, publication.html.erb by
+  default. Renders nothing when there are no related items — never
+  pads with unrelated content.
+
+  Config (per collection in config/site.yml). Lives under `show:`
+  alongside the other show-page knobs — every show-view section
+  groups there for symmetry with `index:`.
+
+      collections:
+        posts:
+          show:
+            related:
+              enabled: true     # set false to disable for this collection
+              limit: 3          # max items to show
+              match_by: tags    # field name or list of names
+              show_image: true  # when true, always render a cover box —
+                                #   a placeholder tile (no <img>) for items
+                                #   that don't have `image:` / `cover:` in
+                                #   frontmatter. Keeps the grid visually
+                                #   consistent when some items have heroes
+                                #   and others don't. Set false to render
+                                #   text-only cards regardless.
+
+  Workshops-specific extras — workshops carry richer meta than the
+  generic `date:` field, so the related card below the title can
+  show dates and/or location. Both default true; flip false to hide:
+
+      collections:
+        workshops:
+          show:
+            related:
+              show_dates: true     # date_from – date_to (or duration fallback)
+              show_location: true  # city / country / "Remote"
+-->
+<%
+  # Resolve effective limit/match_by — explicit local override > collection
+  # config default. Always fetch the full ranked list, then slice for the
+  # visible block. Total count drives the "Show all N" CTA.
+  source_collection = page.respond_to?(:collection) ? page.collection : nil
+  cfg                = (source_collection ? site.collection_config(source_collection).dig('show', 'related') : nil) || {}
+  override_limit     = defined?(limit)    && limit    ? limit    : nil
+  override_match_by  = defined?(match_by) && match_by ? match_by : nil
+  effective_limit    = override_limit || cfg.fetch('limit', 3)
+  show_image         = cfg.fetch('show_image', true)
+
+  # Workshop-specific meta toggles. For other collections these are
+  # ignored (the partial falls back to the simpler `item.date` line).
+  is_workshop        = source_collection == 'workshops'
+  ws_show_dates      = is_workshop && cfg.fetch('show_dates',    true)
+  ws_show_location   = is_workshop && cfg.fetch('show_location', true)
+
+  all_related = site.related(page, match_by: override_match_by)
+
+  # Workshops: hide past entries from the related list — recommending
+  # an event that's already happened is noise. A workshop is "past"
+  # when its end-date (`date_to` ‖ `date_from`) is strictly before
+  # today; dateless evergreen workshops always count as upcoming.
+  if is_workshop
+    today = Date.today
+    all_related = all_related.reject do |item|
+      end_date = item.frontmatter['date_to'] || item.frontmatter['date_from']
+      end_date && to_time(end_date).to_date < today
+    end
+  end
+
+  visible = all_related.first(effective_limit)
+  total   = all_related.size
+%>
+<% if visible.any? %>
+<%# `related--book` modifier when the source collection is publications,
+    so the thumbnail uses a 2:3 book-cover aspect (instead of the
+    landscape 4:3 default that crops book covers top/bottom). %>
+<section class="related<%= ' related--book' if source_collection == 'publications' %>" aria-labelledby="related-heading">
+  <h2 id="related-heading" class="related__heading">Related</h2>
+  <ul class="related__list">
+    <% visible.each do |item| %>
+      <%== render 'partials/related_item',
+                 item:             item,
+                 show_image:       show_image,
+                 is_workshop:      is_workshop,
+                 ws_show_dates:    ws_show_dates,
+                 ws_show_location: ws_show_location %>
+    <% end %>
+  </ul>
+  <% if total > effective_limit %>
+    <p class="related__more">
+      <a href="<%= page.url.chomp('/') %>/related/">
+        Show all <%= total %> related items
+      </a>
+    </p>
+  <% end %>
+</section>
+<% end %>

data/app/views/partials/_search.html.erb

@@ -0,0 +1,26 @@
+<!--
+  Static search box powered by Pagefind. Requires `search: true` in
+  config/site.yml — when off, this partial renders nothing.
+
+  Pagefind walks _site/ at build time (or when `bin/index` is run) and
+  emits its CSS/JS runtime + chunked search index into _site/pagefind/.
+  The runtime is same-origin, but it compiles a WebAssembly module —
+  and WASM compilation is governed by CSP `script-src` regardless of
+  origin. HeadersFile#apply_search adds `'wasm-unsafe-eval'` to the
+  generated `_headers` CSP when `search: true`, so search works under
+  the strict policy on hosts that enforce `_headers`.
+
+  Drop this into a layout or another partial wherever you want a search box:
+    <%%= render 'partials/search' %>
+
+  Requires Pagefind on PATH at build time. See lib/abqari/search.rb for
+  install instructions.
+-->
+<% if site.config['search'] == true %>
+<div class="abqari-search">
+  <link rel="stylesheet" href="/pagefind/pagefind-ui.css">
+  <script src="/pagefind/pagefind-ui.js"></script>
+  <div id="abqari-search"></div>
+  <script src="<%= asset_path('js/search-init.js') %>" defer></script>
+</div>
+<% end %>

data/app/views/partials/_series_pager.html.erb

@@ -0,0 +1,48 @@
+<!--
+  Bidirectional series pager — previous / next by `series_position`.
+
+  The forward-only counterpart is `_next_in_series`, which reuses the
+  prominent `_post_list` index card. A pager is the right shape once
+  you need both directions: two stacked full-width cards read as two
+  unrelated sections rather than as one navigation control.
+
+  Intended for course-shaped collections — a module of ordered lessons,
+  a numbered guide run — where readers move backwards as often as
+  forwards. Generic across collections; nothing here is posts-specific.
+
+  Renders nothing when the page has no series neighbour in either
+  direction. When only one neighbour exists it renders alone and keeps
+  its slot (prev left, next right) so the controls don't swap sides
+  from page to page.
+
+  Required frontmatter: `series:` plus an Integer `series_position:`.
+  A quoted position ("3") drops the page out of the chain silently —
+  `bin/audit` flags it under Content.
+
+  Usage:
+      <%%== render 'partials/series_pager' %>
+-->
+<%
+  prev_page = site.prev_in_series(page)
+  next_page = site.next_in_series(page)
+%>
+<% if prev_page || next_page %>
+<nav class="series-pager" aria-label="Series navigation">
+  <% if prev_page %>
+    <a class="series-pager__link series-pager__link--prev" rel="prev" href="<%= sanitized_url(prev_page.url) %>">
+      <span class="series-pager__direction">Previous</span>
+      <span class="series-pager__title"><%= prev_page.title %></span>
+    </a>
+  <% else %>
+    <%# Empty slot keeps `next` in the right-hand column on the first
+        item in a series. Not focusable, not announced. %>
+    <span class="series-pager__slot-empty" aria-hidden="true"></span>
+  <% end %>
+  <% if next_page %>
+    <a class="series-pager__link series-pager__link--next" rel="next" href="<%= sanitized_url(next_page.url) %>">
+      <span class="series-pager__direction">Next</span>
+      <span class="series-pager__title"><%= next_page.title %></span>
+    </a>
+  <% end %>
+</nav>
+<% end %>

data/app/views/partials/_skip_link.html.erb

@@ -0,0 +1,12 @@
+<!--
+  Skip-to-content link. Renders as the very first focusable element on the
+  page so keyboard and screen-reader users can bypass the nav and jump
+  straight to the article. Visually hidden until focused (see .skip-link
+  CSS in each theme).
+
+  The target is `#main-content` — every layout sets that id and
+  `tabindex="-1"` on its <main> so the link can move focus there. Don't
+  remove the tabindex; without it, browsers won't focus a non-interactive
+  element after the anchor jump and screen readers lose context.
+-->
+<a class="skip-link" href="#main-content">Skip to content</a>

data/app/views/partials/_taxonomy_row.html.erb

@@ -0,0 +1,62 @@
+<!--
+  Row of taxonomy tiles — one per term, used by the photos landing
+  to render the "Series" and "Countries" sections. Reusable for any
+  taxonomy that maps to photos (or any dated collection).
+
+  Required locals:
+    heading       — section heading text (e.g. "Series")
+    taxonomy      — taxonomy name as configured in site.yml (e.g. 'series')
+    collection    — collection name to filter terms by (e.g. 'photos')
+    limit         — max tiles to show; nil = show all
+    all_url       — destination for the "View all" link; nil = no link
+    cols_class    — gallery-index column-modifier class (optional)
+
+  Each tile carries:
+    - Term name (e.g. "Maaloula 2026")
+    - Photo count
+    - Cover image: first photo's `image:` frontmatter, when present
+    - Link to the term's taxonomy index page
+
+  Terms are sorted by photo count desc (most-photographed series first),
+  then by name. Drop the section entirely when there are no terms.
+-->
+<%
+  terms_for_collection = site.posts_by_term(taxonomy)
+                             .transform_values { |pages| pages.select { |p| p.collection == collection } }
+                             .reject { |_term, pages| pages.empty? }
+                             .sort_by { |term, pages| [-pages.size, term.to_s] }
+  terms_for_collection = terms_for_collection.first(limit) if limit
+%>
+<% if terms_for_collection.any? %>
+<section class="taxonomy-row" aria-label="<%= h(heading) %>">
+  <%# Reuses `home-module__*` header classes for the heading + see-all
+      row — same shared pattern the photos landing's "Latest photos"
+      section uses. See _common.css note on home-module__header. %>
+  <header class="home-module__header">
+    <h2 class="home-module__heading"><%= heading %></h2>
+    <% if all_url && !all_url.to_s.empty? %>
+      <a class="home-module__see-all" href="<%= sanitized_url(all_url) %>">View all &rarr;</a>
+    <% end %>
+  </header>
+  <ul class="gallery-index<%= " gallery-index--cols-#{cols_class}" if cols_class %>">
+    <% terms_for_collection.each_with_index do |(term, pages), idx| %>
+      <% tint = "gallery-index__cover--tint-#{(idx % 4) + 1}" %>
+      <% cover = pages.first&.frontmatter&.dig('image') %>
+      <li>
+        <a href="<%= sanitized_url(taxonomy_url(taxonomy, term)) %>">
+          <div class="gallery-index__cover <%= tint %>">
+            <% if cover %>
+              <img src="<%= sanitized_url(bundle_asset_url_for(pages.first, cover)) %>"
+                   alt="<%= term %>"
+                   loading="lazy"
+                   decoding="async">
+            <% end %>
+          </div>
+          <span class="gallery-index__title"><%= term %></span>
+          <span class="gallery-index__location"><%= pluralize(pages.size, 'photo') %></span>
+        </a>
+      </li>
+    <% end %>
+  </ul>
+</section>
+<% end %>

data/app/views/partials/_testimonials.html.erb

@@ -0,0 +1,149 @@
+<!--
+  Testimonials block — semantic markup with `.testimonials*` and
+  `.testimonial*` class hooks. Theme CSS handles the visual.
+
+  Each testimonial can be "about" a record in any collection — a post,
+  a publication, a workshop, anything you ship. Tag it in the YAML
+  with either form below:
+
+      # Generic — works for any collection:
+      - quote: "Great workshop"
+        name:  Jane Doe
+        featured: true
+        collection: workshops
+        slug:       crisis-response-foundations
+
+      # Shorthand for publications (legacy, still supported):
+      - quote: "Couldn't put it down"
+        name:  Uri
+        featured: true
+        book:  memoirs-of-an-assassin           # equivalent to
+                                                # collection: publications
+                                                # slug:       memoirs-of-an-assassin
+
+  Filter modes (specify at most one — first match wins):
+
+      <%%= render 'partials/testimonials', subject: page %>
+                  # auto-detects collection + slug from the page; the
+                  # ergonomic call from any show view (post, workshop,
+                  # publication, anything else with `.collection` +
+                  # `.slug`).
+
+      <%%= render 'partials/testimonials',
+                    collection: 'workshops',
+                    slug: 'crisis-response-foundations' %>
+                  # explicit pair — for cases where you want testimonials
+                  # about a specific item from a context where the page
+                  # variable isn't that item.
+
+      <%%= render 'partials/testimonials', book_slug: 'memoirs-of-an-assassin' %>
+                  # legacy shorthand — equivalent to collection: publications.
+
+      <%%= render 'partials/testimonials', featured: true %>
+                  # no subject filter — show featured across all
+                  # collections. Useful on home / about pages.
+
+  Optional locals:
+      heading: 'Praise'        # section h2 text (defaults below)
+      featured: false          # by default the featured filter follows
+                               # the subject filter — no subject ⇒
+                               # featured-only (curated mix for home),
+                               # subject set ⇒ all matches. Pass true
+                               # or false to force either.
+
+  Renders nothing when there are no matching testimonials.
+
+  Note on indentation: when this partial is called from a markdown body
+  (with erb: true), commonmark interprets a blank line in the partial
+  output as the end of an HTML block, then treats subsequent indented
+  lines as a code block. So we keep all HTML at column 0 and use `-%>`
+  on control tags to avoid emitting blank/whitespace-only lines.
+-->
+<%
+  # Resolve the filter — subject (a page) ‖ explicit (collection,slug)
+  # ‖ legacy book_slug. First match wins; everything else is nil.
+  filter_collection = nil
+  filter_slug       = nil
+  if defined?(subject) && subject
+    filter_collection = subject.collection if subject.respond_to?(:collection)
+    filter_slug       = subject.slug       if subject.respond_to?(:slug)
+  elsif (defined?(collection) && collection) && (defined?(slug) && slug)
+    filter_collection = collection.to_s
+    filter_slug       = slug.to_s
+  elsif defined?(book_slug) && book_slug
+    filter_collection = 'publications'
+    filter_slug       = book_slug.to_s
+  end
+
+  # Featured filter default: show featured-only when there's no subject
+  # filter (curated mix for home/hub pages); show all matches when a
+  # subject IS set (it already narrows the list to one item — no
+  # additional curation needed). Callers can override either way.
+  filter_featured = defined?(featured) ? featured : filter_collection.nil?
+  show_heading    = defined?(heading)  ? heading  : 'What readers are saying'
+
+  # Normalize each testimonial's subject — accept generic
+  # `collection:` + `slug:`, OR the legacy `book:` shorthand. Returns
+  # [collection_name_or_nil, slug_or_nil].
+  t_subject = lambda do |t|
+    if t['collection'] && t['slug']
+      [t['collection'].to_s, t['slug'].to_s]
+    elsif t['book']
+      ['publications', t['book'].to_s]
+    else
+      [nil, nil]
+    end
+  end
+
+  testimonials = Array(site.data['testimonials']).select do |t|
+    t_col, t_sl = t_subject.call(t)
+    next false if filter_collection && (t_col != filter_collection || t_sl != filter_slug)
+    next false if filter_featured && t['featured'] != true
+    true
+  end
+
+  # Resolve a (collection, slug) pair to [url, title] for the citation
+  # link. Looks up the actual page first (any collection works); falls
+  # back to Folio data for publications; otherwise constructs a URL
+  # from the slug-aware `collection_index_url` and uses the slug as the
+  # title. Returns [nil, nil] if collection/slug aren't set.
+  resolve_subject = lambda do |c, s|
+    return [nil, nil] unless c && s
+    coll = site.collection(c) rescue nil
+    if coll && (item = coll.find { |i| i.respond_to?(:slug) && i.slug == s })
+      return [item.url, item.title]
+    end
+    if c == 'publications'
+      pub = (site.data['folio_publications'] || {})[s]
+      return ["#{collection_index_url('publications')}#{s}/", pub['title']] if pub
+    end
+    ["#{collection_index_url(c)}#{s}/", s]
+  end
+-%>
+<% if testimonials.any? -%>
+<section class="testimonials" aria-label="Reader testimonials">
+<% if show_heading -%>
+<h2 class="testimonials__heading"><%= show_heading %></h2>
+<% end -%>
+<div class="card-grid">
+<% testimonials.each do |t| -%>
+<% t_col, t_sl = t_subject.call(t) -%>
+<% subject_url, subject_title = resolve_subject.call(t_col, t_sl) -%>
+<figure class="testimonial">
+<blockquote class="testimonial__quote">
+&ldquo;<%= t['quote'] %>&rdquo;
+</blockquote>
+<figcaption class="testimonial__cite">
+<strong><%= t['name'] %></strong>
+<% if (date = t['date']) && !date.to_s.empty? -%>
+<span> &middot; <%= date %></span>
+<% end -%>
+<% if subject_url && subject_title -%>
+<span> &middot; on <a href="<%= sanitized_url(subject_url) %>"><%= subject_title %></a></span>
+<% end -%>
+</figcaption>
+</figure>
+<% end -%>
+</div>
+</section>
+<% end -%>

data/app/views/partials/_theme_toggle.html.erb

@@ -0,0 +1,19 @@
+<!--
+  Light/dark theme toggle (opt-in). Render anywhere you want the button:
+  <%%= render 'partials/theme_toggle' %>
+
+  How it works:
+    1. The inline bootstrap in _head.html.erb hydrates <html data-theme="..."> from
+       localStorage before render — no flash of the wrong theme.
+    2. Each theme's CSS responds to [data-theme="dark"] / [data-theme="light"]
+       overrides; without an attribute, prefers-color-scheme still wins.
+    3. Clicking flips data-theme and persists in localStorage via theme-toggle.js.
+-->
+<%# `aria-pressed` starts as "false" (light) — theme-toggle.js syncs it to
+    the resolved theme on load and flips it on click. Screen readers
+    announce the current state of the toggle to the user. %>
+<button type="button" class="theme-toggle" aria-label="Toggle light/dark theme" aria-pressed="false" data-theme-toggle>
+  <span class="theme-toggle__sun" aria-hidden="true"><%== icon 'sun', width: '18', height: '18' %></span>
+  <span class="theme-toggle__moon" aria-hidden="true"><%== icon 'moon', width: '18', height: '18' %></span>
+</button>
+<script src="<%= asset_path('js/theme-toggle.js') %>" defer></script>

data/app/views/partials/_toc.html.erb

@@ -0,0 +1,136 @@
+<!--
+  Auto-generated table of contents. Parses headings from the page's
+  rendered body and emits a flat `<nav>` of anchor links. Commonmarker
+  2.x emits markdown headings as:
+
+      <h2 id="slug">Heading text<a href="#slug" … class="anchor"></a></h2>
+
+  We pluck level + id + text from that. The trailing `class="anchor"`
+  child is what identifies a heading as commonmarker's: auxiliary
+  headings the layouts add carry an id but no anchor child, so they
+  stay out of the TOC.
+
+  (Commonmarker 1.x put the id on a LEADING anchor instead —
+  `<h2><a id="slug" class="anchor"></a>Heading text</h2>` — and the id
+  living on the anchor was itself the discriminator. 2.x moved the id
+  onto the heading, which is why both the pattern and the filter had
+  to change.)
+
+  Wire from any show layout (post, publication, photo, workshop):
+      <%%= render 'partials/toc' %>
+
+  Optional locals (override the collection config for this call site):
+      min_headings: 3       # quality floor
+      levels: [2, 3]        # heading levels to include in the TOC
+
+  Gating — three layers, frontmatter wins:
+
+    1. Frontmatter `toc: true` / `toc: false` on the page itself.
+       Explicit boolean overrides every other source. Use `toc: false`
+       to suppress for a long post that doesn't read well with one,
+       or `toc: true` to force the section even on a page where the
+       collection has TOCs turned off (still gated by min_headings).
+
+    2. Per-collection config in config/site.yml:
+
+         collections:
+           posts:
+             show:
+               toc:
+                 enabled: true          # default — set false to suppress
+                 min_headings: 3        # quality floor; short posts get nothing
+                 levels: [2, 3]         # heading levels to include
+                                        #   [2]       → h2 only
+                                        #   [2, 3]    → h2 + h3 (default)
+                                        #   [2, 3, 4] → include h4 sub-headings
+
+       Sits under `show:` alongside `next` and `related` — every knob
+       that affects the show page lives there. (Mirrors `index:`
+       grouping for listing-page knobs.)
+
+    3. Engine defaults — `enabled: true`, `min_headings: 3`,
+       `levels: [2, 3]`.
+
+  The min_headings floor applies even when toc is explicitly `true`
+  — forcing a TOC on a 2-heading page reads as noise, not content.
+  If you genuinely want a 1-heading TOC, set `min_headings: 1` in
+  config or pass it as a local; the two knobs stay independent.
+
+  h1 never appears in the TOC (it's the page title, rendered by the
+  layout, not part of the body markdown). h2–h6 are eligible via
+  `levels:`; the engine ships visible CSS indent steps for h2–h4
+  (deeper levels render but visually flatten to the h4 indent —
+  almost no one needs h5/h6 in a TOC).
+-->
+<%
+  # --- Resolve gating from frontmatter / collection / engine defaults ---
+  toc_cfg = if page.respond_to?(:collection) && page.collection
+              (site.collection_config(page.collection) || {}).dig('show', 'toc') || {}
+            else
+              {}
+            end
+
+  # Frontmatter `toc:` accepts explicit boolean. Any other value
+  # (missing, nil, non-bool) falls through to the collection default.
+  fm_toc  = page.frontmatter['toc']
+  enabled = if fm_toc == true || fm_toc == false
+              fm_toc
+            else
+              toc_cfg.fetch('enabled', true)
+            end
+
+  # `min_headings:` resolution: explicit local > collection config > 3.
+  min_count = if defined?(min_headings) && min_headings
+                min_headings.to_i
+              else
+                toc_cfg.fetch('min_headings', 3).to_i
+              end
+
+  # `levels:` resolution: explicit local > collection config >
+  # default [2, 3]. Clamped to the 2..6 range — h1 is the layout's
+  # page title, h7+ doesn't exist in HTML. Sorted + deduped so the
+  # regex below is deterministic regardless of how the operator
+  # ordered the array.
+  raw_levels = (defined?(levels) && levels) || toc_cfg['levels'] || [2, 3]
+  toc_levels = Array(raw_levels).map(&:to_i).select { |n| (2..6).cover?(n) }.uniq.sort
+  toc_levels = [2, 3] if toc_levels.empty?
+%>
+<% if enabled
+     body         = page.respond_to?(:content) ? page.content.to_s : ''
+     level_chars  = toc_levels.join              # e.g. "23" → matches h2 + h3
+     heading_re   = %r{<(h[#{level_chars}])\s[^>]*id="([^"]+)"[^>]*>([^<]+)<a[^>]*class="anchor"[^>]*></a></\1>}m
+     # The trailing `class="anchor"` child is commonmarker's convention;
+     # layout-added headings (next-item, related, the TOC's own
+     # "Contents" h2) carry an id but no anchor child, so they're
+     # excluded automatically. As before, `[^<]+` means a heading
+     # containing inline markup (e.g. `## Using <code>foo</code>`) is
+     # skipped rather than half-rendered into the list.
+     matches = body.scan(heading_re)
+   else
+     matches = []
+   end %>
+<% if matches.size >= min_count %>
+<nav class="toc" aria-labelledby="toc-heading">
+  <%# Native `<details>` for collapse — zero JS, full keyboard +
+      screen-reader support out of the box. `open` makes the
+      expanded state the default; the user can collapse with a
+      click or with Enter/Space on the focused summary. %>
+  <details class="toc__details" open>
+    <summary class="toc__summary">
+      <h2 id="toc-heading" class="toc__heading">Contents</h2>
+      <%# Chevron — points down when expanded, rotates to point
+          right when collapsed. `aria-hidden` because the summary
+          itself already exposes the expanded/collapsed state to
+          assistive tech via the native details semantics. %>
+      <svg class="toc__chevron" width="16" height="16" viewBox="0 0 20 20" fill="none" aria-hidden="true">
+        <path d="M6 8l4 4 4-4" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"/>
+      </svg>
+    </summary>
+    <ol class="toc__list">
+      <% matches.each do |tag, id, text| %>
+        <li class="toc__item toc__item--<%= tag %>"><a href="#<%= id %>"><%= text %></a></li>
+      <% end %>
+    </ol>
+  </details>
+</nav>
+<% end %>