jekyll-imgflow 0.1.10 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94373ec599b8e291a5a76cb072d27db634329d5a2c345a42d2bbade48860a143
-  data.tar.gz: 45c949cf624fafb3c290898ccca514677d1b336514fb8cb06dc9009a0936faac
+  metadata.gz: d37c208e7250fe6da8291bfab933d5df7391347d0ce95492e32e1d94e54df7a8
+  data.tar.gz: cd222c0e6dbdcffe168ec0919a12d53c57324a277cb9efeecb5173a98c4c5b04
 SHA512:
-  metadata.gz: 3715974b3af0d82d439e1b96a0d80650ae360a142c61898845b1ed6dda1a6fdbc53a6648f2ca6150df82d40d1a7f123bd4a84524657947638cf1a076df45a3c0
-  data.tar.gz: 1eeed12f791b156bfc87e4a3479845cae4e975a4067ebe9530f6cc87e6b1f3e23a48ddb7b27e892bbb3441bcfd1be83aed0bc998438ecf647be5dfc345d8ae1a
+  metadata.gz: 2f566b0e2d70993a209a5353cf1b91d54e3b3f3143397146f58bbbcf19428eab9797ed5def60efdd3d8f926f214fa2ec6670d47ccfd6c000fe2f9c35b2bac00c
+  data.tar.gz: 0b601aea8c16d71133816f034b4277e399e6108569af169c0984416ef6e5d90edc30490d17af254f736f2897eae5c6b55d515888a4b71af35dd8020b63f37a88

data/README.md

@@ -29,10 +29,9 @@ imgflow:
 {% imgflow photo.jpg resize width:800 %}
 ```
 
-> **Full configuration options:** `quality`, `backend_priority`, `formats`,
-> `fallback_format`, `sizes`, provider URLs, and more — see the
-> [Installation Guide](docs/installation.md#4-add-to-_configyml)
-> and [Configuration Reference](docs/ARCHITECTURE.md).
+> **Configuration:** Only `originals` and `output` are required in `_config.yml`
+> — everything else has sensible defaults. See the
+> [Installation Guide](docs/installation.md#4-add-to-_configyml) for full options.
 
 > **Note:** Image references require exact filenames (or paths relative to
 > `originals`). There is no fuzzy matching during the build yet — if you type
@@ -86,12 +85,12 @@ ImgFlow has two processing flows: **Build-Time** (pre-generation) and **Runtime*
 ## 🎯 Provider Support
 
 ### HTTP API Services (Recommended)
-- **[Imgproxy](https://github.com/imgproxy/imgproxy)** - Fast, reliable (Port 33001)
-- **[Weserv](https://github.com/weserv/images)** - Battle-tested (Port 33007)  
-- **[Flyimg](https://github.com/flyimg/flyimg)** - On-the-fly processing (Port 33008)
+- **[Imgproxy](https://github.com/imgproxy/imgproxy)** - Fast, reliable (Port 4022)
+- **[Weserv](https://github.com/weserv/images)** - Battle-tested (Port 4026)
+- **[Flyimg](https://github.com/flyimg/flyimg)** - On-the-fly processing (Port 4030)
 
 ### CLI Tools (Local)
-- **[Sharp](https://github.com/lovell/sharp)** - Fastest (Node.js/libvips)
+- **[Sharp](https://github.com/lovell/sharp)** - Node.js/libvips processing
 - **[ImageMagick](https://github.com/ImageMagick/ImageMagick)** - Feature-rich
 - **[LibVips](https://github.com/libvips/libvips)** - Memory efficient
 
@@ -110,7 +109,7 @@ rake test                            # All tests
 rake parallel:test                   # Parallel testing (faster)
 
 # Docker Services
-docker-compose -f docker-compose.test.yml up -d  # Start services
+rake start_services                  # Start services (pulls latest pinned images)
 rake check_services                  # Verify services
 ```
 
