RubyGems - abqari - Versions diffs - 1.1.0 - Mend

abqari 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1509) hide show

data/lib/abqari/log.rb ADDED Viewed

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+module Abqari
+  # Tiny leveled logger. No stdlib `Logger` ceremony — one module, four
+  # severity methods, level filtered at call time. Configured via the
+  # ABQARI_LOG env var (debug / info / warn / error). Default: info.
+  #
+  # Why not `Logger`? Logger optimises for long-running processes that
+  # need rotation, formatters, custom output streams. Abqari is a build
+  # tool — output is short, lives in CI logs, and the operator wants:
+  #
+  #   - info  → user-facing progress (`Built 108 pages…`)
+  #   - debug → development triage  (`ABQARI_LOG=debug bin/build`)
+  #   - warn  → recoverable issue   (`Folio fetch failed — using cache`)
+  #   - error → fatal               (`render failed: …`)
+  #
+  # Stderr for everything except info — info goes to stdout so it can
+  # be redirected separately. Matches the established convention from
+  # most Unix build tools.
+  #
+  # No file output, no rotation, no formatters. Yagni.
+  module Log
+    LEVELS = { debug: 0, info: 1, warn: 2, error: 3 }.freeze
+    @level = (LEVELS[(ENV['ABQARI_LOG'] || 'info').to_sym] || LEVELS[:info])
+    @mutex = Mutex.new
+    class << self
+      attr_accessor :level
+      def level_name
+        LEVELS.key(@level) || :info
+      end
+      def debug(msg) = emit(:debug, msg, $stderr)
+      def info(msg)  = emit(:info, msg, $stdout)
+      def warn(msg)  = emit(:warn, msg, $stderr)
+      def error(msg) = emit(:error, msg, $stderr)
+      private
+      def emit(severity, msg, stream)
+        return if LEVELS[severity] < @level
+        # Mutex so concurrent threads (parallel page rendering) don't
+        # interleave a single log line.
+        @mutex.synchronize { stream.puts(format_line(severity, msg)) }
+      end
+      def format_line(severity, msg)
+        # Suppress the prefix for plain `info` — that's where the
+        # existing user-facing build output lives, and operators expect
+        # `Built 108 pages` not `[info] Built 108 pages`. Other levels
+        # get a prefix so warnings/errors are scannable in CI logs.
+        return msg.to_s if severity == :info
+        "[#{severity}] #{msg}"
+      end
+    end
+  end
+end

data/lib/abqari/manifest.rb ADDED Viewed

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+require 'json'
+require 'fileutils'
+module Abqari
+  # Web App Manifest writer. Emits `_site/manifest.json` from site config.
+  # Linked from <head> via _head.html.erb. Treated as part of the build, not
+  # a static file in `public/`, so the values stay in sync with site.yml
+  # (title, theme color, etc.) without manual duplication.
+  #
+  # Override any field via `manifest:` in config/site.yml; the rest fall
+  # back to sensible defaults derived from other config keys.
+  class Manifest
+    DEFAULTS = {
+      'display'          => 'standalone',
+      'start_url'        => '/',
+      'theme_color'      => '#ffffff',
+      'background_color' => '#ffffff'
+    }.freeze
+    DEFAULT_ICONS = [
+      { 'src' => '/icon-192.png', 'sizes' => '192x192', 'type' => 'image/png' },
+      { 'src' => '/icon-512.png', 'sizes' => '512x512', 'type' => 'image/png' }
+    ].freeze
+    def initialize(site)
+      @site = site
+      @cfg = site.config['manifest'] || {}
+    end
+    def write
+      File.write(File.join(@site.output_dir, 'manifest.json'), JSON.pretty_generate(payload))
+    end
+    private
+    def payload
+      DEFAULTS.merge(
+        'name'       => @cfg['name']       || @site.config['title'],
+        'short_name' => @cfg['short_name'] || @site.config['title'],
+        'lang'       => @cfg['lang']       || @site.config['locale'] || 'en',
+        'icons'      => default_icons
+      ).merge(@cfg).reject { |_, v| v.nil? }
+    end
+    # Only advertise the default icons that actually exist in the site's
+    # public/ — otherwise the manifest points at `/icon-192.png` etc.
+    # that were never generated (no `bin/icons` run), and every install
+    # attempt / Lighthouse PWA audit 404s. A user-supplied `manifest.icons`
+    # array overrides this entirely (via the `.merge(@cfg)` above).
+    def default_icons
+      public_dir = File.join(@site.site_root, 'public')
+      present = DEFAULT_ICONS.select { |icon| File.exist?(File.join(public_dir, icon['src'].sub(%r{\A/}, ''))) }
+      present.empty? ? nil : present
+    end
+  end
+end

