jekyll-imgflow 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a8e1eb8739d53b1ebcdbc440d4c77279ce895794ffb1beda8de9df159227d91
-  data.tar.gz: 730145b3e3017a1a63281f7e68c518cdc82cce708e55d942cdabdba002900d7c
+  metadata.gz: '096d8389110e5128cb043db130059fed14d477e859068074645aa2d915453d78'
+  data.tar.gz: 47808ceb1562c5445bb3d6b6acbca1477a19ab9477e414c712bce676c8dd579e
 SHA512:
-  metadata.gz: 23a45cd5749d4c389b65ffdbd54ca3240465441a325861d739acfedcaf342bd3e111eb04165b925d790f8b862a79d40c9bcbe85979181b184ea7bc3253065e00
-  data.tar.gz: 9b71032b277287766586518ef618cde9aa0d787f2ed3e7b061b609685f68221a46a7d5a09b53e8a4907512bf11611028a9b8add638f37477b08b607e9f38aa89
+  metadata.gz: 6a22f23719023088512647af702af94e220f7697016cac7ee85d1d894e49be7e2f35c67439e1e6701d14d3a1be20d5cc52cf1961d9dd64da39ae06431b868994
+  data.tar.gz: e25a2fb82d17e77791776935adfe333cd2f127396702902988b3956b10d41e4a4e3101ec9a50a09aaf44a876c7baa42c32135c37b1fdb785179a946c2472c793

data/README.md