@@ -130,25 +129,35 @@ bundle install
 imgflow:
   originals: "assets/images/originals"
   output: "assets/images/optimized"
+  # cache_dir defaults to ".cache/imgflow" (stores manifest, survives _site wipes)
 
 # Use in templates
 {% imgflow photo.jpg resize width:800 %}
+
+# Or use built-in presets:
+{% imgflow photo.jpg preset:gallery %}
 ```
 
+**Built-in presets:** `gallery` (400px, avif/webp/jpg, Q80), `hero` (800px, avif/webp/jpg, Q85), `thumbnail` (150px, webp/jpg, Q75). They work without installation. To copy editable versions, add `require "jekyll-imgflow/tasks"` to the site's `Rakefile`, then run `rake imgflow:install_presets`.
+
 **See:** [installation.md](docs/installation.md) for detailed installation and
-[all configuration options](docs/installation.md#4-add-to-_configyml)
+[all configuration options](docs/installation.md#4-add-to-_configyml),
+[presets.md](docs/usage/presets.md) for the preset system
 
 ## 🐳 Docker Setup (Recommended)
 
 ```bash
-# Start all services
-docker-compose -f docker-compose.test.yml --env-file .env.test up -d
+# Start all services (pulls latest pinned images first)
+rake start_services
 
 # Check services
 rake check_services
 
+# Check if pinned images are outdated (run before releases)
+rake check_docker_images
+
 # Stop services
