jekyll-fingerprint-flow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 99741c6430da05235dd51944c3e977522e1b0e9c61a4be73c77598ebf9e15007
+  data.tar.gz: ea62ad37859d5412030b1498435f32131e6a694f0f4eb478860f06150f0a9928
+SHA512:
+  metadata.gz: d1fe48c5fec220446853fe54aebbdabea227ae975043b8ce6ac228513d550c695dd2258b569e8492bf349e12ea208f6e6aecb1058af93bb6a9471bf9773fd35b
+  data.tar.gz: 370926dbd79d93edabe1a9e776526dda449a98ea0c83533ec322926e04ebe45670f6a3e1fea53ec1bea6ed65eb42c586f7262ed937e3f8f99c494003c21eda9d

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-06
+
+- `Jekyll::FingerprintFlow::Interface.to_h` — the config surface
+  (`fingerprint_flow` keys plus the `priority:` range) derived from
+  `DEFAULTS` and the code's actual `site.config` reads, serialized to a
+  committed `interface.yml` by `rake interface`;
+  `spec/interface_spec.rb` pins manifest freshness and completeness.
+
+- Per-site `:site, :post_write` dispatcher that content-tags supported local
+  asset URLs after normal-priority processing and before compression (default
+  priority 12; configurable from 11 through 19).
+- Source-preserving HTML tag/attribute scanning for `.html` and `.htm` output;
+  rewrites exact `src`, `href`, `xlink:href`, `srcset`, and `poster` attributes,
+  not comments, script/style text, or unrelated `data-*` attributes.
+- `srcset` parsing preserves data URLs, candidate descriptors, and unchanged
+  formatting; handles local candidates individually.
+- `?v=<md5(content)[0,10]>` tags are derived from bytes and memoized only for
+  the current build; no persistent stat-keyed cache can return an old digest.
+- Resolves local `<base href>` values, honors `baseurl`, rejects targets
+  outside `_site` (including traversal and symlinks), and skips symlinked HTML
+  outputs so builds cannot write through them.
+- Skips external/scheme URLs, non-allowlisted paths, missing targets, and
+  pages with invalid base-href encoding; replaces existing `?v=` params and
+  preserves other query params and fragments.
+- Config: `fingerprint_flow.enabled` (default true),
+  `fingerprint_flow.priority` (default 12, integer 11–19),
+  `fingerprint_flow.extensions` (extend the allowlist), and
+  `fingerprint_flow.exclude` (URL path prefixes never rewritten).
+- Writes each HTML file only when an attribute URL actually changes.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 Svend Gundestrup
+
+This project is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This project is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+details.
+
+You should have received a copy of the GNU Affero General Public License along
+with this project. If not, see <https://www.gnu.org/licenses/agpl-3.0.html>.
+
+The complete license text is available from the Free Software Foundation at:
+https://www.gnu.org/licenses/agpl-3.0.txt
+
+SPDX-License-Identifier: AGPL-3.0-or-later

data/README.md