data/lib/abqari/minifier.rb ADDED Viewed

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+module Abqari
+  # Conservative HTML minifier. Strips comments, collapses whitespace between
+  # tags, and trims leading/trailing whitespace — but preserves the contents of
+  # <pre>, <textarea>, <script>, and <style> blocks where whitespace matters.
+  module Minifier
+    PRESERVE_TAGS = %w[pre textarea script style].freeze
+    PRESERVE_REGEX = /<(#{PRESERVE_TAGS.join('|')})\b[^>]*>.*?<\/\1>/im.freeze
+    PLACEHOLDER = "\x00ABQARI_PRESERVED_%d\x00"
+    COMMENT_REGEX = /<!--(?!\[if).*?-->/m.freeze
+    def self.minify(html)
+      preserved = []
+      protected_html = html.gsub(PRESERVE_REGEX) do |match|
+        preserved << match
+        format(PLACEHOLDER, preserved.length - 1)
+      end
+      minified = protected_html
+                 .gsub(COMMENT_REGEX, '')
+                 # Collapse inter-tag whitespace to a SINGLE space, not
+                 # nothing. `<em>a</em> <strong>b</strong>` must stay
+                 # "a b" — deleting the space renders "ab". The size win
+                 # from collapsing runs is nearly identical; only the
+                 # word-joining bug is avoided. (This runs after <pre>/
+                 # <textarea>/<script>/<style> are stashed, so
+                 # significant whitespace inside them is untouched.)
+                 .gsub(/>\s+</, '> <')
+                 .gsub(/\s{2,}/, ' ')
+                 .strip
+      minified.gsub(/\x00ABQARI_PRESERVED_(\d+)\x00/) do
+        preserved[::Regexp.last_match(1).to_i]
+      end
+    end
+    # Comments and quoted strings are recognised in ONE left-to-right
+    # pass, via ordered alternation, so whichever construct STARTS first
+    # consumes the other. Handling them in two passes is wrong in both
+    # directions:
+    #
+    #   - Strings first: a bare `'` is a string delimiter, and English
+    #     prose in comments is full of apostrophes ("the theme's tokens").
+    #     Two comments each carrying one apostrophe get paired into a
+    #     single "string" spanning both — and every rule between them,
+    #     plus the `*/` that should have closed the first comment, is
+    #     swallowed and then deleted by the comment pass. This silently
+    #     ate the whole `:root` token block out of every bundled theme,
+    #     in production builds only (dev doesn't minify), which is the
+    #     worst possible place for it to hide.
+    #
+    #   - Comments first: `content: "/* not a comment */"` is a legal
+    #     string value and must survive verbatim.
+    CSS_TOKEN_REGEX = %r{
+      (?<comment>/\*.*?\*/)
+      |
+      (?<string>"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')
+    }mx.freeze
+    # Conservative CSS minifier. Strips comments and collapses
+    # whitespace; quoted strings are stashed so `content: "a  b"`
+    # survives intact. Two deliberate omissions: no tightening around
+    # `:` (removing the space in `.nav :hover` would turn a descendant
+    # selector into a compound one) and runs collapse to a single space
+    # rather than nothing (`calc(100% - 2rem)` needs its spaces).
+    def self.css(css)
+      preserved = []
+      stripped = css.gsub(CSS_TOKEN_REGEX) do
+        match = ::Regexp.last_match
+        if match[:comment]
+          ''
+        else
+          preserved << match[:string]
+          format(PLACEHOLDER, preserved.length - 1)
+        end
+      end
+      minified = stripped
+                 .gsub(/\s+/, ' ')
+                 .gsub(/\s*([{};,>])\s*/, '\1')
+                 .gsub(';}', '}')
+                 .strip
+      minified.gsub(/\x00ABQARI_PRESERVED_(\d+)\x00/) do
+        preserved[::Regexp.last_match(1).to_i]
+      end
+    end
+    JS_LINE_COMMENT_REGEX  = %r{^[ \t]*//.*$}.freeze
+    JS_BLOCK_COMMENT_REGEX = %r{^[ \t]*/\*.*?\*/[ \t]*$}m.freeze
+    # Ultra-conservative JS comment stripper. Template literals can
+    # legally contain a line-start `//`, so any file using backticks is
+    # returned untouched. For the rest, only WHOLE-LINE comments are
+    # dropped — a trailing `// note` after code stays, because telling
+    # it apart from `"https://…"` inside a string needs real parsing.
+    def self.js(js)
+      return js if js.include?('`')
+      js.gsub(JS_BLOCK_COMMENT_REGEX, '')
+        .gsub(JS_LINE_COMMENT_REGEX, '')
+        .gsub(/\n{3,}/, "\n\n")
+        .sub(/\A\n+/, '')
+    end
+  end
+end

data/lib/abqari/og_image_generator.rb ADDED Viewed

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+require 'cgi'
+require 'fileutils'
+module Abqari
+  # Auto-generated OG share images. When `og_images.auto: true` in
+  # config/site.yml, the build emits a styled SVG card per content
+  # page at `<page-url>og.svg` — so a post at `/posts/hello/` gets
+  # `/posts/hello/og.svg`. The head template's share_image
+  # resolution chain falls through to this URL when no explicit
+  # `share_image:` or `image:` is set on the page.
+  #
+  # Output is SVG, not PNG. Modern social platforms (Facebook,
+  # LinkedIn, Mastodon, Discord, Slack) render SVG og:image fine
+  # in 2026; Twitter/X can be finicky, but its share cards have
+  # been generally improving on this front. Users that need PNG
+  # for max compatibility can convert via vips/magick — or supply
+  # their own hero, which always takes precedence.
+  #
+  # Card layout:
+  #   1200×630 (standard OG dimensions, ~1.91:1 aspect)
+  #   theme-coloured gradient background (from config/site.yml's
+  #     manifest.theme_color — falls back to a tasteful default)
+  #   site title (small, top-left)
+  #   page title (large, centred, wrapped at ~22 chars)
+  #   author + date (small, bottom-left)
+  #
+  # Why SVG instead of pre-rendered PNG? Three reasons:
+  #   - Zero external dependencies (vips/magick not required)
+  #   - Tiny output (~1-2 KB per page vs. 30-80 KB PNG)
+  #   - Themed via existing site colors — no separate design system
+  class OgImageGenerator
+    OG_WIDTH  = 1200
+    OG_HEIGHT = 630
+    # Approximate character widths at the chosen font size, used for
+    # naive word-wrapping. Sans-serif at 72px renders ~22 chars per
+    # line within the safe content area; lower for narrow lines.
+    TITLE_CHARS_PER_LINE = 22
+    TITLE_MAX_LINES      = 4
+    def initialize(site)
+      @site = site
+    end
+    def enabled?
+      @site.config.dig('og_images', 'auto') == true
+    end
+    # Single source of truth for "does this page get an auto card?".
+    # The head partial calls this before emitting the `<page-url>og.svg`
+    # og:image URL, and `write` below calls it before generating the
+    # file — sharing the predicate is what keeps the two from drifting
+    # (drift means pages advertising og:image files that 404).
+    #
+    # Only real content Pages qualify. Generated pages (TaxonomyPage,
+    # PaginatedShard, RelatedIndexPage, PublisherShowPage) don't carry
+    # their own titles the same way and mostly shouldn't be SHARED
+    # directly; flat-file URLs (`/404.html`) can't host a sibling
+    # og.svg because their path isn't a directory. Pages opt out with
+    # `og_image: false`, and a page with its own `share_image:` or
+    # `image:` hero doesn't need a card (the hero IS the share image).
+    def self.auto_card?(page)
+      return false unless page.is_a?(Abqari::Page)
+      return false unless page.url.to_s.end_with?('/')
+      return false if page.title.to_s.empty?
+      fm = page.frontmatter
+      return false if fm['og_image'] == false
+      return false unless fm['share_image'].to_s.empty?
+      return false unless fm['image'].to_s.empty?
+      true
+    end
+    def write
+      return unless enabled?
+      Array(@site.pages).each do |page|
+        next unless self.class.auto_card?(page)
+        svg = render_svg(page)
+        write_file(page, svg)
+      end
+    end
+    private
+    def render_svg(page)
+      title    = page.title.to_s
+      site_t   = @site.config['title'].to_s
+      author   = page.frontmatter['author'] || @site.config['author']
+      date_str = if page.respond_to?(:date) && page.date
+                   page.date.strftime('%-d %B %Y')
+                 end
+      meta_parts = [author, date_str].compact.reject(&:empty?)
+      bg_a, bg_b = gradient_colors
+      lines = wrap_title(title)
+      title_y_start = title_block_y(lines.size)
+      title_tspans = lines.each_with_index.map do |line, i|
+        y = title_y_start + (i * 88)
+        %(<text x="80" y="#{y}" fill="#ffffff" font-size="72" font-weight="700" letter-spacing="-2">#{escape(line)}</text>)
+      end.join("\n  ")
+      <<~SVG
+        <?xml version="1.0" encoding="UTF-8"?>
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 #{OG_WIDTH} #{OG_HEIGHT}" width="#{OG_WIDTH}" height="#{OG_HEIGHT}" role="img" aria-label="#{escape(title)}">
+          <defs>
+            <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+              <stop offset="0" stop-color="#{bg_a}"/>
+              <stop offset="1" stop-color="#{bg_b}"/>
+            </linearGradient>
+          </defs>
+          <rect width="#{OG_WIDTH}" height="#{OG_HEIGHT}" fill="url(#bg)"/>
+          #{brand_mark}
+          <text x="80" y="100" fill="#ffffff" font-size="28" font-weight="600" opacity="0.85" font-family="ui-sans-serif, system-ui, sans-serif">#{escape(site_t)}</text>
+          <g font-family="ui-sans-serif, system-ui, sans-serif">
+          #{title_tspans}
+          </g>
+          #{meta_block(meta_parts)}
+        </svg>
+      SVG
+    end
+    # Faint rub el hizb (۞) in the top-right corner — the eight-pointed
+    # star Arabic manuscripts use to divide and structure text, and
+    # Abqari's mark. One even-odd path: the star outline (two
+    # overlapping squares, outer radius 106) plus a knocked-out centre
+    # circle, so the gradient shows through the hole without masks.
+    def brand_mark
+      star = 'M106,0 L75,31 L75,75 L31,75 L0,106 L-31,75 L-75,75 L-75,31 ' \
+             'L-106,0 L-75,-31 L-75,-75 L-31,-75 L0,-106 L31,-75 L75,-75 L75,-31 Z ' \
+             'M27,0 A27,27 0 1,0 -27,0 A27,27 0 1,0 27,0 Z'
+      %(<path d="#{star}" fill="#ffffff" opacity="0.12" fill-rule="evenodd" transform="translate(1090 110) scale(0.75)"/>)
+    end
+    def meta_block(parts)
+      return '' if parts.empty?
+      %(<text x="80" y="#{OG_HEIGHT - 60}" fill="#ffffff" font-size="26" opacity="0.8" font-family="ui-sans-serif, system-ui, sans-serif">#{escape(parts.join('  ·  '))}</text>)
+    end
+    def title_block_y(line_count)
+      # Centre the title block vertically in the lower-middle of the
+      # card. Single line lands a touch above centre; multi-line
+      # blocks grow downward from the same starting Y.
+      base = OG_HEIGHT / 2 - (line_count - 1) * 44
+      base.clamp(200, OG_HEIGHT - 200)
+    end
+    def wrap_title(text)
+      words = text.split(/\s+/)
+      lines = []
+      current = []
+      words.each do |w|
+        candidate = (current + [w]).join(' ')
+        if candidate.length > TITLE_CHARS_PER_LINE && !current.empty?
+          lines << current.join(' ')
+          current = [w]
+        else
+          current << w
+        end
+      end
+      lines << current.join(' ') unless current.empty?
+      lines = lines.first(TITLE_MAX_LINES)
+      # If we truncated, append an ellipsis to the last line.
+      lines[-1] = "#{lines[-1]}…" if text != lines.join(' ') && lines.any?
+      lines
+    end
+    # One stable on-brand gradient per shipped theme — accent shade
+    # into that theme's dark ground, dark enough for the card's white
+    # text. Unlike the cover tiles (slug-hashed for variety), share
+    # cards want a single recognisable look. Themes not listed
+    # (minimal, custom, bootstrap, none) use the neutral slate pair.
+    THEME_GRADIENTS = {
+      'magazine' => %w[#8a4a2a #3a2a1e],  # rust → deep umber
+      'notebook' => %w[#8a5c14 #2a2b2e],  # ochre → graphite
+      'sand'     => %w[#7a2018 #1b1a12]   # brick → olive-charcoal
+    }.freeze
+    def gradient_colors
+      # An explicit `manifest.theme_color` is a deliberate brand choice
+      # and always wins; otherwise derive from the active theme so the
+      # cards match the site the link opens into.
+      raw = @site.config.dig('manifest', 'theme_color').to_s
+      return [raw, darken(raw, 0.35)] if raw.match?(/\A#[0-9a-fA-F]{6}\z/)
+      THEME_GRADIENTS.fetch(@site.config['theme'].to_s,
+                            %w[#1f2937 #0f172a])  # slate-800 → slate-900
+    end
+    def darken(hex, factor)
+      r = hex[1, 2].to_i(16)
+      g = hex[3, 2].to_i(16)
+      b = hex[5, 2].to_i(16)
+      r = (r * (1 - factor)).round.clamp(0, 255)
+      g = (g * (1 - factor)).round.clamp(0, 255)
+      b = (b * (1 - factor)).round.clamp(0, 255)
+      format('#%02x%02x%02x', r, g, b)
+    end
+    def escape(s)
+      CGI.escapeHTML(s.to_s)
+    end
+    def write_file(page, svg)
+      # Page URL is something like `/posts/hello-from-the-blog/`.
+      # Map to a directory under output_dir and write `og.svg`.
+      #
+      # Routed through PathSafe so a hostile `page.url` (it ultimately
+      # derives from frontmatter `permalink:`) can't write outside
+      # output_dir. PathSafe.join_under raises if it would.
+      dir_part   = page.url.sub(%r{\A/}, '').sub(%r{/\z}, '')
+      target_dir = PathSafe.join_under(@site.output_dir, dir_part)
+      target     = PathSafe.join_under(target_dir, 'og.svg')
+      FileUtils.mkdir_p(target_dir)
+      File.write(target, svg)
+    end
+  end
+end

data/lib/abqari/page/bundle.rb ADDED Viewed

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+require 'uri' # URI::DEFAULT_PARSER — percent-encoding bundle filenames
+module Abqari
+  class Page
+    # Bundle-asset discovery. A "bundle" is a directory containing
+    # `index.md` plus colocated assets (hero image, body figures, AVIF/
+    # WebP variants, etc.). Bundles are the default layout for posts
+    # and photos; flat collections (publications, workshops) use a
+    # single `.md` file with assets in the collection root.
+    #
+    # External symlinks (real path escapes `site_root`) are filtered
+    # via `Site#external_symlink?` so a hostile or accidental link
+    # can't pull external files into the build.
+    module Bundle
+      IMAGE_EXTENSIONS = %w[.jpg .jpeg .png .gif .webp .avif .svg].freeze
+      # Extensions published from a bundle directory. An ALLOW-list, not
+      # a deny-list, and that direction is the whole point.
+      #
+      # This used to publish everything that wasn't a directory, dotfile
+      # or `index.md`. That shipped whatever an author happened to leave
+      # in the folder — including a `notes.md` marked `published: false`,
+      # which went to production verbatim, frontmatter and all, at a
+      # guessable URL. `published: false` has to be a promise; a rule
+      # that publishes the file anyway makes the flag lie.
+      #
+      # Excluding `.md` alone would fix that case and leave the class:
+      # the next `.psd`, `.sketch`, `.docx` or `working-notes.rtf` would
+      # ship the same way. A deny-list has to be extended forever and
+      # fails open on everything nobody thought of; an allow-list fails
+      # closed.
+      #
+      # Generous on purpose, and extensible — `bundle_assets.extensions:`
+      # in site.yml adds to this list, so a site publishing `.gpx` or
+      # `.stl` isn't stuck. Skipped files are WARNED about, never
+      # silently dropped: silent omission is the failure mode this is
+      # meant to end, and swapping one silence for another would miss
+      # the point.
+      #
+      # Note `.md` is absent deliberately — markdown is content, never an
+      # asset. `BundleAssets#copy_flat_collection_assets` has always
+      # taken that line for flat collections; bundles simply never did,
+      # and the inconsistency is what let the leak through.
+      PUBLISHABLE_EXTENSIONS = %w[
+        .jpg .jpeg .png .gif .webp .avif .svg .ico
+        .mp4 .webm .mov .m4v
+        .mp3 .m4a .oga .ogg .opus .wav .flac
+        .vtt .srt
+        .pdf .epub .zip
+      ].freeze
+      # Content, never assets — not publishable via `bundle_assets.extensions:`
+      # either. Allowing markdown back in would republish exactly the
+      # `published: false` sibling the allow-list exists to hold back, so
+      # `Site#bundle_asset_extensions` filters these out of user config
+      # rather than trusting nobody will try.
+      CONTENT_EXTENSIONS = %w[.md .markdown].freeze
+      # Filesystem directory containing this page's bundle, or nil for
+      # flat-collection pages and top-level pages (no bundle).
+      def bundle_dir
+        return nil unless collection
+        cfg = site.collections[collection]
+        cfg['bundle'] != false ? File.dirname(source_path) : nil
+      end
+      # Files in the bundle dir that are published alongside the page —
+      # those whose extension is in the site's publishable set.
+      def bundle_assets
+        bundle_entries.select { |entry| publishable_bundle_file?(entry) }
+      end
+      # The complement: bundle files that will NOT be published. The
+      # caller (`BundleAssets#copy_bundle_assets`) warns about these once
+      # per build so an author can see what was left behind and either
+      # allow the extension or move the file out.
+      def unpublishable_bundle_files
+        bundle_entries.reject { |entry| publishable_bundle_file?(entry) }
+      end
+      # Candidate files in the bundle dir, before the extension filter.
+      # Skips directories, the index.md itself, dotfiles, and any symlink
+      # that escapes `site_root`.
+      #
+      # Dotfiles are the deliberate escape hatch for genuinely private
+      # working files: `Dir.glob` skips them without `FNM_DOTMATCH`, so
+      # a `.notes.md` is neither published as an asset nor loaded as a
+      # page. That's what the skip warning points authors at.
+      def bundle_entries
+        return [] unless bundle_dir
+        # Sort for deterministic iteration order — without it, sitemap
+        # image entries can shuffle between builds on the same machine
+        # when the filesystem reorders inodes. Same content, different
+        # bytes-on-disk → noisy diffs on every deploy.
+        Dir.glob(File.join(bundle_dir, '*')).sort.reject do |entry|
+          File.directory?(entry) ||
+            File.basename(entry) == 'index.md' ||
+            File.basename(entry).start_with?('.') ||
+            site.external_symlink?(entry)
+        end
+      end
+      def publishable_bundle_file?(path)
+        site.bundle_asset_extensions.include?(File.extname(path).downcase)
+      end
+      # URL paths (not filesystem paths) for every image the sitemap
+      # should advertise as belonging to this page. Two sources:
+      #
+      #   1. Files in the bundle dir matching IMAGE_EXTENSIONS — the
+      #      common case (colocated hero + body figures). Converted
+      #      from filesystem path to URL path: `<page.url><basename>`.
+      #   2. Frontmatter `image:` / `cover:` / `cover_image:` values
+      #      that point at absolute same-origin paths (e.g.
+      #      `/assets/hero.jpg`). Bundle-relative values are skipped
+      #      because they're already covered by source #1 above.
+      #      External URLs (http/https) aren't claimed.
+      #
+      # Inline body images aren't extracted — parsing markdown is
+      # expensive and the image sitemap is meant for primary content,
+      # not embedded illustrations.
+      def bundle_images
+        results = []
+        bundle_assets.each do |path|
+          next unless IMAGE_EXTENSIONS.include?(File.extname(path).downcase)
+          # Percent-encode the basename: it comes off the filesystem, so
+          # it can contain spaces or non-ASCII, and a sitemap
+          # `<image:loc>` with a literal space is invalid (XML-escaping
+          # doesn't help — that's a different layer). Only the
+          # filesystem-derived part is encoded; frontmatter values below
+          # are author-written URLs and may already be encoded, so
+          # touching them risks double-encoding.
+          results << "#{url}#{URI::DEFAULT_PARSER.escape(File.basename(path))}"
+        end
+        %w[image cover cover_image].each do |key|
+          raw = frontmatter[key].to_s
+          next if raw.empty?
+          next if raw.start_with?('http://', 'https://')
+          next unless raw.start_with?('/')
+          results << raw unless results.include?(raw)
+        end
+        results
+      end
+    end
+  end
+end

data/lib/abqari/page/incremental.rb ADDED Viewed

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+module Abqari
+  class Page
+    # Incremental-render heuristics + memory management.
+    #
+    # `needs_render?` decides whether a page can be skipped during an
+    # incremental rebuild by comparing the output file's mtime against
+    # every input that affects its render. `lastmod` exposes the same
+    # signals to the sitemap so search engines know when to recrawl.
+    # `forget_body!` releases the in-memory body after a page's own
+    # render completes, bounding the engine's memory footprint.
+    module Incremental
+      # Most recent of: publication date, source file mtime, and (for
+      # bundles) any colocated asset mtime. Used by the sitemap so
+      # search engines re-crawl when content or its assets change.
+      def lastmod
+        candidates = [File.mtime(source_path), date]
+        candidates.concat(bundle_assets.map { |a| File.mtime(a) })
+        candidates.compact.max
+      end
+      # Skip the render when the output is already up to date.
+      # Considers:
+      #
+      #   - source file mtime (`source_path`)
+      #   - bundle-asset mtimes (for posts)
+      #   - site-wide "global" deps mtime (partials, helpers, config,
+      #     themes, icons, assets, data) — any change invalidates every
+      #     page
+      #   - layout-chain deps mtime (`layouts/<name>.html.erb` and every
+      #     ancestor `layout:` extends) — invalidates only pages using
+      #     that chain. Editing `layouts/post.html.erb` no longer
+      #     invalidates photo/publication/workshop pages.
+      #
+      # Always returns true when output is missing or in non-
+      # incremental mode (Site#build wipes _site/ first, so output
+      # never exists).
+      def needs_render?
+        return true unless File.exist?(output_path)
+        output_mtime = File.mtime(output_path)
+        return true if File.mtime(source_path) > output_mtime
+        # Gated on having a bundle, not on being a post. Photos are
+        # bundle-style too, so `post?` meant a photo page went stale
+        # whenever only its colocated image changed — while `lastmod`
+        # (which does include bundle assets) still advertised the page
+        # as updated in the sitemap. Any bundle-style collection a user
+        # defines had the same gap.
+        return true if bundle_dir && bundle_assets.any? { |a| File.mtime(a) > output_mtime }
+        return true if site.shared_deps_mtime > output_mtime
+        return true if site.layout_deps_mtime(layout_name) > output_mtime
+        false
+      end
+      # Release the in-memory body + rendered content after this page
+      # has been written to disk. Frontmatter stays — it's small and
+      # accessed everywhere (taxonomy, sitemap, feed, related lookups).
+      # Body is large (~10 KB per page typically) and only needed
+      # during the page's own render; at 10k pages × 10 KB that's
+      # ~100 MB of otherwise-retained memory.
+      #
+      # If a later request re-reads body (e.g. a posts-index page
+      # rendering after this post and pulling its first-paragraph
+      # description), `#body` lazily loads from disk. OS page cache
+      # makes the re-read sub-millisecond.
+      def forget_body!
+        @body = nil
+        @content = nil
+      end
+    end
+  end
+end