abqari 1.1.0

data/app/views/layouts/workshops_index.html.erb

@@ -0,0 +1,209 @@
+---
+layout: application
+---
+<!--
+  Workshops index — listing of all workshops in the collection.
+
+  The page splits workshops into two groups based on their dates:
+
+    - Upcoming (`date_to` ≥ today, or `date_from` ≥ today when no end
+      date is set, or no dates at all — evergreen offerings count as
+      "available"): rendered as full cards with description and full
+      meta line (date · location · format · price).
+
+    - Past (`date_to` < today, or `date_from` < today when no end
+      date): rendered in a separate "Past workshops" section using
+      a more compact list style — title + date + location only.
+      Same shape rationale as the related partials: less prominent,
+      less information, distinct from the primary listing.
+
+  Per-card display on the UPCOMING cards is controlled by
+  `collections.workshops.index.show_*` toggles in config/site.yml.
+  Past cards always render the compact treatment regardless of
+  config — the toggles are about adjusting upcoming density.
+
+  Title and description on this page come from
+  `content/workshops/index.md`'s frontmatter:
+
+      ---
+      title: Workshops
+      description: Hands-on training in crisis response, …
+      layout: workshops_index
+      ---
+
+  Sort order: stable alphabetic on title, with `order:` frontmatter
+  taking precedence. Past workshops sort newest-first (most recent
+  end date at the top).
+-->
+<%
+  description = page.frontmatter['description']
+  cfg = (site.collection_config('workshops')['index'] || {})
+  show_description = cfg.fetch('show_description', true)
+  show_dates       = cfg.fetch('show_dates',       true)
+  show_location    = cfg.fetch('show_location',    true)
+  show_format      = cfg.fetch('show_format',      true)
+  show_price       = cfg.fetch('show_price',       true)
+  truncate_at      = cfg.fetch('description_truncate', 160)
+
+  # Partition workshops into upcoming + past. A workshop is "past"
+  # only when its end-date (date_to ‖ date_from) is strictly before
+  # today. Workshops with no dates at all count as upcoming
+  # (evergreen offerings that run when requested).
+  today = Date.today
+  workshop_past = lambda do |fm|
+    end_date = fm['date_to'] || fm['date_from']
+    next false unless end_date
+    to_time(end_date).to_date < today
+  end
+
+  workshops = site.collection('workshops').reject { |w| w.url == page.url }
+  upcoming, past = workshops.partition { |w| !workshop_past.call(w.frontmatter) }
+
+  # Upcoming sort: by frontmatter order, then by start date asc, then title.
+  upcoming.sort_by! do |w|
+    fm = w.frontmatter
+    start_key = fm['date_from'] ? to_time(fm['date_from']).to_i : Float::INFINITY
+    [fm['order'] || Float::INFINITY, start_key, w.title.to_s]
+  end
+
+  # Past sort: most recent first (descending end date).
+  past.sort_by! do |w|
+    fm = w.frontmatter
+    end_date = fm['date_to'] || fm['date_from']
+    -(end_date ? to_time(end_date).to_i : 0)
+  end
+
+  # Date-range fragment for a card — `<time>` element(s) for the start
+  # date, plus an en-dash and a second `<time>` when there's a distinct
+  # end date. Returns nil if there are no dates and no duration to fall
+  # back on.
+  build_date_html = lambda do |fm|
+    if show_dates && (df = fm['date_from'])
+      html = %(<time datetime="#{to_time(df).iso8601}">#{local_time(df)}</time>)
+      if (dt = fm['date_to']) && dt != df
+        html += %( &ndash; <time datetime="#{to_time(dt).iso8601}">#{local_time(dt)}</time>)
+      end
+      html
+    elsif (duration = fm['duration'])
+      h(duration)
+    end
+  end
+
+  # Compact meta line for the past-workshops section — collapses
+  # date + location into a single bullet-separated row.
+  build_compact_meta = lambda do |fm|
+    parts = []
+    if (d = build_date_html.call(fm))
+      parts << d
+    end
+    parts << h(fm['location']) if show_location && fm['location']
+    parts
+  end
+%>
+<article>
+  <header>
+    <h1><%= page.title || 'Workshops' %></h1>
+    <% if description && !description.to_s.empty? %>
+      <p class="lede"><%= description %></p>
+    <% end %>
+  </header>
+  <% if page.content && !page.content.to_s.strip.empty? %>
+    <div class="index-intro"><%== page.content %></div>
+  <% end %>
+
+  <%# Future workshops — full cards. Renders a heading even when the
+      list is empty so the section structure stays parallel with past
+      workshops below. %>
+  <section class="workshops-index__group workshops-index__group--future">
+    <h2 class="workshops-index__heading">Future workshops</h2>
+    <% if upcoming.any? %>
+      <ul class="workshops-index">
+        <% upcoming.each do |w| %>
+          <% fm = w.frontmatter %>
+          <li class="workshops-index__item">
+            <a href="<%= w.url %>" class="workshops-index__link">
+              <%# Cover slot. `cover_choice_for` returns :photo /
+                  :placeholder / :svg / :none based on the
+                  `workshops.index.cover` enum + frontmatter override. %>
+              <% case cover_choice_for(w, context: :index) %>
+              <% when :photo %>
+                <span class="workshops-index__cover">
+                  <img src="<%= sanitized_url(bundle_asset_url_for(w, fm['image'])) %>"
+                       alt="<%= w.title %>"
+                       loading="lazy">
+                </span>
+              <% when :placeholder %>
+                <span class="workshops-index__cover">
+                  <svg class="workshops-index__cover-placeholder" viewBox="0 0 4 3"
+                       preserveAspectRatio="none" aria-hidden="true">
+                    <rect width="4" height="3" fill="currentColor"/>
+                  </svg>
+                </span>
+              <% when :svg %>
+                <span class="workshops-index__cover workshops-index__cover--svg">
+                  <%== cover_svg_for(w) %>
+                </span>
+              <% when :none %>
+              <% end %>
+              <span class="workshops-index__body">
+                <h3 class="workshops-index__title"><%= w.title %></h3>
+
+                <% if show_description && (desc = fm['description']) && !desc.to_s.empty? %>
+                  <p class="workshops-index__description"><%= truncate(desc.to_s, length: truncate_at) %></p>
+                <% end %>
+
+                <%# Meta block — three stacked lines on upcoming cards
+                    so each fact reads cleanly:
+                      1. Date range (or duration when no dates)
+                      2. Location · Format (joined by ·, both optional)
+                      3. Price
+                    Any line whose source data is absent or whose toggle
+                    is off renders nothing — the remaining lines close up. %>
+                <% if (date_html = build_date_html.call(fm)) %>
+                  <p class="workshops-index__meta workshops-index__meta--dates"><%== date_html %></p>
+                <% end %>
+                <%
+                  loc_parts = []
+                  loc_parts << h(fm['location']) if show_location && fm['location']
+                  loc_parts << h(fm['format'])   if show_format   && fm['format']
+                %>
+                <% if loc_parts.any? %>
+                  <p class="workshops-index__meta workshops-index__meta--location"><%== loc_parts.join(' &middot; ') %></p>
+                <% end %>
+                <% if show_price && (price = fm['price']) %>
+                  <p class="workshops-index__meta workshops-index__meta--price"><%= price %></p>
+                <% end %>
+              </span>
+            </a>
+          </li>
+        <% end %>
+      </ul>
+    <% else %>
+      <p class="workshops-index__empty muted">No future workshops scheduled.</p>
+    <% end %>
+  </section>
+
+  <%# Past workshops — compact treatment. Section header makes the
+      visual demotion explicit; cards drop description, format, price. %>
+  <% if past.any? %>
+    <section class="workshops-index__group workshops-index__group--past">
+      <h2 class="workshops-index__heading workshops-index__heading--past">Past workshops</h2>
+      <ul class="workshops-index workshops-index--past">
+        <% past.each do |w| %>
+          <% fm = w.frontmatter %>
+          <li class="workshops-index__item workshops-index__item--past">
+            <a href="<%= w.url %>" class="workshops-index__link">
+              <span class="workshops-index__body">
+                <h3 class="workshops-index__title"><%= w.title %></h3>
+                <% parts = build_compact_meta.call(fm) %>
+                <% if parts.any? %>
+                  <p class="workshops-index__meta"><%== parts.join(' &middot; ') %></p>
+                <% end %>
+              </span>
+            </a>
+          </li>
+        <% end %>
+      </ul>
+    </section>
+  <% end %>
+</article>

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

@@ -0,0 +1,27 @@
+<!--
+  "← Back" link primitive — used at the top or bottom of detail pages
+  to give readers an explicit way back to the parent index. Optional
+  pattern; layouts opt in by rendering this partial where they want
+  the link.
+
+  Locals:
+    url:    target URL (default "/")
+    label:  link text  (default "Back")
+
+  Usage:
+      <%%= render 'partials/back_link' %%>                                    <!-- "← Back" to "/" -->
+      <%%= render 'partials/back_link', label: 'Back to all books' %%>
+      <%%= render 'partials/back_link', url: '/books/', label: 'Back to books' %%>
+
+  Themes style `.back-link__wrapper` and `.back-link` — adjust spacing
+  and color to taste. Sites on Bootstrap or another component framework
+  can override this partial with framework-flavored markup (drop a copy
+  in the site's app/views/partials/_back_link.html.erb).
+-->
+<% _label = defined?(label) ? label : 'Back' %>
+<% _url   = defined?(url)   ? url   : '/' %>
+<p class="back-link__wrapper">
+  <a class="back-link" href="<%= sanitized_url(_url) %>">
+    &larr; <%= _label %>
+  </a>
+</p>

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

@@ -0,0 +1,25 @@
+<!--
+  Slug-aware "← Back to <collection>" link, used at the top of show
+  views (post, photo, publication, etc.). The label and URL both follow
+  the collection's `slug:` aliasing automatically:
+
+    posts (no slug)             → "Back to posts" → /posts/
+    posts with slug: stories    → "Back to stories" → /stories/
+    posts with slug: articles   → "Back to articles" → /articles/
+    publications, slug: books   → "Back to books" → /books/
+
+  Renders nothing for pages outside any collection (top-level pages,
+  Folio bundle/series pages where the destination isn't obvious).
+
+  Override either side at the call site:
+      <%%= render 'partials/back_to_index' %>
+      <%%= render 'partials/back_to_index', label: 'All posts' %>
+      <%%= render 'partials/back_to_index', url: '/archive/', label: 'Archive' %>
+-->
+<% _url   = defined?(url)   ? url   : collection_index_url %>
+<% _label = defined?(label) ? label : (collection_index_label && "Back to #{collection_index_label}") %>
+<% if _url && _label %>
+<p class="back-link">
+  <a href="<%= sanitized_url(_url) %>">&larr; <%= _label %></a>
+</p>
+<% end %>

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

@@ -0,0 +1,76 @@
+<!--
+  Book grid — a card grid of every publication, ordered by
+  `in_series.position` then alphabetically by title. Reads from
+  `site.collection('publications')`, which includes both manual
+  pages and any externally-sourced publications a publisher
+  integration (e.g. Folio) has added.
+
+  Renders nothing when the publications collection is empty, so it's
+  safe to drop into any layout regardless of whether the site has
+  any books yet.
+
+  Usage from a layout or markdown body (with `erb: true` in
+  frontmatter):
+      <%%= render 'partials/book_grid' %>
+      <%%= render 'partials/book_grid', heading: 'The Novels' %>
+
+  URL prefix follows `publications.slug` aliasing — sites that set
+  `publications.slug: books` get `/books/<slug>/` links here
+  automatically.
+
+  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.
+-->
+<%
+  books = site.collection('publications').sort_by do |p|
+    pos = p.frontmatter.dig('in_series', 'position') || p.frontmatter['order'] || 999
+    [pos, p.title.to_s]
+  end
+
+  pubs_cfg = site.collection_config('publications')
+  pubs_prefix = pubs_cfg['slug'].to_s.empty? ?
+    pubs_cfg['permalink'].to_s.sub(':slug/', '').sub(':slug', '') :
+    "/#{pubs_cfg['slug']}/"
+  pubs_prefix = '/publications/' if pubs_prefix.empty?
+
+  _heading = defined?(heading) ? heading : nil
+-%>
+<% if books.any? -%>
+<section class="folio-book-grid" aria-label="<%= _heading || 'Books' %>">
+<% if _heading -%>
+<h2 class="folio-book-grid__heading"><%= _heading %></h2>
+<% end -%>
+<div class="folio-book-grid__list">
+<% books.each do |book| -%>
+<%
+  fm        = book.frontmatter
+  cover_url = fm['cover_url']
+  tagline   = fm['tagline']
+  has_buy   = fm['buy_now_url'] || fm['add_to_cart_url']
+-%>
+<article class="folio-book-grid__item">
+<a href="<%= pubs_prefix %><%= book.slug %>/" class="folio-book-grid__cover-link">
+<% if cover_url -%>
+<div class="book-cover">
+<img src="<%= sanitized_url(cover_url) %>" alt="<%= book.title %> cover" loading="lazy">
+</div>
+<% end -%>
+</a>
+<h3 class="folio-book-grid__title">
+<a href="<%= pubs_prefix %><%= book.slug %>/"><%= book.title %></a>
+</h3>
+<% if tagline -%>
+<p class="folio-book-grid__tagline"><%= tagline %></p>
+<% end -%>
+<p class="folio-book-grid__cta">
+<a href="<%= pubs_prefix %><%= book.slug %>/" class="btn btn-outline-secondary"><%= has_buy ? 'Read more' : 'Coming soon' %> &rarr;</a>
+</p>
+</article>
+<% end -%>
+</div>
+</section>
+<% end -%>

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

@@ -0,0 +1,72 @@
+<!--
+  Schema.org Book JSON-LD for publication detail pages. Reads
+  canonical fields from `page.frontmatter` directly — whether the
+  publication is a manual content file or Folio-sourced, the field
+  names are the same (see docs/publications.md).
+
+  Renders for every publication that has a title (i.e. always).
+  Missing fields are omitted from the emitted JSON-LD rather than
+  emitted as nulls.
+-->
+<%
+  fm       = page.frontmatter || {}
+  site_url = site.config['url'].to_s.sub(%r{/\z}, '')
+  title    = page.title
+%>
+<% if title %>
+<%
+  jsonld = {
+    "@context"   => "https://schema.org",
+    "@type"      => "Book",
+    "name"       => title,
+    "bookFormat" => "https://schema.org/EBook"
+  }
+  jsonld["url"] = "#{site_url}#{page.url}" unless site_url.empty?
+  jsonld["mainEntityOfPage"] = { "@type" => "WebPage", "@id" => "#{site_url}#{page.url}" } unless site_url.empty?
+
+  # Author — page-level `author:` (Folio shape: { slug, name } Hash,
+  # or a plain string) wins over site-wide.
+  author_raw = fm['author'] || site.config['author']
+  if author_raw
+    author_name = author_raw.is_a?(Hash) ? author_raw['name'] : author_raw.to_s
+    jsonld["author"] = { "@type" => "Person", "name" => author_name } unless author_name.to_s.empty?
+  end
+
+  jsonld["isbn"]          = fm['isbn']            if fm['isbn']
+  jsonld["inLanguage"]    = fm['language']        if fm['language']
+  jsonld["numberOfPages"] = fm['pages'].to_i      if fm['pages']
+  jsonld["description"]   = fm['tagline'] || fm['excerpt'] || page.description
+
+  # Image — canonical `cover_url`. Absolute URL or site-relative path.
+  if (cover = fm['cover_url'])
+    jsonld["image"] = if cover.start_with?('http://', 'https://')
+                        cover
+                      elsif cover.start_with?('/')
+                        "#{site_url}#{cover}"
+                      else
+                        "#{site_url}#{bundle_asset_url_for(page, cover)}"
+                      end
+  end
+
+  # Date published — Folio carries ISO timestamps; frontmatter may
+  # carry plain dates. Normalise to ISO when possible.
+  if (raw_date = fm['published_at'])
+    jsonld["datePublished"] = raw_date.respond_to?(:iso8601) ? raw_date.iso8601 : raw_date.to_s
+  end
+
+  # Offers — canonical price is a Hash { cents, currency, formatted }
+  # (the publication normaliser expands string shorthands at parse
+  # time, so this is the only shape we need to read).
+  if (price = fm['price']).is_a?(Hash) && price['cents']
+    available = fm.key?('available_for_purchase') ? fm['available_for_purchase'] : true
+    jsonld["offers"] = {
+      "@type"         => "Offer",
+      "price"         => (price['cents'].to_f / 100).round(2),
+      "priceCurrency" => price['currency'] || 'USD',
+      "availability"  => available ? 'https://schema.org/InStock' : 'https://schema.org/PreOrder',
+      "url"           => fm['buy_now_url'] || fm['shop_url']
+    }.compact
+  end
+%>
+<script type="application/ld+json"><%== script_safe_json(jsonld.compact) %></script>
+<% end %>

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

@@ -0,0 +1,87 @@
+<!--
+  Related books — sister-publications block on a single publication
+  detail page. Reads from `site.collection('publications')` so it
+  works equally with manual content files, externally-sourced
+  entries, or any mix.
+
+  "Related" today = other publications in the same series, sorted by
+  `in_series.position`. Future enhancements (tag / category overlap
+  when there's no series) plug into this same lookup.
+
+  Adaptive heading: "Ready for the sequel?" / "Continue the series" /
+  "Earlier in the series" / "Other books in the series" — depending
+  on where the current book sits in the sequence.
+
+  Renders nothing when the book isn't in a series OR when the series
+  has no other published books.
+-->
+<%
+  current_series   = page.frontmatter.dig('in_series', 'slug')
+  current_position = page.frontmatter.dig('in_series', 'position').to_i
+
+  related = if current_series
+              site.collection('publications')
+                  .reject { |b| b.slug == page.slug }
+                  .select { |b| b.frontmatter.dig('in_series', 'slug') == current_series }
+                  .sort_by { |b| b.frontmatter.dig('in_series', 'position') || Float::INFINITY }
+            else
+              []
+            end
+
+  heading = if related.size == 1
+              rel_pos = related.first.frontmatter.dig('in_series', 'position').to_i
+              if rel_pos == current_position + 1
+                'Ready for the sequel?'
+              elsif rel_pos > current_position
+                'Continue the series'
+              elsif rel_pos == 1
+                "Haven't read the first book?"
+              else
+                'Earlier in the series'
+              end
+            else
+              'Other books in the series'
+            end
+
+  # URL prefix for individual publication pages — honors `slug:` aliasing.
+  pubs_cfg = site.collection_config('publications')
+  pubs_prefix = pubs_cfg['slug'].to_s.empty? ?
+    pubs_cfg['permalink'].to_s.sub(':slug/', '').sub(':slug', '') :
+    "/#{pubs_cfg['slug']}/"
+  pubs_prefix = '/publications/' if pubs_prefix.empty?
+%>
+<% if related.any? %>
+<section class="book-related" aria-label="Related books">
+  <h2 class="book-related__heading"><%= heading %></h2>
+
+  <% related.each do |b| %>
+    <% fm = b.frontmatter %>
+    <% has_buy = fm['buy_now_url'] || fm['add_to_cart_url'] %>
+    <article class="book-related__item">
+      <a href="<%= pubs_prefix %><%= b.slug %>/" class="book-related__cover">
+        <% if (cover = fm['cover_url']) %>
+          <div class="book-cover">
+            <img src="<%= sanitized_url(cover) %>"
+                 alt="<%= b.title %> cover"
+                 loading="lazy">
+          </div>
+        <% end %>
+      </a>
+
+      <div class="book-related__body">
+        <h3 class="book-related__title">
+          <a href="<%= pubs_prefix %><%= b.slug %>/"><%= b.title %></a>
+        </h3>
+
+        <% if (tagline = fm['tagline']) %>
+          <p class="book-related__tagline"><%= tagline %></p>
+        <% end %>
+
+        <a href="<%= pubs_prefix %><%= b.slug %>/" class="book-related__cta">
+          <%= has_buy ? 'Read more' : 'Coming soon' %> &rarr;
+        </a>
+      </div>
+    </article>
+  <% end %>
+</section>
+<% end %>

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

@@ -0,0 +1,60 @@
+<!--
+  Schema.org BreadcrumbList JSON-LD. Builds a 2-3 item trail
+  automatically from the page's collection (or its index ancestry):
+
+    Home → Posts → Building with Abqari       (post show)
+    Home → Photos → Old city walls            (photo show)
+    Home → Publications → An Atlas of …       (publication show)
+    Home → Workshops → Crisis Response …      (workshop show)
+    Home → Posts                              (posts index)
+
+  Slug-aware: if `posts.slug: stories`, the middle crumb reads
+  "Stories" and links to `/stories/`. The label is title-cased from
+  the effective collection name; override with a per-page
+  `breadcrumb_parent_label:` if needed.
+
+  Renders nothing when:
+    - the site has no `url:` configured (need absolute IDs)
+    - the page has no collection AND no detectable collection-index
+      ancestry (home, About, top-level pages)
+
+  Use it from any show or index layout:
+      <%%= render 'partials/breadcrumb_jsonld' %>
+-->
+<%
+  site_url = site.config['url'].to_s.sub(%r{/\z}, '')
+  coll_for_show  = page.respond_to?(:collection) ? page.collection : nil
+  coll_for_index = site.collection_index_name(page) if page.respond_to?(:source_path)
+  coll_name      = coll_for_show || coll_for_index
+%>
+<% if !site_url.empty? && coll_name %>
+<%
+  cfg          = site.collection_config(coll_name) || {}
+  effective    = cfg['slug'].to_s.empty? ? coll_name : cfg['slug'].to_s
+  parent_url   = "#{site_url}/#{effective}/"
+  parent_label = page.frontmatter['breadcrumb_parent_label'] ||
+                 effective.capitalize
+
+  crumbs = [
+    { "@type" => "ListItem", "position" => 1, "name" => 'Home', "item" => "#{site_url}/" },
+    { "@type" => "ListItem", "position" => 2, "name" => parent_label, "item" => parent_url }
+  ]
+
+  # When this page IS the collection index, the trail stops at "Home →
+  # Posts". When it's a show page (page.collection set), append a third
+  # crumb pointing at the current page.
+  if coll_for_show
+    crumbs << { "@type" => "ListItem",
+                "position" => 3,
+                "name"     => page.title.to_s,
+                "item"     => "#{site_url}#{page.url}" }
+  end
+
+  jsonld = {
+    "@context"        => "https://schema.org",
+    "@type"           => "BreadcrumbList",
+    "itemListElement" => crumbs
+  }
+%>
+<script type="application/ld+json"><%== script_safe_json(jsonld) %></script>
+<% end %>

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

@@ -0,0 +1,26 @@
+<!--
+  CTA box on a publication page nudging the reader toward a bundle
+  that contains this book. Required local: `bundle_slug`. Looks the
+  bundle up in `site.collection('bundles')` so the partial works
+  whether the bundle is manual content or Folio-sourced (after the
+  canonical-schema migration both are in the same collection).
+
+  Emits nothing if the bundle isn't found.
+-->
+<% bundle = site.collection('bundles').find { |b| b.slug == bundle_slug } %>
+<% if bundle %>
+  <% fm = bundle.frontmatter %>
+  <aside class="folio-bundle-cta">
+    <h3>Save with the bundle</h3>
+    <p>
+      <a href="<%= bundle.url %>"><%= bundle.title %></a>
+      <% if (price = fm.dig('price', 'formatted')) %>
+        — <%= price %>
+      <% end %>
+    </p>
+    <p class="folio-bundle-cta__buttons">
+      <%== buy_button(fm, label: fm['buy_label'] || 'Buy bundle') %>
+      <%== cart_button(fm) %>
+    </p>
+  </aside>
+<% end %>

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

@@ -0,0 +1,64 @@
+<!--
+  Photo carousel — slideshow view of an arbitrary collection (defaults
+  to `photos`). Render from any layout:
+
+      <%%= render 'partials/carousel' %>
+      <%%= render 'partials/carousel', collection: 'posts' %>
+
+  Or with an explicit list of photos:
+
+      <%%= render 'partials/carousel', items: site.collection('photos').first(20) %>
+
+  Each slide reads `image:`, `title`, `caption:`, `city`, `country`,
+  `date` from the source page — same shape the photo layout expects.
+  Vanilla-JS click handlers (no Bootstrap dependency); arrow keys + click
+  navigation; CSP-safe (external `carousel.js` only, no inline scripts).
+-->
+<%
+  items = if defined?(items) && items
+            items
+          else
+            requested = (defined?(collection) && collection) || 'photos'
+            site.collection(requested)
+          end
+%>
+<% if items.any? %>
+  <div class="carousel" data-carousel>
+    <div class="carousel__track">
+      <% items.each_with_index do |item, idx| %>
+        <figure class="carousel__slide<%= idx.zero? ? ' is-active' : '' %>" aria-hidden="<%= idx.zero? ? 'false' : 'true' %>">
+          <% if item.frontmatter['image'] %>
+            <img class="carousel__image"
+                 src="<%= item.frontmatter['image'] %>"
+                 alt="<%= item.frontmatter['caption'] || item.title %>"
+                 <%== idx.zero? ? 'fetchpriority="high"' : 'loading="lazy"' %>>
+          <% end %>
+          <figcaption class="carousel__caption">
+            <a href="<%= item.url %>" class="carousel__title"><%= item.title %></a>
+            <% if item.frontmatter['caption'] %>
+              <p class="carousel__quote"><%= item.frontmatter['caption'] %></p>
+            <% end %>
+            <p class="carousel__meta">
+              <% if item.frontmatter['city'] || item.frontmatter['country'] %>
+                <%= [item.frontmatter['city'], item.frontmatter['country']].compact.join(', ') %>
+              <% end %>
+              <% if item.respond_to?(:date) && item.date %>
+                · <time datetime="<%= item.date.iso8601 %>"><%= local_time(item.date) %></time>
+              <% end %>
+            </p>
+          </figcaption>
+        </figure>
+      <% end %>
+    </div>
+    <button type="button" class="carousel__prev" aria-label="Previous slide" data-carousel-prev>
+      <span aria-hidden="true">&larr;</span>
+    </button>
+    <button type="button" class="carousel__next" aria-label="Next slide" data-carousel-next>
+      <span aria-hidden="true">&rarr;</span>
+    </button>
+    <p class="carousel__counter">
+      <span data-carousel-current>1</span> / <%= items.size %>
+    </p>
+  </div>
+  <script src="<%= asset_path('js/carousel.js') %>" defer></script>
+<% end %>