@@ -0,0 +1,159 @@
+# jekyll-fingerprint-flow
+
+[![Status: Active](https://img.shields.io/badge/status-active-success)](https://github.com/gundestrup/jekyll-fingerprint-flow)
+[![CI](https://github.com/gundestrup/jekyll-fingerprint-flow/actions/workflows/ci.yml/badge.svg)](https://github.com/gundestrup/jekyll-fingerprint-flow/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/jekyll-fingerprint-flow)](https://rubygems.org/gems/jekyll-fingerprint-flow)
+[![Codecov](https://codecov.io/gh/gundestrup/jekyll-fingerprint-flow/graph/badge.svg)](https://codecov.io/gh/gundestrup/jekyll-fingerprint-flow)
+[![Ruby](https://img.shields.io/badge/ruby-%E2%89%A5%203.3-red.svg)](https://www.ruby-lang.org/)
+[![Jekyll](https://img.shields.io/badge/jekyll-4.x-blue.svg)](https://jekyllrb.com/)
+[![Release](https://img.shields.io/github/v/tag/gundestrup/jekyll-fingerprint-flow)](https://github.com/gundestrup/jekyll-fingerprint-flow/tags)
+[![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE.txt)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/gundestrup/jekyll-fingerprint-flow)
+[![CodeFactor](https://www.codefactor.io/repository/github/gundestrup/jekyll-fingerprint-flow/badge)](https://www.codefactor.io/repository/github/gundestrup/jekyll-fingerprint-flow)
+[![Semgrep CE](https://img.shields.io/badge/Semgrep_CE-security-success)](https://github.com/gundestrup/jekyll-fingerprint-flow/security/code-scanning)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=gundestrup_jekyll-fingerprint-flow&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=gundestrup_jekyll-fingerprint-flow)
+
+Drop-in content-hash cache busting for Jekyll. After the site is written,
+matching local asset URLs in supported attributes of generated `.html`
+and `.htm` files receive a content-derived `?v=<md5>` tag:
+
+```html
+<link rel="stylesheet" href="/assets/site.css">
+<!-- becomes -->
+<link rel="stylesheet" href="/assets/site.css?v=3f8a1c2e94">
+```
+
+No template changes or asset-pipeline tags are needed. The post-write pass
+covers matching URLs emitted by layouts, themes, and other plugins, without
+mistaking comments, script text, or unrelated `data-*` attributes for markup.
+
+## Why
+
+Browsers cache static assets aggressively. When a site serves assets with a
+long `Cache-Control: max-age`, a new deploy can update the HTML while visitors
+keep stale CSS or JavaScript referenced directly by that HTML. Changing the
+URL invalidates the browser cache entry, and a **content hash** changes the
+URL exactly when the referenced file's bytes change:
+
+- same bytes → same URL → browser cache entry remains valid
+- different bytes → new URL → browser fetches the new resource
+
+The digest is deterministic across machines and builds; there is no persistent
+version counter or manifest state to synchronize.
+
+Query-param tagging (`?v=`) was chosen over renamed files
+(`site-<hash>.css`) deliberately: filenames stay stable, so precompressed
+siblings (`.br`, `.zst`, `.gz`) and direct document links keep working. The
+post-write order is normal processing (20), fingerprinting (12), then
+compression (10), so compressors see the rewritten HTML.
+
+## Install
+
+```ruby
+# Gemfile
+group :jekyll_plugins do
+  gem "jekyll-fingerprint-flow"
+end
+```
+
+That's it — the next `jekyll build` fingerprints matching references.
+
+## What gets tagged
+
+The plugin scans real start-tag attributes in generated `.html` and `.htm`
+files. It edits only the attribute value spans; it does not serialize the
+whole document.
+
+| Attribute | Example |
+| ----------- | --------- |
+| `src` | `<script>`, `<img>`, `<video>`, `<source>`, `<iframe>` |
+| `href` | `<link>` and direct links to downloadable files |
+| `xlink:href` | legacy SVG links |
+| `srcset` | responsive image candidates (descriptors preserved) |
+| `poster` | `<video>` poster frames |
+
+A URL is tagged only when **all** of these hold:
+
+- it is local (no scheme, no `//`, not `data:`/`mailto:`/…)
+- its extension is in the allowlist (`css js mjs map json xml webmanifest
+  png jpg jpeg gif webp avif svg ico woff woff2 ttf otf eot mp4 webm mp3
+  wav ogg pdf txt`)
+- its target resolves to a real file within `_site` (root-relative paths honor
+  `baseurl`; relative paths honor a local `<base href>` when present, otherwise
+  resolve from the generated document's directory)
+
+Comments, raw-text elements (`script`, `style`, `textarea`, and similar), and
+non-target attributes such as `data-src` are not scanned. External `<base`
+URLs are left untouched along with that page's local-looking references,
+since the browser would resolve them against the external origin.
+
+`srcset` candidates are parsed separately so commas inside data URLs are not
+treated as candidate separators. Candidates that cannot be tagged stay byte-
+for-byte as supplied; the attribute is rewritten only if at least one URL
+changes.
+
+Existing query strings are preserved — a `?v=` already present is replaced
+(not stacked), other parameters are retained, and `#fragments` survive. HTML
+entities in attribute values are decoded for URL processing and escaped again
+when written.
+
+### Scope boundary
+
+This is a post-write HTML attribute rewriter, not a general parser for every
+resource-bearing language. It does **not** rewrite CSS `url()` / `@import`,
+inline CSS, JavaScript `fetch()`/dynamic imports, references in JSON/XML, or
+other non-HTML output. Such references need format-specific processing; the
+plugin intentionally does not guess by rewriting arbitrary strings in source
+text.
+
+## Config
+
+All optional — defaults are zero-config:
+
+```yaml
+# _config.yml
+fingerprint_flow:
+  enabled: true              # set false to disable the pass entirely
+  priority: 12               # integer 11..19; default 12
+  extensions: [.gpx, .bin]   # extra extensions to fingerprint
+  exclude:                   # URL path prefixes never rewritten
+    - "/internal/"
+```
+
+`priority` is a site-configurable integer from 11 through 19 (default 12). A
+dispatcher registers at each allowed slot and only the one selected by this
+site's config rewrites output. Normal-priority work (20) runs first, then
+fingerprinting, then compression (0–10).
+
+## Behaviour notes
+
+- **Content-derived tag.** The value is `md5(file content)[0,10]`, a pure
+  function of the output bytes.
+- **Build-local memoization.** Each unique resolved file is hashed once per
+  build. The memo is not persisted, so preserved mtimes or same-size edits
+  cannot make a later build reuse a stale digest.
+- **Destination confinement.** Resolved files and symlink targets must remain
+  under `_site`; path traversal and external symlinks are skipped. Symlinked
+  HTML pages are not rewritten.
+- **No mtime churn.** HTML files are written back only when a URL changes, so
+  rsync-based deploys do not re-upload untouched pages.
+- **HTTP policy is separate.** The plugin changes URLs; it does not set
+  `Cache-Control`. The web server still controls freshness. Long-lived browser
+  caching is safe when caches key entries by the full URL, including `?v=`.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake quick   # rubocop + rspec
+bundle exec rake ci      # + bundler-audit, semgrep, package check
+```
+
+Release: `bundle exec rake "version:bump[patch]"`, add a dated CHANGELOG
+entry, commit, `git tag vX.Y.Z && git push --tags` — the release workflow
+verifies the tag, builds the gem, attaches it to a GitHub release, and
+publishes to RubyGems via OIDC trusted publishing.
+
+## License
+
+AGPL-3.0-or-later — see [LICENSE.txt](LICENSE.txt).

data/interface.yml

@@ -0,0 +1,14 @@
+# Generated by `rake interface` — do not edit.
+# Public tag/config surface for tooling (editor extensions, doc linters).
+---
+gem: jekyll-fingerprint-flow
+version: 0.1.0
+tags: {}
+filters: []
+config:
+  fingerprint_flow:
+  - enabled
+  - exclude
+  - extensions
+  - priority
+enums: {}

data/lib/jekyll/fingerprint_flow/configuration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module FingerprintFlow
+    # Reads the `fingerprint_flow:` section of _config.yml.
+    #
+    #   fingerprint_flow:
+    #     enabled: true            # default
+    #     extensions: [foo]        # extra extensions to fingerprint
+    #     exclude: ["/internal/"]  # URL path prefixes never rewritten
+    #     priority: 12             # integer 11..19; between normal processing and compression
+    class Configuration
+      DEFAULT_POST_WRITE_PRIORITY = 12
+      POST_WRITE_PRIORITIES = (11..19)
+      DEFAULT_EXTENSIONS = %w[
+        css js mjs map json xml webmanifest
+        png jpg jpeg gif webp avif svg ico
+        woff woff2 ttf otf eot
+        mp4 webm mp3 wav ogg pdf txt
+      ].freeze
+
+      attr_reader :extensions, :exclude, :post_write_priority
+
+      def self.post_write_priority(site)
+        config = site.config["fingerprint_flow"] || {}
+        priority = config.fetch("priority", DEFAULT_POST_WRITE_PRIORITY)
+        return priority if priority.is_a?(Integer) && POST_WRITE_PRIORITIES.cover?(priority)
+
+        raise Jekyll::Errors::FatalException,
+              "FingerprintFlow: fingerprint_flow.priority must be an integer from 11 through 19"
+      end
+
+      def initialize(site)
+        cfg = site.config["fingerprint_flow"] || {}
+        @enabled = cfg.fetch("enabled", true)
+        @post_write_priority = self.class.post_write_priority(site)
+        configure_asset_options(cfg)
+      end
+
+      def enabled?
+        @enabled
+      end
+
+      private
+
+      def configure_asset_options(config)
+        extra = Array(config["extensions"]).map do |extension|
+          extension.to_s.downcase.delete_prefix(".")
+        end
+        @extensions = (DEFAULT_EXTENSIONS | extra).freeze
+        @exclude = Array(config["exclude"]).map(&:to_s)
+      end
+    end
+  end
+end

data/lib/jekyll/fingerprint_flow/hasher.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Jekyll
+  module FingerprintFlow
+    # Content-hash tags for files under _site. The tag is a pure function of
+    # file content — same bytes, same tag, on any machine, in any
+    # environment. Each output file is hashed once per build.
+    class Hasher
+      DIGEST_LENGTH = 10
+
+      def initialize
+        @memo = {}
+      end
+
+      def tag(path)
+        @memo[path] ||= Digest::MD5.file(path).hexdigest[0, DIGEST_LENGTH]
+      end
+    end
+  end
+end

data/lib/jekyll/fingerprint_flow/html_document_rewriter.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Jekyll
+  module FingerprintFlow
+    class HtmlDocumentRewriter
+      URL_ATTRIBUTES = %w[src href srcset poster xlink:href].freeze
+      INVALID_BASE_HREF = :invalid_base_href
+
+      attr_reader :tagged, :skipped
+
+      def initialize(tagger, scanner: HtmlTagScanner.new)
+        @tagger = tagger
+        @scanner = scanner
+        @tagged = 0
+        @skipped = 0
+        @srcset_rewriter = SrcsetRewriter.new(@tagger) { |value| counted(value) }
+      end
+
+      def rewrite(source, path)
+        base_href = first_base_href(source)
+        return invalid_base(path) if base_href == INVALID_BASE_HREF
+
+        apply_changes(source, attribute_changes(source, path, base_href))
+      end
+
+      private
+
+      def first_base_href(source)
+        @scanner.each_tag(source) do |name, attributes|
+          next unless name == "base"
+
+          attribute = attributes.find { |item| item.name == "href" }
+          next unless attribute
+
+          value = decode_attribute(attribute_value(source, attribute))
+          return value || INVALID_BASE_HREF
+        end
+        nil
+      end
+
+      def attribute_changes(source, path, base_href)
+        changes = []
+        @scanner.each_tag(source) do |_name, attributes|
+          changes.concat(changes_for_attributes(source, attributes, File.dirname(path), base_href))
+        end
+        changes
+      end
+
+      def changes_for_attributes(source, attributes, html_dir, base_href)
+        attributes.filter_map do |attribute|
+          change_for_attribute(source, attribute, html_dir, base_href)
+        end
+      end
+
+      def change_for_attribute(source, attribute, html_dir, base_href)
+        return unless URL_ATTRIBUTES.include?(attribute.name)
+
+        value = decode_attribute(attribute_value(source, attribute))
+        return count_skip unless value
+
+        rewritten = rewrite_attribute(attribute, value, html_dir, base_href)
+        return unless rewritten && rewritten != value
+
+        [attribute.value_start, attribute.value_end, CGI.escapeHTML(rewritten).b]
+      end
+
+      def rewrite_attribute(attribute, value, html_dir, base_href)
+        if attribute.name == "srcset"
+          return @srcset_rewriter.rewrite(value, html_dir: html_dir, base_href: base_href)
+        end
+
+        counted(@tagger.tag(value, html_dir: html_dir, base_href: base_href))
+      end
+
+      def attribute_value(source, attribute)
+        source.byteslice(attribute.value_start, attribute.value_end - attribute.value_start)
+      end
+
+      def decode_attribute(raw)
+        value = raw.dup.force_encoding(Encoding::UTF_8)
+        CGI.unescapeHTML(value) if value.valid_encoding?
+      end
+
+      def invalid_base(path)
+        Jekyll.logger.warn("fingerprint-flow:", "skipped #{path} (invalid base href encoding)")
+        nil
+      end
+
+      def apply_changes(source, changes)
+        changes.sort_by(&:first).reverse_each do |start, finish, replacement|
+          prefix = source.byteslice(0, start)
+          suffix = source.byteslice(finish, source.bytesize - finish)
+          source = prefix + replacement + suffix
+        end
+        source
+      end
+
+      def count_skip
+        @skipped += 1
+        nil
+      end
+
+      def counted(value)
+        if value
+          @tagged += 1
+          value
+        else
+          count_skip
+        end
+      end
+    end
+  end
+end

data/lib/jekyll/fingerprint_flow/html_tag_parser.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module FingerprintFlow
+    class HtmlTagParser
+      Attribute = Struct.new(:name, :value_start, :value_end, keyword_init: true)
+      ATTRIBUTE_TERMINATORS = [34, 39, 47, 60, 61, 62].freeze
+      QUOTES = [34, 39].freeze
+      ASCII_SPACE = [9, 10, 12, 13, 32].freeze
+
+      def initialize(source, opening)
+        @source = source
+        @cursor = opening + 1
+      end
+
+      def parse
+        return unless ascii_alpha?(@source.getbyte(@cursor))
+
+        name = read_tag_name
+        attributes, ending = read_attributes
+        [name, attributes, ending]
+      end
+
+      private
+
+      def read_tag_name
+        start = @cursor
+        @cursor += 1 while tag_name_byte?(@source.getbyte(@cursor))
+        @source.byteslice(start, @cursor - start).downcase
+      end
+
+      def read_attributes
+        attributes = []
+        seen = {}
+        loop do
+          @cursor = skip_spaces(@cursor)
+          ending = tag_ending
+          return [attributes, ending] if ending
+
+          append_current_attribute(attributes, seen)
+        end
+      end
+
+      def tag_ending
+        byte = @source.getbyte(@cursor)
+        return @cursor + 1 if byte == 62
+        return @cursor + 2 if byte == 47 && @source.getbyte(@cursor + 1) == 62
+
+        @source.bytesize unless byte
+      end
+
+      def append_current_attribute(attributes, seen)
+        name = read_attribute_name
+        unless name
+          @cursor += 1
+          return
+        end
+
+        start, finish = read_attribute_value
+        return if seen[name]
+
+        attributes << Attribute.new(name: name, value_start: start, value_end: finish) if start
+        seen[name] = true
+      end
+
+      def read_attribute_name
+        start = @cursor
+        @cursor += 1 while attribute_name_byte?(@source.getbyte(@cursor))
+        return if @cursor == start
+
+        @source.byteslice(start, @cursor - start).downcase
+      end
+
+      def read_attribute_value
+        @cursor = skip_spaces(@cursor)
+        return [nil, nil] unless @source.getbyte(@cursor) == 61
+
+        @cursor = skip_spaces(@cursor + 1)
+        quote = @source.getbyte(@cursor)
+        return read_quoted_value(quote) if QUOTES.include?(quote)
+
+        read_unquoted_value
+      end
+
+      def read_quoted_value(quote)
+        start = @cursor + 1
+        ending = @source.index(quote.chr.b, start)
+        @cursor = ending ? ending + 1 : @source.bytesize
+        ending ? [start, ending] : [nil, nil]
+      end
+
+      def read_unquoted_value
+        start = @cursor
+        @cursor += 1 while (byte = @source.getbyte(@cursor)) && !space?(byte) && byte != 62
+        [start, @cursor]
+      end
+
+      def skip_spaces(position)
+        position += 1 while space?(@source.getbyte(position))
+        position
+      end
+
+      def space?(byte)
+        ASCII_SPACE.include?(byte)
+      end
+
+      def ascii_alpha?(byte)
+        return false unless byte
+
+        byte.between?(65, 90) || byte.between?(97, 122)
+      end
+
+      def tag_name_byte?(byte)
+        byte && !space?(byte) && ![47, 61, 62].include?(byte)
+      end
+
+      def attribute_name_byte?(byte)
+        byte && !space?(byte) && !ATTRIBUTE_TERMINATORS.include?(byte)
+      end
+    end
+  end
+end

data/lib/jekyll/fingerprint_flow/html_tag_scanner.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "jekyll/fingerprint_flow/html_tag_parser"
+
+module Jekyll
+  module FingerprintFlow
+    class HtmlTagScanner
+      RAW_TEXT_ELEMENTS = %w[
+        script style textarea title xmp iframe noembed noframes plaintext
+      ].freeze
+      COMMENT_OPEN = "<!--".b.freeze
+      COMMENT_CLOSE = "-->".b.freeze
+      CDATA_OPEN = "<![CDATA[".b.freeze
+
+      def each_tag(source, &block)
+        return enum_for(:each_tag, source) unless block
+
+        data = source.b
+        cursor = 0
+        while (opening = data.index("<".b, cursor))
+          cursor = skip_special(data, opening) || scan_tag(data, opening, &block)
+        end
+        self
+      end
+
+      private
+
+      def scan_tag(source, opening, &block)
+        parsed = HtmlTagParser.new(source, opening).parse
+        return opening + 1 unless parsed
+
+        name, attributes, cursor = parsed
+        block.call(name, attributes)
+        after_tag(source, name, cursor)
+      end
+
+      def after_tag(source, name, cursor)
+        return source.bytesize if name == "plaintext"
+        return raw_text_end(source, name, cursor) if RAW_TEXT_ELEMENTS.include?(name)
+
+        cursor
+      end
+
+      def skip_special(source, opening)
+        if starts_with?(source, COMMENT_OPEN, opening)
+          skip_delimited(source, opening + COMMENT_OPEN.bytesize)
+        elsif starts_with?(source, CDATA_OPEN, opening)
+          skip_cdata(source, opening + CDATA_OPEN.bytesize)
+        elsif markup_start?(source, opening)
+          skip_markup(source, opening + 2)
+        end
+      end
+
+      def markup_start?(source, opening)
+        [33, 47, 63].include?(source.getbyte(opening + 1))
+      end
+
+      def starts_with?(source, token, position)
+        source.byteslice(position, token.bytesize) == token
+      end
+
+      def skip_delimited(source, position)
+        ending = source.index(COMMENT_CLOSE, position)
+        ending ? ending + COMMENT_CLOSE.bytesize : source.bytesize
+      end
+
+      def skip_cdata(source, position)
+        while position + 2 < source.bytesize
+          return position + 3 if cdata_end?(source, position)
+
+          position += 1
+        end
+        source.bytesize
+      end
+
+      def cdata_end?(source, position)
+        source.getbyte(position) == 93 &&
+          source.getbyte(position + 1) == 93 &&
+          source.getbyte(position + 2) == 62
+      end
+
+      def skip_markup(source, position)
+        quote = nil
+        while position < source.bytesize
+          byte = source.getbyte(position)
+          return position + 1 if byte == 62 && quote.nil?
+
+          quote = next_quote(byte, quote)
+          position += 1
+        end
+        position
+      end
+
+      def next_quote(byte, quote)
+        return nil if quote && byte == quote
+        return byte if quote.nil? && [34, 39].include?(byte)
+
+        quote
+      end
+
+      def raw_text_end(source, name, position)
+        pattern = Regexp.new("</#{Regexp.escape(name)}(?=[\\x09\\x0a\\x0c\\x0d\\x20/>])".b, Regexp::IGNORECASE)
+        match = pattern.match(source, position)
+        match ? match.begin(0) : source.bytesize
+      end
+    end
+  end
+end

data/lib/jekyll/fingerprint_flow/interface.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module FingerprintFlow
+    # Machine-readable description of the plugin's public interface:
+    # config keys (this plugin registers no Liquid tags or filters).
+    # `rake interface` writes this as interface.yml (shipped in the gem) so
+    # tooling like editor extensions can consume it without parsing Ruby.
+    module Interface
+      CONFIG_KEYS = %w[enabled exclude extensions priority].freeze
+
+      def self.to_h
+        {
+          "gem" => "jekyll-fingerprint-flow",
+          "version" => VERSION,
+          "tags" => {},
+          "filters" => [],
+          "config" => { "fingerprint_flow" => CONFIG_KEYS.sort },
+          "enums" => {}
+        }
+      end
+    end
+  end
+end

data/lib/jekyll/fingerprint_flow/rewriter.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module FingerprintFlow
+    class Rewriter
+      def initialize(site, hasher: Hasher.new)
+        @config = Configuration.new(site)
+        @dest = File.expand_path(site.dest)
+        tagger = UrlTagger.new(site: site, config: @config, hasher: hasher)
+        @html_rewriter = HtmlDocumentRewriter.new(tagger)
+      end
+
+      def run
+        return unless @config.enabled?
+
+        files = Dir.glob(File.join(@dest, "**", "*.{html,htm}"))
+        changed = files.count { |file| rewrite_file(file) }
+        summary = "#{files.size} HTML files scanned, #{changed} rewritten, " \
+                  "#{@html_rewriter.tagged} refs tagged"
+        Jekyll.logger.info("fingerprint-flow:", summary)
+      end
+
+      def rewrite_file(path)
+        return unless safe_output_path?(path)
+
+        source = File.binread(path)
+        output = @html_rewriter.rewrite(source, path)
+        return unless output && output != source
+
+        File.binwrite(path, output)
+      end
+
+      private
+
+      def safe_output_path?(path)
+        return false if File.symlink?(path)
+
+        root = File.realpath(@dest)
+        real = File.realpath(path)
+        prefix = root.end_with?(File::SEPARATOR) ? root : "#{root}#{File::SEPARATOR}"
+        File.file?(real) && real.start_with?(prefix)
+      rescue SystemCallError
+        false
+      end
+    end
+  end
+end

data/lib/jekyll/fingerprint_flow/srcset_rewriter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module FingerprintFlow
+    class SrcsetRewriter
+      ASCII_SPACE = [9, 10, 12, 13, 32].freeze
+
+      def initialize(tagger, &counter)
+        @tagger = tagger
+        @counter = counter
+      end
+
+      def rewrite(value, html_dir:, base_href:)
+        changes = []
+        position = 0
+        while (candidate = next_candidate(value, position))
+          start, finish, url, position = candidate
+          tagged = @counter.call(@tagger.tag(url, html_dir: html_dir, base_href: base_href))
+          changes << [start, finish, tagged.b] if tagged && tagged != url
+        end
+        return if changes.empty?
+
+        apply_changes(value.b, changes).force_encoding(Encoding::UTF_8)
+      end
+
+      private
+
+      def next_candidate(value, position)
+        position = skip_separators(value, position)
+        return if position >= value.bytesize
+
+        start = position
+        position = skip_url(value, position)
+        finish = position
+        url = value.byteslice(start, finish - start)
+        url, finish, trailing_comma = strip_trailing_commas(url, finish)
+        position = skip_descriptors(value, position) unless trailing_comma
+        [start, finish, url, position]
+      end
+
+      def strip_trailing_commas(url, finish)
+        commas = url[/,+\z/]
+        return [url, finish, false] unless commas
+
+        [url.byteslice(0, url.bytesize - commas.bytesize), finish - commas.bytesize, true]
+      end
+
+      def skip_url(value, position)
+        position += 1 while position < value.bytesize && !space?(value.getbyte(position))
+        position
+      end
+
+      def skip_descriptors(value, position)
+        position = skip_spaces(value, position)
+        depth = 0
+        while position < value.bytesize
+          byte = value.getbyte(position)
+          return position + 1 if byte == 44 && depth.zero?
+
+          depth += 1 if byte == 40
+          depth -= 1 if byte == 41 && depth.positive?
+          position += 1
+        end
+        position
+      end
+
+      def skip_separators(value, position)
+        while position < value.bytesize
+          byte = value.getbyte(position)
+          break unless space?(byte) || byte == 44
+
+          position += 1
+        end
+        position
+      end
+
+      def skip_spaces(value, position)
+        position += 1 while position < value.bytesize && space?(value.getbyte(position))
+        position
+      end
+
+      def space?(byte)
+        ASCII_SPACE.include?(byte)
+      end
+
+      def apply_changes(source, changes)
+        changes.sort_by(&:first).reverse_each do |start, finish, replacement|
+          prefix = source.byteslice(0, start)
+          suffix = source.byteslice(finish, source.bytesize - finish)
+          source = prefix + replacement + suffix
+        end
+        source
+      end
+    end
+  end
+end

data/lib/jekyll/fingerprint_flow/url_tagger.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Jekyll
+  module FingerprintFlow
+    # Decides whether a single URL from generated HTML should carry a
+    # content-hash tag, and produces the tagged URL. Pure URL logic — file
+    # resolution and hashing are injected.
+    #
+    # Tagged:   local URLs with a fingerprintable extension resolving to a
+    #           real file under _site → ?v=<md5> (merged into any existing
+    #           query, fragment preserved)
+    # Skipped:  external URLs (any scheme, //), fragment-only, data:,
+    #           non-allowlisted extensions, and references whose target file does
+    #           not exist inside _site.
+    class UrlTagger
+      EXTERNAL = %r{\A(?:[a-z][a-z0-9+.-]*:|//)}i
+
+      def initialize(site:, config:, hasher:)
+        @dest = File.expand_path(site.dest)
+        @baseurl = normalize_baseurl(site.baseurl)
+        @config = config
+        @hasher = hasher
+      end
+
+      # Returns the rewritten URL, or nil when the URL must not be touched.
+      def tag(url, html_dir:, base_href: nil)
+        parts = split(url.strip) or return
+        path, query, frag = parts
+        decoded_path = unescape(path) or return
+        return unless fingerprintable?(decoded_path)
+
+        resolved = resolve(decoded_path, html_dir, base_href) or return
+        merge(path, query, frag, @hasher.tag(resolved))
+      end
+
+      private
+
+      def normalize_baseurl(value)
+        normalized = value.to_s
+        normalized = normalized.delete_prefix("/") while normalized.start_with?("/")
+        normalized = normalized.delete_suffix("/") while normalized.end_with?("/")
+        normalized
+      end
+
+      def split(url)
+        return if url.empty? || url.match?(EXTERNAL)
+
+        path, _, fragment = url.partition("#")
+        path, _, query = path.partition("?")
+        return if path.empty?
+
+        [path, query, fragment]
+      end
+
+      def unescape(path)
+        URI::DEFAULT_PARSER.unescape(path)
+      rescue ArgumentError
+        nil
+      end
+
+      def fingerprintable?(path)
+        ext = File.extname(path).delete_prefix(".").downcase
+        return false unless @config.extensions.include?(ext)
+
+        @config.exclude.none? { |prefix| path.start_with?(prefix) }
+      end
+
+      def resolve(path, html_dir, base_href)
+        return if external_base_href?(base_href)
+
+        candidate = candidate_path(path, html_dir, base_href)
+        candidate && confined_file(candidate)
+      rescue ArgumentError, SystemCallError
+        nil
+      end
+
+      def external_base_href?(base_href)
+        base_href&.strip&.match?(EXTERNAL)
+      end
+
+      def candidate_path(path, html_dir, base_href)
+        return root_relative_path(path) if path.start_with?("/")
+
+        base_dir = relative_base_dir(base_href, html_dir)
+        base_dir && File.expand_path(path, base_dir)
+      end
+
+      def root_relative_path(path)
+        File.expand_path(without_baseurl(path.delete_prefix("/")), @dest)
+      end
+
+      def without_baseurl(relative)
+        return relative if @baseurl.empty?
+        return "" if relative == @baseurl
+
+        relative.start_with?("#{@baseurl}/") ? relative.delete_prefix("#{@baseurl}/") : relative
+      end
+
+      def relative_base_dir(base_href, html_dir)
+        return html_dir unless base_href
+
+        base_path = base_href.strip.partition("#").first.partition("?").first
+        decoded_base = unescape(base_path) or return
+        return html_dir if decoded_base.empty?
+
+        base_target = base_target(decoded_base, html_dir)
+        decoded_base.end_with?("/") ? base_target : File.dirname(base_target)
+      end
+
+      def base_target(path, html_dir)
+        return root_relative_path(path) if path.start_with?("/")
+
+        File.expand_path(path, html_dir)
+      end
+
+      def confined_file(candidate)
+        root = File.realpath(@dest)
+        resolved = File.realpath(candidate)
+        return unless File.file?(resolved) && inside_destination?(resolved, root)
+
+        resolved
+      end
+
+      def inside_destination?(path, root)
+        prefix = root.end_with?(File::SEPARATOR) ? root : "#{root}#{File::SEPARATOR}"
+        path.start_with?(prefix)
+      end
+
+      def merge(path, query, fragment, tag)
+        merged = if query.match?(/(?:^|&)v=/)
+                   query.sub(/(^|&)v=[^&]*/, "\\1v=#{tag}")
+                 elsif query.empty?
+                   "v=#{tag}"
+                 else
+                   "#{query}&v=#{tag}"
+                 end
+        suffix = fragment.empty? ? "" : "##{fragment}"
+        "#{path}?#{merged}#{suffix}"
+      end
+    end
+  end
+end

data/lib/jekyll/fingerprint_flow/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module FingerprintFlow
+    VERSION = "0.1.0"
+  end
+end

data/lib/jekyll/fingerprint_flow.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "jekyll"
+require "jekyll/fingerprint_flow/version"
+require "jekyll/fingerprint_flow/configuration"
+require "jekyll/fingerprint_flow/hasher"
+require "jekyll/fingerprint_flow/url_tagger"
+require "jekyll/fingerprint_flow/html_tag_scanner"
+require "jekyll/fingerprint_flow/srcset_rewriter"
+require "jekyll/fingerprint_flow/html_document_rewriter"
+require "jekyll/fingerprint_flow/rewriter"
+require "jekyll/fingerprint_flow/interface"
+
+module Jekyll
+  module FingerprintFlow
+    Configuration::POST_WRITE_PRIORITIES.each do |hook_priority|
+      registered_priority = hook_priority
+      Jekyll::Hooks.register :site, :post_write, priority: registered_priority do |site|
+        next unless Configuration.post_write_priority(site) == registered_priority
+
+        Rewriter.new(site).run
+      end
+    end
+  end
+end

data/lib/jekyll-fingerprint-flow.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "jekyll/fingerprint_flow"

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-fingerprint-flow
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Svend Gundestrup
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: A zero-config Jekyll plugin that content-tags supported local asset URLs
+  in generated .html/.htm attributes at post_write. Covers matching markup emitted
+  by themes and plugins without template changes. CSS/JS runtime references and HTTP
+  cache headers are outside its scope.
+email:
+- svend@gundestrup.dk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- interface.yml
+- lib/jekyll-fingerprint-flow.rb
+- lib/jekyll/fingerprint_flow.rb
+- lib/jekyll/fingerprint_flow/configuration.rb
+- lib/jekyll/fingerprint_flow/hasher.rb
+- lib/jekyll/fingerprint_flow/html_document_rewriter.rb
+- lib/jekyll/fingerprint_flow/html_tag_parser.rb
+- lib/jekyll/fingerprint_flow/html_tag_scanner.rb
+- lib/jekyll/fingerprint_flow/interface.rb
+- lib/jekyll/fingerprint_flow/rewriter.rb
+- lib/jekyll/fingerprint_flow/srcset_rewriter.rb
+- lib/jekyll/fingerprint_flow/url_tagger.rb
+- lib/jekyll/fingerprint_flow/version.rb
+homepage: https://github.com/gundestrup/jekyll-fingerprint-flow
+licenses:
+- AGPL-3.0-or-later
+metadata:
+  homepage_uri: https://github.com/gundestrup/jekyll-fingerprint-flow
+  source_code_uri: https://github.com/gundestrup/jekyll-fingerprint-flow/tree/main
+  changelog_uri: https://github.com/gundestrup/jekyll-fingerprint-flow/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/gundestrup/jekyll-fingerprint-flow/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Content-hash URL cache busting for Jekyll HTML output
+test_files: []