@@ -5,6 +5,7 @@ A [Jekyll](https://jekyllrb.com/) plugin for automatic image optimization with m
 [![DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/gundestrup/jekyll-imgflow)
 [![Status](https://img.shields.io/badge/status-active-success)](https://github.com/gundestrup/jekyll-imgflow)
 [![codecov](https://codecov.io/gh/gundestrup/jekyll-imgflow/branch/main/graph/badge.svg)](https://codecov.io/gh/gundestrup/jekyll-imgflow)
+[![VS Code Extension](https://img.shields.io/badge/VS%20Code%20Companion-jekyll--imgflow-blue?logo=visual-studio-code)](https://github.com/gundestrup/jekyll-imgflow-vscode)
 [![License](https://img.shields.io/github/license/gundestrup/jekyll-imgflow)](LICENSE)
 
 ## 🚀 Quick Start
@@ -16,17 +17,28 @@ gem 'jekyll-imgflow'
 # Install
 bundle install
 
-# Configure (_config.yml)
+# Configure (_config.yml) — only originals and output are required,
+# everything else has sensible defaults:
 imgflow:
   originals: "assets/images/originals"
   output: "assets/images/optimized"
-  sizes: {sm: 400, md: 800, lg: 1200}
-  formats: [webp, avif, jpg]
 
 # Use in templates
 {% 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).
+
+> **Note:** Image references require exact filenames (or paths relative to
+> `originals`). There is no fuzzy matching during the build yet — if you type
+> `photo.jpg` but the file is `photo.jpeg`, the build will fail with an error.
+>
+> For editor autocomplete while writing `{% imgflow %}` tags, install the
+> [VS Code companion extension](https://github.com/gundestrup/jekyll-imgflow-vscode).
+
 ## ✨ Key Features
 
 - **Multiple Providers**: [Sharp](https://github.com/lovell/sharp), [ImageMagick](https://github.com/ImageMagick/ImageMagick), [LibVips](https://github.com/libvips/libvips), [Imgproxy](https://github.com/imgproxy/imgproxy), [Weserv](https://github.com/weserv/images), [Flyimg](https://github.com/flyimg/flyimg)
@@ -112,18 +124,17 @@ gem 'jekyll-imgflow'
 # Install
 bundle install
 
-# Configure (_config.yml)
+# Configure (_config.yml) — only originals and output required:
 imgflow:
   originals: "assets/images/originals"
   output: "assets/images/optimized"
-  sizes: {sm: 400, md: 800, lg: 1200}
-  formats: [webp, avif, jpg]
 
 # Use in templates
 {% imgflow photo.jpg resize width:800 %}
 ```
 
-**See:** [installation.md](docs/installation.md) for detailed installation instructions and configuration options
+**See:** [installation.md](docs/installation.md) for detailed installation and
+[all configuration options](docs/installation.md#4-add-to-_configyml)
 
 ## 🐳 Docker Setup (Recommended)
 

data/lib/jekyll-imgflow/batch_manager.rb

@@ -213,8 +213,13 @@ module JekyllImgFlow
           # Use FilenameGenerator to generate proper filename
           operations = { width: width, format: format, quality: config.quality }
           filename = filename_generator.generate_filename(original_name, operations)
-          # Write to _site during build (after Jekyll copies assets)
-          output_path = path_resolver.resolve_output_path(filename)
+
+          # Preserve original directory structure under output
+          subdir = File.dirname(original_name)
+          subdir = nil if subdir == "."
+
+          # Write to source directory so Jekyll copies files to _site during write phase
+          output_path = path_resolver.resolve_source_output_path(filename, subdir)
 
           tasks << {
             original_name: original_name,

data/lib/jekyll-imgflow/build_time_processor.rb

@@ -42,12 +42,14 @@ module JekyllImgFlow
       original_paths = find_original_images
       Jekyll.logger.info "📸 Found #{original_paths.length} original images"
 
+      originals_dir = File.join(@site.source, @config.originals)
+
       # Build tasks for each original image
       original_paths.each do |path|
-        original_name = File.basename(path)
+        original_name = path.sub("#{originals_dir}/", "")
 
         # Check if needs processing (file changed or provider changed)
-        if needs_processing?(path)
+        if needs_processing?(original_name, path)
           Jekyll.logger.info "🔧 Queuing default versions for: #{original_name}"
 
           # Build default tasks
@@ -84,8 +86,10 @@ module JekyllImgFlow
         provider_name = @registry.current_provider.class.name.split("::").last.downcase
 
         # 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.dest, "")
+        relative_path = absolute_path.sub(@site.source, "")
 
         # Register the version in manifest
         @manifest.register_version(
@@ -113,10 +117,13 @@ module JekyllImgFlow
     end
 
     # Check if image needs processing
-    # @param path [String] Path to original image
+    # @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?(path)
-      original_name = File.basename(path)
+    def needs_processing?(original_name, path = 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
 
       # If no versions exist, needs processing
       return true unless @manifest.versions?(original_name)

data/lib/jekyll-imgflow/config.rb

@@ -2,10 +2,29 @@
 
 module JekyllImgFlow
   class Config
+    # Sensible defaults — users only need to configure `originals` and `output`
+    # (or even nothing at all). All other values fall back to these.
+    DEFAULT_ORIGINALS = "assets/images/originals"
+    DEFAULT_OUTPUT = "assets/images/optimized"
+    DEFAULT_INPUT_FORMATS = %w[jpg jpeg png webp avif gif tiff tif svg].freeze
+    # Output format priority: avif > webp > png > jpg (fallback).
+    # The browser picks the first <source> format it supports, so avif is
+    # served to modern browsers, webp as a fallback for avif, png for
+    # transparency, and jpg as the universal <img> fallback.
+    DEFAULT_FORMATS = %w[avif webp png jpg].freeze
+    DEFAULT_SIZES = { "sm" => 400, "md" => 800, "lg" => 1200, "xl" => 2000 }.freeze
+    DEFAULT_QUALITY = 85
+    # Ordered by speed (see docs/providers.md benchmark):
+    # sharp (14s) → libvips (22s) → imagemagick (31s) → imgproxy (31s) → weserv (30s) → flyimg
+    DEFAULT_BACKEND_PRIORITY = %w[sharp libvips imagemagick imgproxy weserv flyimg].freeze
+    # 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"
+
     attr_reader :site, :originals, :output, :input_formats, :sizes, :formats,
                 :quality, :backend_priority, :imgproxy_url,
                 :image_compressor_url, :weserv_url, :flyimg_url,
-                :optimize_qualities
+                :optimize_qualities, :fallback_format
 
     def initialize(site)
       shared = site.config["shared_images_configs"] || {}
@@ -13,20 +32,14 @@ module JekyllImgFlow
       cfg = shared.merge(overrides)
 
       @site             = site
-      @originals        = cfg["originals"]
-      @output           = cfg["output"]
-      @input_formats    = cfg["input_formats"]
-      @sizes            = cfg["sizes"]
-      @formats          = cfg["formats"]
-      @quality          = cfg["quality"]
-      @backend_priority = cfg["backend_priority"]
-
-      # Validate required config fields
-      raise ArgumentError, "No originals configured in unified config" unless @originals
-      raise ArgumentError, "No output configured in unified config" unless @output
-      raise ArgumentError, "No input_formats configured in unified config" unless @input_formats
-      raise ArgumentError, "No formats configured in unified config" unless @formats
-      raise ArgumentError, "No sizes configured in unified config" unless @sizes
+      @originals        = cfg["originals"] || DEFAULT_ORIGINALS
+      @output           = cfg["output"] || DEFAULT_OUTPUT
+      @input_formats    = cfg["input_formats"] || DEFAULT_INPUT_FORMATS
+      @sizes            = cfg["sizes"] || DEFAULT_SIZES
+      @formats          = cfg["formats"] || DEFAULT_FORMATS
+      @quality          = cfg["quality"] || DEFAULT_QUALITY
+      @backend_priority = cfg["backend_priority"] || DEFAULT_BACKEND_PRIORITY
+      @fallback_format  = cfg["fallback_format"] || DEFAULT_FALLBACK_FORMAT
 
       @imgproxy_url = cfg["imgproxy_url"]
       @image_compressor_url = cfg["image_compressor_url"]

data/lib/jekyll-imgflow/html_generator.rb

@@ -58,13 +58,13 @@ module JekyllImgFlow
 
     private
 
-    # Get fallback formats from config or use sensible defaults
+    # Get fallback formats — only the configured fallback format (e.g. jpg).
+    # These are skipped in the <source> loop and used for the <img> fallback.
+    # All other formats (webp, avif, etc.) get <source> tags.
     def fallback_formats
-      if @config&.formats
-        # Convert format names to extensions and add dots
-        @config.formats.map { |fmt| ".#{fmt}" }
+      if @config&.fallback_format
+        [".#{@config.fallback_format}"]
       else
-        # Fallback to common formats if no config available
         %w[.jpg .jpeg .png]
       end
     end
@@ -242,13 +242,40 @@ module JekyllImgFlow
       "<div#{parent_attrs}>#{html}</div>"
     end
 
-    # Group results by file extension/format
+    # Group results by file extension, ordered by config format priority
+    # (avif → webp → png → jpg). The browser picks the first <source> format
+    # it supports, so the order of <source> tags determines format priority.
     def group_by_format(results)
-      results.group_by { |r| File.extname(r).downcase }
+      grouped = results.group_by { |r| File.extname(r).downcase }
+      sort_format_groups(grouped)
     end
 
-    # Find fallback image (prefer jpg/jpeg/png)
+    # Sort format groups by config format priority (first = highest priority).
+    # Formats not in config.formats are appended at the end alphabetically.
+    def sort_format_groups(grouped)
+      priority = build_format_priority
+      grouped.sort_by { |ext, _| priority.index(ext) || Float::INFINITY }
+    end
+
+    # Build a lookup of format extensions ordered by config.formats priority.
+    # E.g. ["avif", "webp", "png", "jpg"] → [".avif", ".webp", ".png", ".jpg"]
+    def build_format_priority
+      return %w[.avif .webp .png .jpg] unless @config&.formats
+
+      @config.formats.map { |fmt| ".#{fmt.downcase}" }
+    end
+
+    # Find fallback image — prefer the configured fallback format,
+    # then any legacy format (jpg/jpeg/png), then first result.
     def find_fallback_image(results)
+      return results.first if results.empty?
+
+      preferred = @config&.fallback_format
+      if preferred
+        found = results.find { |r| r.end_with?(".#{preferred}") }
+        return found if found
+      end
+
       results.find { |r| r.match?(/\.(jpe?g|png)$/i) } || results.first
     end
 

data/lib/jekyll-imgflow/imgflow_tag.rb

@@ -64,7 +64,15 @@ module Jekyll
 
       site = context.registers[:site]
       page = context.registers[:page]
-      original_name = File.basename(parsed[:image_path])
+
+      # Resolve input path
+      input_path = resolve_image_path(parsed[:image_path], site, components[:config])
+      raise ArgumentError, "Input image file not found: #{input_path}" unless File.file?(input_path)
+
+      # Store original name relative to the configured originals directory
+      # so output can mirror the original directory structure
+      originals_dir = File.join(site.source, components[:config].originals)
+      original_name = input_path.sub("#{originals_dir}/", "")
 
       # Get page path for manifest tracking
       # Try multiple attributes to get the page identifier
@@ -74,10 +82,6 @@ module Jekyll
                     "unknown"
                   end
 
-      # Resolve input path
-      input_path = resolve_image_path(parsed[:image_path], site, components[:config])
-      raise ArgumentError, "Input image file not found: #{input_path}" unless File.file?(input_path)
-
       # Process operations using clean architecture
       operations = parsed[:operations]
 
@@ -96,8 +100,12 @@ module Jekyll
                    params[:quality] ||= components[:config].quality       # Use default quality
                  end
 
+                 # Preserve original directory structure under output
+                 subdir = File.dirname(original_name)
+                 subdir = nil if subdir == "."
+
                  filename = components[:filename_generator].generate_filename(input_path, params)
-                 output_path = components[:path_resolver].resolve_output_path(filename)
+                 output_path = components[:path_resolver].resolve_source_output_path(filename, subdir)
 
                  # Determine version type
                  version_type = determine_version_type(params, components[:config])
@@ -199,11 +207,12 @@ module Jekyll
       path_resolver = JekyllImgFlow::PathResolver.new(config)
 
       # Handle different path formats
-      if image_path.start_with?("/") || image_path.include?("/")
-        # Absolute or relative path
+      if image_path.start_with?("/")
+        # Absolute site-root path: /assets/images/originals/valdemar/photo.jpg
         File.join(site.source, image_path)
       else
-        # Use PathResolver to get CLI path (full filesystem path)
+        # Relative path: photo.jpg or valdemar/photo.jpg
+        # Always resolve against the configured originals directory
         path_resolver.cli_path(image_path)
       end
     end

data/lib/jekyll-imgflow/manifest_manager.rb

@@ -114,7 +114,7 @@ module JekyllImgFlow
 
       # Get optimized directory path
       config = JekyllImgFlow::Config.new(@site)
-      optimized_dir = File.join(@site.dest, config.output)
+      optimized_dir = File.join(@site.source, config.output)
 
       # Safety guard: prevent deletion of _site itself
       raise "Refusing to delete optimized directory: path resolves to site dest or is empty" if optimized_dir == @site.dest || optimized_dir.empty?
@@ -261,12 +261,7 @@ module JekyllImgFlow
       cleaned = []
 
       orphans.each do |orphan|
-        output_file = if orphan["output"].start_with?("/")
-                        orphan["output"]
-                      else
-                        File.join(@site.dest,
-                                  orphan["output"])
-                      end
+        output_file = File.join(@site.source, orphan["output"])
         if File.exist?(output_file)
           File.delete(output_file)
           cleaned << orphan["output"]

data/lib/jekyll-imgflow/operation_processor.rb

@@ -42,13 +42,18 @@ module JekyllImgFlow
       type = operation[:type]
       params = operation[:params]
 
+      # Determine version type
+      version_type = determine_version_type(params)
+
+      # Preserve original directory structure under output
+      subdir = File.dirname(original_name)
+      subdir = nil if subdir == "."
+
       # Generate filename using FilenameGenerator (JPT compatible)
       filename = @filename_generator.generate_filename(input_path, params)
-      # Write to _site during build (after Jekyll copies assets)
-      actual_output_path = @path_resolver.resolve_output_path(filename)
 
-      # Determine version type
-      version_type = determine_version_type(params)
+      # Write to source directory so Jekyll copies files to _site during the write phase
+      actual_output_path = @path_resolver.resolve_source_output_path(filename, subdir)
 
       # Ensure output directory exists before processing
       FileUtils.mkdir_p(File.dirname(actual_output_path))
@@ -68,8 +73,8 @@ module JekyllImgFlow
 
       # Register in manifest
       if @manifest
-        # Convert absolute path to relative for manifest storage
-        relative_path = actual_output_path.sub(@path_resolver.site_dest, "")
+        # Store relative path (with leading /) for manifest storage
+        relative_path = "/#{@path_resolver.resolve_relative_output_path(filename, subdir)}"
 
         provider_name = @provider.class.provider_name
         @manifest.register_version(
@@ -83,9 +88,43 @@ module JekyllImgFlow
         )
       end
 
+      # Register as Jekyll static file so Jekyll copies it to _site during
+      # the write phase. Without this, files created during pre_render (or
+      # during render via imgflow tags) are not picked up by Jekyll's static
+      # file reader, which runs before pre_render. This would leave _site
+      # without optimized images until a second build.
+      register_jekyll_static_file(actual_output_path)
+
       actual_output_path
     end
 
+    # Register a generated file as a Jekyll::StaticFile so Jekyll copies it
+    # to _site during the write phase. No-op for mock/test sites.
+    # @param file_path [String] Absolute path to the generated file in source
+    def register_jekyll_static_file(file_path)
+      site = @config&.site
+      return unless site.is_a?(Jekyll::Site)
+
+      relative = file_path.delete_prefix("#{site.source}/")
+      return if relative == file_path # not under site source
+
+      add_static_file(site, relative) unless static_file_registered?(site, relative)
+    end
+
+    # @param site [Jekyll::Site] Jekyll site object
+    # @param relative [String] Path relative to site source
+    def static_file_registered?(site, relative)
+      site.static_files.any? { |sf| sf.relative_path == "/#{relative}" }
+    end
+
+    # @param site [Jekyll::Site] Jekyll site object
+    # @param relative [String] Path relative to site source
+    def add_static_file(site, relative)
+      site.static_files << Jekyll::StaticFile.new(
+        site, site.source, File.dirname(relative), File.basename(relative)
+      )
+    end
+
     # Process multiple operations on an image in sequence (batch)
     # @param operations [Array<Hash>] Array of operations to process
     # @param input_path [String] Path to input image

data/lib/jekyll-imgflow/path_resolver.rb

@@ -61,26 +61,29 @@ module JekyllImgFlow
 
     # Resolve output path for generated filename
     # @param filename [String] Generated filename
+    # @param subdir [String, nil] Optional subdirectory under output
     # @return [String] Full path to output file in _site (for specialized versions during rendering)
-    def resolve_output_path(filename)
+    def resolve_output_path(filename, subdir = nil)
       # Resolve output path relative to site destination
-      File.join(@config.site.dest, @config.output, filename)
+      File.join([@config.site.dest, @config.output, subdir, filename].compact)
     end
 
     # Resolve output path to source directory for default images
     # @param filename [String] Generated filename
+    # @param subdir [String, nil] Optional subdirectory under output
     # @return [String] Full path to output file in source (for default versions during pre_render)
-    def resolve_source_output_path(filename)
+    def resolve_source_output_path(filename, subdir = nil)
       # Default images go to source directory so Jekyll can copy them to _site
-      File.join(@config.site.source, @config.output, filename)
+      File.join([@config.site.source, @config.output, subdir, filename].compact)
     end
 
     # Resolve relative output path for manifest storage
     # @param filename [String] Generated filename
+    # @param subdir [String, nil] Optional subdirectory under output
     # @return [String] Relative path from site root
-    def resolve_relative_output_path(filename)
+    def resolve_relative_output_path(filename, subdir = nil)
       # Return path relative to site root (without leading /)
-      File.join(@config.output, filename)
+      File.join([@config.output, subdir, filename].compact)
     end
 
     # Get site destination directory

data/lib/jekyll-imgflow/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JekyllImgFlow
-  VERSION = "0.1.6"
+  VERSION = "0.1.8"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-imgflow
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - Svend Gundestrup