-docker-compose -f docker-compose.test.yml down
+rake stop_services
 ```
 
 **See:** [docker.md](docs/docker.md) for detailed Docker configuration and services

data/lib/jekyll-imgflow/batch_manager.rb

@@ -91,11 +91,12 @@ module JekyllImgFlow
     def process_task(task)
       # Check if processing is needed
       # Check if output is up-to-date
-      if task[:skip_if_exists] && File.exist?(task[:output_path]) && !@operation_processor.needs_processing?(
-        task[:input_path],
-        task[:output_path],
-        task[:params]
-      )
+      if !task[:force_processing] && task[:skip_if_exists] && File.exist?(task[:output_path]) &&
+         !@operation_processor.needs_processing?(
+           task[:input_path],
+           task[:output_path],
+           task[:params]
+         )
         Jekyll.logger.debug "⏭️  Skipping #{task[:original_name]} - already up-to-date"
         mark_completed(task, :skipped)
         return
@@ -104,7 +105,8 @@ module JekyllImgFlow
       # Process the operation
       operation = {
         type: task[:operation_type],
-        params: task[:params]
+        params: task[:params],
+        file_digest: task[:file_digest]
       }
 
       Jekyll.logger.debug "🔍 BatchManager: Processing task - input: #{task[:input_path]}, original: #{task[:original_name]}"
@@ -201,7 +203,7 @@ module JekyllImgFlow
     # @param config [Config] ImgFlow configuration
     # @param site [Jekyll::Site] Jekyll site object
     # @return [Array<Hash>] Array of tasks
-    def self.build_default_tasks(original_name, input_path, config, _site)
+    def self.build_default_tasks(original_name, input_path, config, _site, file_digest: nil)
       tasks = []
 
       # Use FilenameGenerator for consistent naming
@@ -233,6 +235,7 @@ module JekyllImgFlow
             },
             version_type: :default,
             page_path: nil, # Default versions not tied to specific page
+            file_digest: file_digest,
             skip_if_exists: true
           }
         end

data/lib/jekyll-imgflow/build_time_processor.rb

@@ -13,29 +13,31 @@ module JekyllImgFlow
 
       # Initialize operation processor with current provider
       provider = @registry.current_provider
-      @operation_processor = OperationProcessor.new(provider, @path_resolver, @manifest, @config)
+      @operation_processor = OperationProcessor.new(provider, @path_resolver, @manifest, @config) if provider
 
       # Initialize batch manager
       @batch_manager = BatchManager.new(@operation_processor)
 
       # Store all components in site for sharing with ImgFlow tag
-      return if @site.imgflow_components
-
-      filename_generator = JekyllImgFlow::FilenameGenerator.new
+      @filename_generator = JekyllImgFlow::FilenameGenerator.new
 
       @site.imgflow_components = {
         config: @config,
         manifest: @manifest,
         path_resolver: @path_resolver,
-        filename_generator: filename_generator,
+        filename_generator: @filename_generator,
         registry: @registry,
         provider: provider,
-        operation_processor: @operation_processor
+        operation_processor: @operation_processor,
+        stats: @operation_processor&.stats,
+        preset_manager: JekyllImgFlow::PresetManager.new(@site, @config)
       }
     end
 
     # Process all changed images in originals folder
     def process_changed_images
+      return { completed: 0, failed: 0 } unless @operation_processor
+
       Jekyll.logger.info "🔄 BuildTimeProcessor: Processing changed images"
 
       # Get all original images
@@ -44,27 +46,37 @@ module JekyllImgFlow
 
       originals_dir = File.join(@site.source, @config.originals)
 
+      # Clean up manifest entries for deleted originals
+      current_originals = original_paths.map { |path| path.sub("#{originals_dir}/", "") }
+      @manifest.cleanup_deleted_originals(current_originals)
+      @manifest.cleanup_obsolete_defaults(expected_default_operations)
+      @manifest.reset_page_usage unless incremental_build?
+
       # Build tasks for each original image
-      original_paths.each do |path|
+      original_paths.reject { |path| AnimatedGifDetector.animated?(path) }.each do |path|
         original_name = path.sub("#{originals_dir}/", "")
+        file_digest = @filename_generator.file_digest(path)
 
         # Check if needs processing (file changed or provider changed)
-        if needs_processing?(original_name, path)
+        if needs_processing?(original_name, path, file_digest)
           Jekyll.logger.info "🔧 Queuing default versions for: #{original_name}"
 
           # Build default tasks
-          tasks = BatchManager.build_default_tasks(original_name, path, @config, @site)
+          tasks = BatchManager.build_default_tasks(
+            original_name, path, @config, @site, file_digest: file_digest
+          )
+          force_processing = source_digest_changed?(original_name, file_digest)
+          tasks.each { |task| task[:force_processing] = force_processing }
           @batch_manager.add_tasks(tasks)
         else
+          expected_default_operations.length.times { @operation_processor.stats.record_cache_hit }
           Jekyll.logger.debug "⏭️  Skipping #{original_name} - already up-to-date"
         end
       end
 
       # Process all queued tasks
       results = @batch_manager.process_all
-
-      # Register completed tasks in manifest
-      register_completed_tasks(@batch_manager.completed)
+      register_skipped_tasks(@batch_manager.completed)
 
       # Save manifest so it's available when ImgflowTag runs
       @manifest.save
@@ -76,34 +88,19 @@ module JekyllImgFlow
 
     private
 
-    # Register completed tasks in manifest
-    # @param completed_tasks [Array<Hash>] Array of completed tasks from BatchManager
-    def register_completed_tasks(completed_tasks)
-      completed_tasks.each do |task|
-        next unless task[:task] && task[:result]
-
-        # Get provider name
-        provider_name = @registry.current_provider.class.name.split("::").last.downcase
+    def register_skipped_tasks(completed_tasks)
+      provider_name = @registry.current_provider&.class&.provider_name || "unknown"
+      completed_tasks.each do |completed|
+        next unless completed[:status] == :skipped
 
-        # Convert absolute path to relative for manifest storage
-        # Default versions are written to the source directory so Jekyll can
-        # copy them to _site during the write phase.
-        absolute_path = task[:result]
-        relative_path = absolute_path.sub(@site.source, "")
-
-        # Register the version in manifest
+        task = completed[:task]
+        @operation_processor.stats.record_cache_hit
+        relative_path = task[:output_path].sub(@site.source, "")
         @manifest.register_version(
-          task[:task][:original_name],
-          relative_path,
-          task[:task][:params],
-          :default, # BuildTimeProcessor creates default versions
-          nil, # page_path (default versions aren't tied to specific pages)
-          nil, # file_digest
-          provider_name
+          task[:original_name], relative_path, task[:params], :default, nil,
+          task[:file_digest], provider_name
         )
       end
-
-      Jekyll.logger.debug "📝 Registered #{completed_tasks.length} completed tasks in manifest"
     end
 
     # Find all original images in originals folder
@@ -113,48 +110,60 @@ module JekyllImgFlow
       input_formats = @config.input_formats
 
       Dir.glob(File.join(originals_dir, "**", "*.{#{input_formats.join(',')}}"))
-         .reject { |path| AnimatedGifDetector.animated?(path) }
     end
 
     # Check if image needs processing
     # @param original_name [String] Path to original image relative to originals directory
     # @param path [String, nil] Full path to original image (defaults to original_name)
     # @return [Boolean] True if processing needed
-    def needs_processing?(original_name, path = nil)
+    def needs_processing?(original_name, path = nil, file_digest = nil)
       path ||= original_name
-      # For single-argument calls, derive a flat original_name from the full path
       original_name = File.basename(original_name) if original_name == path
+      return true unless File.file?(path)
 
-      # If no versions exist, needs processing
-      return true unless @manifest.versions?(original_name)
+      file_digest ||= @filename_generator.file_digest(path)
+      default_versions = @manifest.get_versions(original_name)["default"] || []
+      current_provider = @registry.current_provider&.class&.provider_name || "unknown"
 
-      # Check if original file was modified
-      versions = @manifest.get_versions(original_name)
-      default_versions = versions["default"] || []
-
-      return true if default_versions.empty?
+      expected_default_operations.any? do |operations|
+        version = default_versions.find do |candidate|
+          @manifest.same_operations?(candidate["operations"], operations)
+        end
+        !current_default_version?(version, current_provider, file_digest)
+      end
+    end
 
-      # Get the most recent version creation time
-      latest_version = default_versions.max_by { |v| v["created_at"] || 0 }
-      version_time = latest_version["created_at"]
+    def expected_default_operations
+      @config.sizes.each_value.flat_map do |width|
+        @config.formats.map do |format|
+          { width: width, format: format, quality: @config.quality }
+        end
+      end
+    end
 
-      # If original is newer than versions, needs processing
-      return true unless version_time
+    def source_digest_changed?(original_name, file_digest)
+      digests = (@manifest.get_versions(original_name)["default"] || []).filter_map do |version|
+        version["file_digest"]
+      end
+      digests.any? && digests.any? { |digest| digest != file_digest }
+    end
 
-      original_mtime = File.mtime(path).to_i
-      return true if original_mtime > version_time
+    def incremental_build?
+      @site.is_a?(Jekyll::Site) && @site.incremental?
+    end
 
-      # No timestamp means we need to process
+    def current_default_version?(version, current_provider, file_digest)
+      return false unless version && version["provider"] == current_provider
+      return false unless version["file_digest"] == file_digest
 
-      # Check if provider changed
-      current_provider = @registry.current_provider.class.provider_name
-      version_providers = default_versions.map { |v| v["provider"] }
-      version_providers.uniq!
+      output_path = version["output"]
+      return false unless output_path
 
-      return true unless version_providers.include?(current_provider)
+      absolute_path = File.expand_path(output_path.delete_prefix("/"), @site.source)
+      output_root = File.expand_path(@config.output, @site.source)
+      return false unless absolute_path.start_with?("#{output_root}#{File::SEPARATOR}")
 
-      # Up-to-date
-      false
+      File.file?(absolute_path)
     end
   end
 end

data/lib/jekyll-imgflow/config.rb

@@ -20,11 +20,12 @@ module JekyllImgFlow
     # Format used for the <img> fallback in <picture> elements.
     # All other formats in `formats` get <source> tags for browsers that support them.
     DEFAULT_FALLBACK_FORMAT = "jpg"
+    DEFAULT_IMAGE_MODAL = true
 
     attr_reader :site, :originals, :output, :input_formats, :sizes, :formats,
                 :quality, :backend_priority, :imgproxy_url,
-                :image_compressor_url, :weserv_url, :flyimg_url,
-                :optimize_qualities, :fallback_format
+                :weserv_url, :flyimg_url,
+                :optimize_qualities, :fallback_format, :image_modal
 
     def initialize(site)
       shared = site.config["shared_images_configs"] || {}
@@ -40,9 +41,9 @@ module JekyllImgFlow
       @quality          = cfg["quality"] || DEFAULT_QUALITY
       @backend_priority = cfg["backend_priority"] || DEFAULT_BACKEND_PRIORITY
       @fallback_format  = cfg["fallback_format"] || DEFAULT_FALLBACK_FORMAT
+      @image_modal      = cfg.fetch("image_modal", DEFAULT_IMAGE_MODAL)
 
       @imgproxy_url = cfg["imgproxy_url"]
-      @image_compressor_url = cfg["image_compressor_url"]
       @weserv_url       = cfg["weserv_url"]
       @flyimg_url       = cfg["flyimg_url"]
       @optimize_qualities = cfg["optimize_qualities"] || {
@@ -64,12 +65,10 @@ module JekyllImgFlow
       {
         enabled: merged_config.key?("imgproxy_url") ||
           merged_config.key?("weserv_url") ||
-          merged_config.key?("flyimg_url") ||
-          merged_config.key?("image_compressor_url"),
+          merged_config.key?("flyimg_url"),
         imgproxy_url: @imgproxy_url,
         weserv_url: @weserv_url,
-        flyimg_url: @flyimg_url,
-        image_compressor_url: @image_compressor_url
+        flyimg_url: @flyimg_url
       }
     end
 

data/lib/jekyll-imgflow/filename_generator.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "digest"
-require "json"
 
 module JekyllImgFlow
   # Generates unique filenames for processed images
@@ -11,10 +10,18 @@ module JekyllImgFlow
     # @param original_name [String] Original image filename
     # @param operations [Hash] Operations applied to image
     # @return [String] Generated filename (without path)
+    # Formats that are valid for output (raster only).
+    # SVG and other vector formats are input-only — image providers
+    # always produce raster output (webp, avif, jpg, png).
+    VECTOR_FORMATS = %w[svg].freeze
+
     def generate_filename(original_name, operations)
       base_name = File.basename(original_name, ".*")
       width = operations[:width]
       format = operations[:format] || File.extname(original_name).delete(".")
+      # Vector formats (e.g. SVG) are input-only — never use them as
+      # output format. Fall back to jpg (universal <img> fallback).
+      format = "jpg" if VECTOR_FORMATS.include?(format.to_s.downcase)
 
       # Generate hash using Jekyll Picture Tag approach
       hash = generate_jpt_hash(original_name, operations)
@@ -22,15 +29,6 @@ module JekyllImgFlow
       "#{base_name}-#{width}-#{hash}.#{format}"
     end
 
-    # Generate cache key for operations (SHA256 for manifest tracking)
-    # @param operations [Hash] Operations hash
-    # @return [String] Cache key
-    def generate_cache_key(operations)
-      # Sort keys to ensure consistent hashing
-      sorted_operations = operations.sort.to_h
-      Digest::SHA256.hexdigest(sorted_operations.to_json)
-    end
-
     # Get file digest for manifest tracking
     # @param original_path [String] Path to original image
     # @return [String] SHA256 digest of file

data/lib/jekyll-imgflow/generated_file_cleaner.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module JekyllImgFlow
+  class GeneratedFileCleaner
+    def initialize(site, config)
+      @site = site
+      @config = config
+    end
+
+    def delete(output_path)
+      return false unless output_path
+
+      unregister_static_file(output_path)
+      deleted = false
+      [@site.source, @site.dest].each do |base_path|
+        path = safe_generated_path(base_path, output_path)
+        next unless path && File.file?(path)
+
+        File.delete(path)
+        remove_empty_output_dirs(File.dirname(path), output_root(base_path))
+        deleted = true
+      end
+      deleted
+    end
+
+    def clear
+      roots = [@site.source, @site.dest].map { |base_path| output_root(base_path) }
+      valid = roots.zip([@site.source, @site.dest]).all? do |directory, base_path|
+        base = File.expand_path(base_path)
+        directory.start_with?("#{base}#{File::SEPARATOR}")
+      end
+      raise "Refusing to delete optimized directory outside configured roots" unless valid
+
+      unregister_output_tree(roots.first)
+      files = roots.flat_map do |directory|
+        Dir.glob(File.join(directory, "**", "*")).select { |path| File.file?(path) }
+      end
+      files = files.uniq
+      files.each { |path| File.delete(path) }
+      files.length
+    end
+
+    private
+
+    def unregister_static_file(output_path)
+      return unless @site.is_a?(Jekyll::Site)
+
+      source_path = safe_generated_path(@site.source, output_path)
+      @site.static_files.reject! do |static_file|
+        source_path && File.expand_path(static_file.path) == source_path
+      end
+    end
+
+    def unregister_output_tree(root)
+      return unless @site.is_a?(Jekyll::Site)
+
+      @site.static_files.reject! do |static_file|
+        File.expand_path(static_file.path).start_with?("#{root}#{File::SEPARATOR}")
+      end
+    end
+
+    def safe_generated_path(base_path, output_path)
+      root = output_root(base_path)
+      candidate = File.expand_path(output_path.delete_prefix("/"), base_path)
+      candidate if candidate.start_with?("#{root}#{File::SEPARATOR}")
+    end
+
+    def output_root(base_path)
+      File.expand_path(@config.output, base_path)
+    end
+
+    def remove_empty_output_dirs(directory, root)
+      while directory.start_with?("#{root}#{File::SEPARATOR}") && Dir.empty?(directory)
+        Dir.rmdir(directory)
+        directory = File.dirname(directory)
+      end
+    end
+  end
+end

data/lib/jekyll-imgflow/hooks.rb

@@ -11,6 +11,12 @@ module JekyllImgFlow
       site.define_singleton_method(:imgflow_components=) { |value| @imgflow_components = value }
     end
 
+    if site.respond_to?(:config)
+      cache_dir = Config.new(site).cache_dir
+      site.config["exclude"] = Array(site.config["exclude"])
+      site.config["exclude"] << cache_dir unless site.config["exclude"].include?(cache_dir)
+    end
+
     # Components will be initialized on first use (lazy loading)
     Jekyll.logger.info "✅ ImgFlow: Components ready for initialization"
   end
@@ -31,22 +37,30 @@ module JekyllImgFlow
     Jekyll.logger.info "🔌 ImgFlow post_write hook - saving final manifest with page usage"
 
     if site.imgflow_components && site.imgflow_components[:manifest]
-      site.imgflow_components[:manifest].save
+      manifest = site.imgflow_components[:manifest]
+      cleanup_orphaned_images(site, manifest) if Jekyll.env != "development" &&
+                                                 !(site.is_a?(Jekyll::Site) && site.incremental?)
+      manifest.save
       Jekyll.logger.info "✅ ImgFlow: Final manifest saved with all page usage data"
     else
       Jekyll.logger.warn "⚠️  ImgFlow: No manifest found to save"
     end
+  end
 
-    # Clean up orphaned specialized images in production
-    cleanup_orphaned_images(site) if Jekyll.env != "development"
+  # Inject modal CSS/JS into pages that contain data-imgflow-modal triggers
+  %i[pages documents].each do |type|
+    Jekyll::Hooks.register type, :post_render do |doc|
+      doc.output = ModalAssets.inject(doc.output) if doc.output
+    end
   end
 
-  def self.cleanup_orphaned_images(site)
+  def self.cleanup_orphaned_images(site, manifest = nil)
     Jekyll.logger.info "🧹 ImgFlow: Checking for orphaned specialized images..."
 
     # Use ManifestManager to find and cleanup orphans
-    manifest = ManifestManager.new(site)
+    manifest ||= ManifestManager.new(site)
     cleaned = manifest.cleanup_orphans
+    manifest.save
 
     if cleaned.any?
       Jekyll.logger.info "✅ ImgFlow: Removed #{cleaned.length} orphaned specialized images"

data/lib/jekyll-imgflow/html_generator.rb

@@ -4,8 +4,7 @@ module JekyllImgFlow
   # Unified HTML Generator for all markup formats
   # Supports Picture Tag compatibility with multiple markup formats and attributes
   class HtmlGenerator
-    MARKUP_FORMATS = %w[auto picture img data_auto data_picture data_img direct_url
-                        naked_srcset].freeze
+    include ModalWrapper
 
     # Generate HTML based on markup format and attributes
     # @param results [Array<String>] Processed image paths
@@ -50,6 +49,9 @@ module JekyllImgFlow
       # Wrap in link if specified
       html = wrap_with_link(html) if @attributes[:link]
 
+      # Wrap in modal trigger if enabled (only for HTML elements, not raw URLs)
+      html = wrap_with_modal(html) if modal_enabled? && html_element?
+
       # Wrap in parent container if specified
       html = wrap_with_parent(html) if @attributes[:parent]&.any?
 
@@ -80,7 +82,8 @@ module JekyllImgFlow
         a: attributes[:a] || {},
         parent: attributes[:parent] || {},
         alt: attributes[:alt],
-        link: attributes[:link]
+        link: attributes[:link],
+        modal: attributes[:modal]
       }
     end
 
@@ -92,7 +95,8 @@ module JekyllImgFlow
         a: {},
         parent: {},
         alt: nil,
-        link: nil
+        link: nil,
+        modal: nil
       }
     end
 
@@ -332,11 +336,20 @@ module JekyllImgFlow
            .gsub(">", "&gt;")
     end
 
-    # Get correct path for HTML generation (relative paths for Jekyll sites)
+    # Get correct path for HTML generation.
     def html_path(relative_path)
-      # For HTML generation, we want relative paths within the site
-      # Remove leading slash to make it relative to site root
-      relative_path.start_with?("/") ? relative_path[1..] : relative_path
+      path = "/#{relative_path.delete_prefix('/')}"
+      baseurl = html_baseurl
+      return path if baseurl.empty? || path == baseurl || path.start_with?("#{baseurl}/")
+
+      "#{baseurl}#{path}"
+    end
+
+    def html_baseurl
+      site = @context&.registers&.dig(:site) || @config&.site
+      baseurl = site&.config&.fetch("baseurl", "").to_s
+      normalized = baseurl.gsub(%r{\A/+|/+$}, "")
+      normalized.empty? ? "" : "/#{normalized}"
     end
 
     # Get absolute URL when needed (for direct_url format)
@@ -345,18 +358,7 @@ module JekyllImgFlow
 
       site = @context.registers[:site]
       base_url = site.config["url"] || "http://localhost:4000"
-      baseurl = site.config["baseurl"] || ""
-
-      # Ensure base_url ends without trailing slash and baseurl starts without slash
-      base_url = base_url.chomp("/")
-      baseurl = baseurl[1..] if baseurl.start_with?("/")
-
-      # Build URL parts carefully to avoid double slashes
-      url_parts = [base_url]
-      url_parts << baseurl unless baseurl.empty?
-      url_parts << html_path(relative_path)
-
-      url_parts.join("/")
+      "#{base_url.chomp('/')}#{html_path(relative_path)}"
     end
   end
 end