jekyll-auto-thumbnails 0.2.0

data/README.md

@@ -0,0 +1,123 @@
+# Automatic Image Thumbnails for Jekyll
+
+Scans your rendered HTML for local images with `width` or `height` attributes, then automatically generates and uses appropriately-sized thumbnails for them, if the `src` image is bigger than that.
+
+Can also take global maximum dimensions (such as for fixed-width layouts) and thumbnail images that don't have explicit size attributes, too.
+
+Requires [ImageMagick](https://imagemagick.org) to be installed.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+group :jekyll_plugins do
+  gem "jekyll-auto-thumbnails"
+end
+```
+
+Run:
+
+```bash
+bundle install
+```
+
+**System Requirement**: ImageMagick must be installed (gem requires the `convert` and `identify` commands to be available).
+
+## Configuration
+
+```yaml
+# _config.yml
+auto_thumbnails:
+  enabled: true  # default: true
+  
+  # Maximum dimensions for automatic thumbnailing
+  # Images exceeding these get thumbnails even without explicit sizing
+  max_width: 1200   # pixels (optional)
+  max_height: 800   # pixels (optional)
+  
+  # JPEG quality for generated thumbnails (0-100)
+  quality: 85  # default: 85
+```
+
+## How It Works
+
+1. **HTML Scanning**: After all plugins run, scans `<article>` tags for images
+2. **Size Detection**: 
+   - Images with `width` or `height` attributes → uses those dimensions
+   - Unsized images exceeding max config → thumbnails to max dimensions
+3. **Generation**: Creates thumbnails with MD5-based caching in `.jekyll-cache/`
+4. **URL Replacement**: Updates `<img src>` to point to thumbnails
+5. **File Copying**: Copies thumbnails to `_site/` after build
+
+## Usage Examples
+
+### Explicit Sizing
+
+```html
+<article>
+  <img src="/photo.jpg" width="300" height="200">
+  <!-- Generates: photo_thumb-abc123-300x200.jpg -->
+</article>
+```
+
+### Automatic Optimization
+
+```yaml
+# _config.yml
+auto_thumbnails:
+  max_width: 800
+```
+
+```html
+<article>
+  <img src="/big-photo.jpg">
+  <!-- If photo is 2000x1500, generates: big-photo_thumb-def456-800x600.jpg -->
+</article>
+```
+
+### With Markdown
+
+Works automatically with any Markdown processor, because it checks the rendered HTML!
+
+```markdown
+![Photo](photo.jpg)  <!-- Auto-detects size -->
+```
+
+
+## Cache Behavior
+
+- First build: Generates thumbnails, stores in `.jekyll-cache/`
+- Subsequent builds: Reuses cached thumbnails (fast!)
+- Source changed: MD5 mismatch detected, regenerates automatically
+- Dimensions changed: Different filename, generates new thumbnail
+
+## Troubleshooting
+
+### ImageMagick Not Found
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install imagemagick
+
+# macOS
+brew install imagemagick
+
+# Verify installation
+which convert identify
+```
+
+### Thumbnails Not Generating
+
+Check build output for warnings:
+
+```bash
+bundle exec jekyll build --verbose
+# Look for "AutoThumbnails:" messages
+```
+
+### Clear Cache
+
+```bash
+rm -rf .jekyll-cache/jekyll-auto-thumbnails/
+```

data/lib/jekyll-auto-thumbnails/configuration.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module JekyllAutoThumbnails
+  # Configuration parser for auto_thumbnails settings
+  #
+  # Parses Jekyll site config for auto_thumbnails options and provides
+  # accessor methods with appropriate defaults and validation.
+  class Configuration
+    attr_reader :max_width, :max_height, :quality, :cache_dir
+
+    # Initialize configuration from Jekyll site
+    #
+    # @param site [Jekyll::Site] The Jekyll site object
+    def initialize(site)
+      config_hash = site.config["auto_thumbnails"] || {}
+
+      @enabled = config_hash.fetch("enabled", true)
+      @max_width = parse_dimension(config_hash["max_width"])
+      @max_height = parse_dimension(config_hash["max_height"])
+      @quality = parse_quality(config_hash.fetch("quality", 85))
+      @cache_dir = File.join(site.source, ".jekyll-cache", "jekyll-auto-thumbnails")
+    end
+
+    # Check if image optimization is enabled
+    #
+    # @return [Boolean] true if enabled (default: true)
+    def enabled?
+      @enabled
+    end
+
+    private
+
+    # Parse dimension value (max_width or max_height)
+    #
+    # @param value [Object] dimension value from config
+    # @return [Integer, nil] positive integer or nil
+    def parse_dimension(value)
+      val = value.to_i
+      val.positive? ? val : nil
+    end
+
+    # Parse quality value (0-100)
+    #
+    # @param value [Object] quality value from config
+    # @return [Integer] quality value 0-100, or 85 if invalid
+    def parse_quality(value)
+      val = value.to_i
+      val.between?(0, 100) ? val : 85
+    end
+  end
+end

data/lib/jekyll-auto-thumbnails/digest_calculator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+module JekyllAutoThumbnails
+  # MD5 digest calculation for cache keys
+  #
+  # Computes short MD5 digests of image files for use in thumbnail filenames.
+  module DigestCalculator
+    # Compute short (6-char) MD5 digest of file
+    #
+    # @param file_path [String] path to file
+    # @return [String] first 6 characters of MD5 hex digest
+    # @raise [Errno::ENOENT] if file doesn't exist
+    def self.short_digest(file_path)
+      Digest::MD5.file(file_path).hexdigest[0...6]
+    end
+  end
+end

data/lib/jekyll-auto-thumbnails/generator.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module JekyllAutoThumbnails
+  # Thumbnail generation via ImageMagick
+  class Generator
+    # Initialize generator
+    #
+    # @param config [Configuration] configuration
+    # @param site_source [String] Jekyll site source directory
+    def initialize(config, site_source)
+      @config = config
+      @site_source = site_source
+    end
+
+    # Check if ImageMagick is available (cross-platform)
+    #
+    # @return [Boolean] true if convert command found in PATH
+    def imagemagick_available?
+      cmd_name = Gem.win_platform? ? "convert.exe" : "convert"
+      path_dirs = ENV["PATH"].to_s.split(File::PATH_SEPARATOR)
+
+      path_dirs.any? do |dir|
+        executable = File.join(dir, cmd_name)
+        File.executable?(executable)
+      end
+    end
+
+    # Generate thumbnail (with caching)
+    #
+    # @param url [String] image URL
+    # @param width [Integer, nil] target width
+    # @param height [Integer, nil] target height
+    # @return [String, nil] path to cached thumbnail or nil if failed
+    def generate(url, width, height)
+      # Resolve source file
+      source_path = UrlResolver.to_filesystem_path(url, @site_source)
+      return nil unless source_path && File.exist?(source_path)
+
+      # Compute digest
+      digest = DigestCalculator.short_digest(source_path)
+
+      # Build thumbnail filename
+      basename = File.basename(source_path, File.extname(source_path))
+      ext = File.extname(source_path)
+      thumb_filename = build_thumbnail_filename(basename, digest, width, height, ext)
+
+      # Check cache
+      cached_path = File.join(@config.cache_dir, thumb_filename)
+      return cached_path if File.exist?(cached_path)
+
+      # Generate
+      FileUtils.mkdir_p(@config.cache_dir)
+      success = shell_generate(source_path, cached_path, width, height)
+
+      return nil unless success
+
+      # Check if thumbnail is larger than original
+      if File.size(cached_path) > File.size(source_path)
+        Jekyll.logger.warn "AutoThumbnails:",
+                           "Thumbnail larger than original (#{File.size(cached_path)} > #{File.size(source_path)}), " \
+                           "deleting #{cached_path}"
+        FileUtils.rm_f(cached_path)
+        return nil
+      end
+
+      cached_path
+    end
+
+    # Build thumbnail filename
+    #
+    # @param basename [String] image basename (no extension)
+    # @param digest [String] 6-char MD5 digest
+    # @param width [Integer, nil] width
+    # @param height [Integer, nil] height
+    # @param ext [String] file extension
+    # @return [String] thumbnail filename
+    def build_thumbnail_filename(basename, digest, width, height, ext)
+      width_str = width || ""
+      height_str = height || ""
+      "#{basename}_thumb-#{digest}-#{width_str}x#{height_str}#{ext}"
+    end
+
+    private
+
+    # Generate thumbnail using ImageMagick
+    #
+    # @param source_path [String] source image path
+    # @param dest_path [String] destination thumbnail path
+    # @param width [Integer, nil] target width
+    # @param height [Integer, nil] target height
+    # @return [Boolean] true if successful
+    def shell_generate(source_path, dest_path, width, height)
+      geometry = build_geometry(width, height)
+      ext = File.extname(source_path)
+
+      # Build command array (no shell interpretation)
+      cmd = ["convert", source_path, "-resize", geometry]
+
+      # Add quality for lossy formats
+      if quality_needed?(ext)
+        cmd << "-quality"
+        cmd << @config.quality.to_s
+      end
+
+      cmd << dest_path
+
+      # Call system with array (bypasses shell)
+      system(*cmd)
+    end
+
+    # Build ImageMagick geometry string
+    #
+    # @param width [Integer, nil] target width
+    # @param height [Integer, nil] target height
+    # @return [String] geometry string (e.g., "400x300>")
+    def build_geometry(width, height)
+      width_str = width || ""
+      height_str = height || ""
+      "#{width_str}x#{height_str}>"
+    end
+
+    # Check if quality parameter needed for image format
+    #
+    # @param ext [String] file extension
+    # @return [Boolean] true if quality parameter should be used
+    def quality_needed?(ext)
+      %w[.jpg .jpeg].include?(ext.downcase)
+    end
+  end
+end

data/lib/jekyll-auto-thumbnails/hooks.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module JekyllAutoThumbnails
+  # Jekyll hook integration
+  module Hooks
+    # Initialize optimization system
+    #
+    # @param site [Jekyll::Site] Jekyll site
+    def self.initialize_system(site)
+      config = Configuration.new(site)
+      return unless config.enabled?
+
+      site.data["auto_thumbnails_config"] = config
+      site.data["auto_thumbnails_registry"] = Registry.new
+      site.data["auto_thumbnails_generator"] = Generator.new(config, site.source)
+
+      Jekyll.logger.info "AutoThumbnails:", "System initialized"
+    end
+
+    # Process site - scan, generate, replace
+    #
+    # @param site [Jekyll::Site] Jekyll site
+    def self.process_site(site)
+      config = site.data["auto_thumbnails_config"]
+      return unless config&.enabled?
+
+      registry = site.data["auto_thumbnails_registry"]
+      generator = site.data["auto_thumbnails_generator"]
+
+      # Check ImageMagick
+      unless generator.imagemagick_available?
+        Jekyll.logger.warn "AutoThumbnails:", "ImageMagick not found - skipping"
+        return
+      end
+
+      # Scan all documents and pages
+      (site.documents + site.pages).each do |doc|
+        next unless doc.output
+
+        Scanner.scan_html(doc.output, registry, config, site.source)
+      end
+
+      Jekyll.logger.info "AutoThumbnails:", "Found #{registry.entries.size} images to optimize"
+
+      # Generate thumbnails
+      url_map = {}
+      registry.entries.each do |url, requirements|
+        cached_path = generator.generate(url, requirements[:width], requirements[:height])
+
+        if cached_path
+          # Build thumbnail URL (use forward slashes for URLs, not File.join)
+          thumb_filename = File.basename(cached_path)
+          url_dir = File.dirname(url)
+          # Ensure URL uses forward slashes (cross-platform URLs)
+          thumb_url = if url_dir == "."
+                        "/#{thumb_filename}"
+                      else
+                        "#{url_dir}/#{thumb_filename}"
+                      end
+          url_map[url] = thumb_url
+        else
+          Jekyll.logger.warn "AutoThumbnails:", "Failed to generate thumbnail for #{url}"
+        end
+      end
+
+      # Store url_map for post_write hook
+      site.data["auto_thumbnails_url_map"] = url_map
+
+      # Replace URLs in HTML
+      (site.documents + site.pages).each do |doc|
+        next unless doc.output
+
+        doc.output = replace_urls(doc.output, url_map)
+      end
+
+      Jekyll.logger.info "AutoThumbnails:", "Generated #{url_map.size} thumbnails"
+    end
+
+    # Copy thumbnails from cache to _site
+    #
+    # @param site [Jekyll::Site] Jekyll site
+    def self.copy_thumbnails(site)
+      config = site.data["auto_thumbnails_config"]
+      return unless config&.enabled?
+
+      url_map = site.data["auto_thumbnails_url_map"]
+      return unless url_map && !url_map.empty?
+
+      Jekyll.logger.info "AutoThumbnails:", "Copying #{url_map.size} thumbnails to _site"
+
+      url_map.each_value do |thumb_url|
+        thumb_filename = File.basename(thumb_url)
+        cached_path = File.join(config.cache_dir, thumb_filename)
+
+        # Build destination path in _site preserving directory structure
+        dest_path = File.join(site.dest, thumb_url.sub(%r{^/}, ""))
+        dest_dir = File.dirname(dest_path)
+
+        FileUtils.mkdir_p(dest_dir)
+        FileUtils.cp(cached_path, dest_path)
+      end
+
+      Jekyll.logger.info "AutoThumbnails:", "All thumbnails copied"
+    end
+
+    # Replace image URLs in HTML
+    #
+    # @param html [String] HTML content
+    # @param url_map [Hash] original URL => thumbnail URL
+    # @return [String] modified HTML
+    def self.replace_urls(html, url_map)
+      # Return early if no replacements needed
+      return html if url_map.empty?
+
+      doc = Nokogiri::HTML(html)
+
+      doc.css("article img").each do |img|
+        src = img["src"]
+        next unless src
+
+        # Find thumbnail URL for this image
+        thumb_url = url_map[src]
+        img["src"] = thumb_url if thumb_url
+      end
+
+      # Serialize with encoding declaration to match Jekyll output
+      doc.to_html
+    end
+
+    private_class_method :replace_urls
+  end
+end
+
+# Register Jekyll hooks
+Jekyll::Hooks.register :site, :post_read do |site|
+  JekyllAutoThumbnails::Hooks.initialize_system(site)
+end
+
+Jekyll::Hooks.register :site, :post_render do |site|
+  JekyllAutoThumbnails::Hooks.process_site(site)
+end
+
+Jekyll::Hooks.register :site, :post_write do |site|
+  JekyllAutoThumbnails::Hooks.copy_thumbnails(site)
+end

data/lib/jekyll-auto-thumbnails/registry.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module JekyllAutoThumbnails
+  # Image requirement registry
+  #
+  # Tracks images needing thumbnails and their required dimensions.
+  # Handles duplicate registrations by keeping the largest dimensions.
+  class Registry
+    # Initialize empty registry
+    def initialize
+      @entries = {}
+    end
+
+    # Register an image with required dimensions
+    #
+    # @param url [String] image URL
+    # @param width [Integer, nil] required width
+    # @param height [Integer, nil] required height
+    def register(url, width, height)
+      existing = @entries[url]
+
+      @entries[url] = if existing
+                        # Update to max dimensions
+                        {
+                          width: [existing[:width], width].compact.max,
+                          height: [existing[:height], height].compact.max
+                        }
+                      else
+                        { width: width, height: height }
+                      end
+    end
+
+    # Check if image is registered
+    #
+    # @param url [String] image URL
+    # @return [Boolean] true if registered
+    def registered?(url)
+      @entries.key?(url)
+    end
+
+    # Get requirements for image
+    #
+    # @param url [String] image URL
+    # @return [Hash, nil] {width:, height:} or nil if not registered
+    def requirements_for(url)
+      @entries[url]&.dup
+    end
+
+    # Get all registered entries
+    #
+    # @return [Hash] url => {width:, height:}
+    def entries
+      @entries.dup
+    end
+  end
+end

data/lib/jekyll-auto-thumbnails/scanner.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "open3"
+
+module JekyllAutoThumbnails
+  # HTML scanning for images
+  module Scanner
+    # Scan HTML for images needing optimization
+    #
+    # @param html [String] HTML content
+    # @param registry [Registry] image registry
+    # @param config [Configuration] configuration
+    # @param site_source [String] Jekyll site source (optional, for unsized image checking)
+    def self.scan_html(html, registry, config, site_source = nil)
+      doc = Nokogiri::HTML(html)
+
+      # Only process images in <article> tags
+      doc.css("article img").each do |img|
+        src = img["src"]
+        next unless src
+        next if UrlResolver.external?(src)
+
+        # Check for explicit dimensions
+        width = parse_dimension(img["width"])
+        height = parse_dimension(img["height"])
+
+        if width || height
+          # Explicitly sized - calculate missing dimension if needed
+          if site_source && (width.nil? || height.nil?)
+            Jekyll.logger.debug "AutoThumbnails:", "Calculating dimensions for #{src} (#{width}x#{height})"
+            width, height = calculate_dimensions(src, width, height, site_source)
+            Jekyll.logger.debug "AutoThumbnails:", "Calculated: #{width}x#{height}"
+          end
+
+          # Skip if dimensions match original (no thumbnail needed)
+          if site_source && dimensions_match_original?(src, width, height, site_source)
+            Jekyll.logger.debug "AutoThumbnails:", "Skipping #{src} - dimensions match original"
+            next
+          end
+
+          Jekyll.logger.debug "AutoThumbnails:", "Registering #{src} at #{width}x#{height}"
+          registry.register(src, width, height)
+        elsif site_source && (config.max_width || config.max_height)
+          # Unsized but max config exists - check actual dimensions
+          check_and_register_oversized(src, registry, config, site_source)
+        end
+      end
+    end
+
+    # Check if image exceeds max dimensions and register if so
+    #
+    # @param url [String] image URL
+    # @param registry [Registry] image registry
+    # @param config [Configuration] configuration
+    # @param site_source [String] site source directory
+    def self.check_and_register_oversized(url, registry, config, site_source)
+      file_path = UrlResolver.to_filesystem_path(url, site_source)
+      return unless file_path && File.exist?(file_path)
+
+      actual_width, actual_height = image_dimensions(file_path)
+      return unless actual_width && actual_height
+
+      # Check if exceeds max dimensions
+      exceeds_width = config.max_width && actual_width > config.max_width
+      exceeds_height = config.max_height && actual_height > config.max_height
+
+      return unless exceeds_width || exceeds_height
+
+      # Register with max dimensions (preserving aspect ratio logic in Generator)
+      registry.register(url, config.max_width, config.max_height)
+    end
+
+    # Get image dimensions from file
+    #
+    # @param file_path [String] path to image file
+    # @return [Array<Integer, Integer>, nil] [width, height] or nil
+    def self.image_dimensions(file_path)
+      # Use ImageMagick identify command (shell-free, cross-platform)
+      # Use [0] to get only first frame (important for animated GIFs)
+      output, status = Open3.capture2e("identify", "-format", "%wx%h", "#{file_path}[0]")
+      return nil unless status.success? && !output.strip.empty?
+
+      width, height = output.strip.split("x").map(&:to_i)
+      [width, height]
+    rescue StandardError
+      nil
+    end
+
+    # Calculate missing dimension based on aspect ratio
+    #
+    # @param url [String] image URL
+    # @param width [Integer, nil] specified width
+    # @param height [Integer, nil] specified height
+    # @param site_source [String] site source directory
+    # @return [Array<Integer, Integer>] [width, height] with calculated dimension
+    def self.calculate_dimensions(url, width, height, site_source)
+      file_path = UrlResolver.to_filesystem_path(url, site_source)
+      return [width, height] unless file_path && File.exist?(file_path)
+
+      actual_width, actual_height = image_dimensions(file_path)
+      return [width, height] unless actual_width && actual_height
+
+      # Calculate missing dimension preserving aspect ratio
+      if width && !height
+        # Width specified, calculate height
+        aspect_ratio = actual_height.to_f / actual_width
+        height = (width * aspect_ratio).round
+      elsif height && !width
+        # Height specified, calculate width
+        aspect_ratio = actual_width.to_f / actual_height
+        width = (height * aspect_ratio).round
+      end
+
+      [width, height]
+    end
+
+    # Parse dimension attribute (width or height)
+    #
+    # @param value [String, nil] attribute value
+    # @return [Integer, nil] parsed integer or nil
+    def self.parse_dimension(value)
+      return nil if value.nil? || value.empty?
+
+      # Strip non-numeric characters (e.g., "300px" -> 300)
+      numeric = value.to_s.gsub(/[^\d]/, "")
+      return nil if numeric.empty?
+
+      numeric.to_i
+    end
+
+    # Check if requested dimensions match original dimensions
+    #
+    # @param url [String] image URL
+    # @param width [Integer] requested width
+    # @param height [Integer] requested height
+    # @param site_source [String] site source directory
+    # @return [Boolean] true if dimensions match original
+    def self.dimensions_match_original?(url, width, height, site_source)
+      file_path = UrlResolver.to_filesystem_path(url, site_source)
+      return false unless file_path && File.exist?(file_path)
+
+      actual_width, actual_height = image_dimensions(file_path)
+      return false unless actual_width && actual_height
+
+      width == actual_width && height == actual_height
+    end
+
+    private_class_method :check_and_register_oversized, :calculate_dimensions, :parse_dimension,
+                         :dimensions_match_original?
+  end
+end