jekyll-compress-images 1.3 → 1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0acb0ae2e739816700bc6fb491d44d272ffb7dad3bd0f725b8b90e61f9589709
-  data.tar.gz: e2d6ff51708865f6ba43a21f9c6a2f93ff5f1867a9b0aac31253999e31cdd97b
+  metadata.gz: 704a828325e4c1d9396206750da62503785ac90033f86d8d36429d3a5ab04a59
+  data.tar.gz: 657104fb5242f0a3c5948278b4718762d41cc2d73c5423414205ade8e3d7eb2a
 SHA512:
-  metadata.gz: d1cbccb9e8ba180bada845b8b8fcbaf6dc5e5be4ce4d092ff7d7d024d06822f7c44135be321b9bc76d063d864aafded65ebae9289b16ee770fe22b68731ac53a
-  data.tar.gz: 4a5536237ae2205c4ca9372a1bea7e907d831943d47dd0c3cf8bcc59f53e11a6ccb492ae8908d2438bd60c62f2f8ef41f90352c256f4198cbb63b41641b8fc12
+  metadata.gz: 86ae385b510546688f9e72709c9f8f10b1f60c0e4b09bad40cc1fca06c5b3a39efc95262f704b2c0a98880225444a10a049a24228c76360766d0acf56099f65a
+  data.tar.gz: 29e08242a343da1a4476324336700ab579a20e039de62db5241a39740c04636c282d4988e0e11d8c860ded80709c3b9900aa864987f9cf88f6cb8f83310264e6

data/README.md

@@ -3,7 +3,7 @@
 
 # jekyll-compress-images
 
-Plugin for compressing/optimizing images (jpg, png, gif, svg).
+Plugin for compressing/optimizing images (jpg, png, gif, svg), and optionally creating WebP and AVIF versions.
 
 # Installation
 
@@ -40,8 +40,60 @@ compress_images:
   images_path: "assets/img/**/*.{gif,png,jpg,jpeg,svg}"  # relative to your site source
   cache_file: "_compress_images_cache.yml"               # remembers which images are already optimized
   threads: 8                                              # defaults to the number of CPU cores
+  overwrite_originals: true                               # false = only the published images in _site are compressed
+  webp: false                                             # create .webp versions of jpg/png images
+  webp_quality: 80
+  avif: false                                             # create .avif versions of jpg/png images
+  avif_quality: 60
 ```
 
+## Keep your original images
+
+By default, images are compressed **in place**, in your source folder. If you'd rather keep high-quality originals in your repo and only publish compressed ones, set:
+
+```yaml
+compress_images:
+  overwrite_originals: false
+```
+
+Compressed copies are kept in `.jekyll-cache/compress-images/`, so only the first build is slow. Your source images are never touched, and `_compress_images_cache.yml` isn't needed.
+
+## WebP and AVIF
+
+WebP and AVIF are usually much smaller than JPG/PNG. Turn them on with:
+
+```yaml
+compress_images:
+  webp: true
+  avif: true
+```
+
+This needs `cwebp` and `avifenc` (version 1.0 or newer) installed:
+
+- macOS: `brew install webp libavif`
+- Ubuntu 24.04+/Debian 13+ (and GitHub Actions `ubuntu-latest`): `sudo apt-get install webp libavif-bin`
+
+For every jpg/png, a `.webp` and `.avif` file is added next to it in `_site`, e.g. `hero.jpg.webp`. If one comes out bigger than the original, it's skipped. Your source folder isn't touched.
+
+Browsers only use these files if your HTML asks for them, so use the `picture` tag instead of `<img>`:
+
+```liquid
+{% picture assets/img/hero.jpg alt="Hero" class="cover" loading="lazy" %}
+{% picture {{ page.image }} alt="{{ page.title }}" %}
+```
+
+which becomes:
+
+```html
+<picture>
+  <source srcset="/assets/img/hero.jpg.avif" type="image/avif">
+  <source srcset="/assets/img/hero.jpg.webp" type="image/webp">
+  <img src="/assets/img/hero.jpg" alt="Hero" class="cover" loading="lazy">
+</picture>
+```
+
+Anything after the image path is added to the `<img>`. Browsers that don't support AVIF/WebP use the original image. If you already use another plugin with a `picture` tag (like jekyll_picture_tag), that one is kept.
+
 ## image_optim options
 
 You can pass [image_optim](https://github.com/toy/image_optim) options by using:
@@ -53,7 +105,7 @@ imageoptim:
   verbose: false
 ```
 
-SVG optimization uses [svgo](https://github.com/svg/svgo), which isn't bundled. Install it with `npm install -g svgo`, or set `svgo: false` to hide the warning.
+SVG optimization uses [svgo](https://github.com/svg/svgo), which isn't bundled. It's used automatically when it's installed (`npm install -g svgo`).
 
 # Usage
 
@@ -61,8 +113,9 @@ On `jekyll serve` or `jekyll build`, compression will run. If your images are al
 
 Good to know:
 
-- Images are optimized **in place**, in your source folder. Commit them afterwards.
+- Images are optimized **in place**, in your source folder (unless you set `overwrite_originals: false`). Commit them afterwards.
 - Commit `_compress_images_cache.yml` too, so other machines (and CI) know which images are already done.
+- Each build prints a summary like `Optimized 12 images, saved 3.4 MB`. Run with `--verbose` to see every image.
 - If you replace an image with a new file, it will be optimized again automatically.
 
 # Development

data/lib/jekyll-compress-images.rb

@@ -1,6 +1,10 @@
+require "cgi"
 require "digest"
 require "etc"
+require "fileutils"
+require "open3"
 require "pathname"
+require "set"
 require "yaml"
 require "image_optim"
 require "image_optim_pack"
@@ -13,52 +17,248 @@ module Jekyll
     LOG_TOPIC = "CompressImages:".freeze
 
     DEFAULT_OPTIONS = {
-      "cache_file"  => "_compress_images_cache.yml",
-      "images_path" => "assets/img/**/*.{gif,png,jpg,jpeg,svg}",
-      "threads"     => Etc.nprocessors
+      "cache_file"          => "_compress_images_cache.yml",
+      "images_path"         => "assets/img/**/*.{gif,png,jpg,jpeg,svg}",
+      "threads"             => Etc.nprocessors,
+      "overwrite_originals" => true,
+      "webp"                => false,
+      "webp_quality"        => 80,
+      "avif"                => false,
+      "avif_quality"        => 60
     }.freeze
 
     DEFAULT_IMAGEOPTIM_OPTIONS = {
       "pngout"  => false,
-      "svgo"    => true,
       "verbose" => false
     }.freeze
 
+    # Extra formats we can create, the tool that makes them and how to install it
+    VARIANTS = {
+      "webp" => { "tool" => "cwebp",   "install" => "brew install webp / apt install webp" },
+      "avif" => { "tool" => "avifenc", "install" => "brew install libavif / apt install libavif-bin" }
+    }.freeze
+
+    # Formats cwebp and avifenc can read
+    CONVERTIBLE = %w[.jpg .jpeg .png].freeze
+
     def generate(site)
       @site = site
       @config = DEFAULT_OPTIONS.merge(site.config["compress_images"] || {})
-      @cache_path = File.expand_path(@config["cache_file"], site.source)
+      @mutex = Mutex.new
+      @stats = { "optimized" => 0, "saved" => 0, "created" => 0 }
+      @used_cache_files = Set.new
+      @digests = {}
 
       images = Dir.glob(File.expand_path(@config["images_path"], site.source)).select { |path| File.file?(path) }.sort
+
+      # Look these up before optimize_copies points them at the cache folder
+      files = published_files(images)
+
+      if @config["overwrite_originals"]
+        optimize_originals(images)
+      else
+        optimize_copies(files)
+      end
+      create_variants(files)
+      clean_cache_dir
+      log_summary
+    end
+
+    private
+
+    # Optimizes images in the source folder and remembers them in the cache file
+    def optimize_originals(images)
+      @cache_path = File.expand_path(@config["cache_file"], site.source)
       @original_cache = load_cache
       # Only keep entries for images that still exist, so deleted images drop out of the cache
       @cache = @original_cache.select { |key, _| images.any? { |path| relative(path) == key } }
-      @mutex = Mutex.new
 
       pending = images.reject { |path| @cache[relative(path)] == digest(path) }
-      pending.in_threads([@config["threads"].to_i, 1].max).each { |path| optimize(path) } if pending.any?
+      in_parallel(pending) do |path|
+        safely("optimize", path) do
+          optimize(path)
+          # Store the digest of the optimized file, so we only run again when the image is replaced
+          new_digest = digest(path)
+          @mutex.synchronize { @cache[relative(path)] = new_digest }
+        end
+      end
     ensure
       save_cache if @cache
     end
 
-    private
+    # Leaves the originals untouched. Optimized copies live in the cache folder
+    # and Jekyll publishes them instead of the originals.
+    def optimize_copies(files)
+      pending = files.keys.reject { |path| File.file?(cached_path(path, File.extname(path))) }
+      pending = pending.uniq { |path| cached_path(path, File.extname(path)) }
 
-    def image_optim
-      @image_optim ||= ImageOptim.new(DEFAULT_IMAGEOPTIM_OPTIONS.merge(@site.config["imageoptim"] || {}))
+      in_parallel(pending) do |path|
+        safely("optimize", path) do
+          write_atomically(cached_path(path, File.extname(path))) do |tmp|
+            FileUtils.cp(path, tmp)
+            optimize(tmp, path)
+          end
+        end
+      end
+
+      files.each do |path, file|
+        copy = cached_path(path, File.extname(path))
+        file.define_singleton_method(:path) { copy } if File.file?(copy)
+      end
+    end
+
+    # Creates .webp/.avif files next to the images, e.g. hero.jpg -> hero.jpg.webp
+    def create_variants(files)
+      formats = VARIANTS.keys.select { |format| @config[format] && tool_installed?(format) }
+      return if formats.empty?
+
+      images = files.keys.select { |path| CONVERTIBLE.include?(File.extname(path).downcase) }
+      jobs = images.product(formats)
+      pending = jobs.reject { |path, format| File.file?(cached_path(path, ".#{format}")) || File.file?(skip_marker(path, format)) }
+      pending = pending.uniq { |path, format| cached_path(path, ".#{format}") }
+
+      in_parallel(pending) do |path, format|
+        safely("create #{format} for", path) { convert(path, format) }
+      end
+
+      jobs.each do |path, format|
+        variant = cached_path(path, ".#{format}")
+        next unless File.file?(variant)
+
+        file = StaticFile.new(site, site.source, File.dirname("/#{relative(path)}"), "#{File.basename(path)}.#{format}")
+        file.define_singleton_method(:path) { variant }
+        site.static_files << file
+      end
+    end
+
+    def convert(path, format)
+      target = cached_path(path, ".#{format}")
+      write_atomically(target) do |tmp|
+        output, status = Open3.capture2e(*convert_command(format, path, tmp))
+        raise output.strip unless status.success?
+
+        # Not worth publishing if it's bigger than the original, the picture tag then falls back to it
+        if File.size(tmp) >= File.size(path)
+          FileUtils.touch(skip_marker(path, format))
+          FileUtils.rm_f(tmp)
+        else
+          Jekyll.logger.debug LOG_TOPIC, "Created #{relative(path)}.#{format}"
+          @mutex.synchronize { @stats["created"] += 1 }
+        end
+      end
+    end
+
+    def convert_command(format, input, output)
+      quality = @config["#{format}_quality"].to_s
+      case format
+      when "webp" then ["cwebp", "-quiet", "-q", quality, "-metadata", "icc", input, "-o", output]
+      when "avif" then ["avifenc", "-q", quality, "-s", "6", "-j", "all", input, output]
+      end
     end
 
-    def optimize(path)
+    def optimize(path, original = path)
       size_before = File.size(path)
       image_optim.optimize_image!(path)
-      size_after = File.size(path)
-      saved = size_before.zero? ? 0 : ((size_before - size_after) * 100.0 / size_before).round(1)
-      Jekyll.logger.info LOG_TOPIC, "Optimized #{relative(path)} (-#{saved}%)"
+      saved = size_before - File.size(path)
+      Jekyll.logger.debug LOG_TOPIC, "Optimized #{relative(original)} (-#{percent(saved, size_before)}%)"
+      @mutex.synchronize do
+        @stats["optimized"] += 1
+        @stats["saved"] += saved
+      end
+    end
+
+    def site
+      @site
+    end
+
+    def image_optim
+      @image_optim ||= ImageOptim.new(imageoptim_options)
+    end
+
+    # svgo isn't bundled, so only turn it on when it's installed (unless the site config says otherwise)
+    def imageoptim_options
+      DEFAULT_IMAGEOPTIM_OPTIONS.merge("svgo" => executable?("svgo") || ENV.key?("SVGO_BIN"))
+                                .merge(site.config["imageoptim"] || {})
+    end
+
+    # Static files Jekyll will publish at their usual URL, by source path
+    def published_files(images)
+      by_path = images.to_h { |path| [path, nil] }
+      site.static_files.each_with_object({}) do |file, found|
+        path = File.expand_path(file.path)
+        found[path] = file if by_path.key?(path) && file.url == "/#{relative(path)}"
+      end
+    end
+
+    def in_parallel(items, &block)
+      items.in_threads([@config["threads"].to_i, 1].max).each(&block)
+    end
 
-      # Store the digest of the optimized file, so we only run again when the image is replaced
-      new_digest = digest(path)
-      @mutex.synchronize { @cache[relative(path)] = new_digest }
+    def safely(action, path)
+      yield
     rescue StandardError => e
-      Jekyll.logger.warn LOG_TOPIC, "Could not optimize #{relative(path)}: #{e.message}"
+      Jekyll.logger.warn LOG_TOPIC, "Could not #{action} #{relative(path)}: #{e.message}"
+    end
+
+    # Writes to a temporary file first, so an interrupted build never leaves a half-done file in the cache
+    def write_atomically(target)
+      FileUtils.mkdir_p(File.dirname(target))
+      tmp = "#{target}.tmp#{File.extname(target)}"
+      yield tmp
+      File.rename(tmp, target) if File.file?(tmp)
+    ensure
+      FileUtils.rm_f(tmp) if tmp
+    end
+
+    def cache_dir
+      @cache_dir ||= File.join(File.expand_path(site.config["cache_dir"] || ".jekyll-cache", site.source), "compress-images")
+    end
+
+    def cached_path(path, extension)
+      @digests[path] ||= digest(path)
+      File.join(cache_dir, "#{@digests[path]}#{extension}").tap { |file| @used_cache_files << file }
+    end
+
+    def skip_marker(path, format)
+      "#{cached_path(path, ".#{format}")}.skip".tap { |file| @used_cache_files << file }
+    end
+
+    def clean_cache_dir
+      return unless File.directory?(cache_dir)
+
+      (Dir.glob(File.join(cache_dir, "*")).to_set - @used_cache_files).each { |file| FileUtils.rm_f(file) }
+    end
+
+    def tool_installed?(format)
+      tool = VARIANTS[format]["tool"]
+      return true if executable?(tool)
+
+      Jekyll.logger.warn LOG_TOPIC, "#{format} is enabled but `#{tool}` isn't installed (#{VARIANTS[format]["install"]})"
+      false
+    end
+
+    def executable?(name)
+      ENV["PATH"].to_s.split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, name)) }
+    end
+
+    def log_summary
+      if @stats["optimized"].positive?
+        Jekyll.logger.info LOG_TOPIC, "Optimized #{@stats["optimized"]} #{@stats["optimized"] == 1 ? "image" : "images"}, saved #{human_size(@stats["saved"])}"
+      end
+      return unless @stats["created"].positive?
+
+      Jekyll.logger.info LOG_TOPIC, "Created #{@stats["created"]} WebP/AVIF #{@stats["created"] == 1 ? "file" : "files"}"
+    end
+
+    def human_size(bytes)
+      return "#{bytes} B" if bytes < 1024
+      return "#{(bytes / 1024.0).round(1)} KB" if bytes < 1024 * 1024
+
+      "#{(bytes / 1024.0 / 1024).round(1)} MB"
+    end
+
+    def percent(part, whole)
+      whole.zero? ? 0 : (part * 100.0 / whole).round(1)
     end
 
     def digest(path)
@@ -66,7 +266,7 @@ module Jekyll
     end
 
     def relative(path)
-      Pathname.new(path).relative_path_from(Pathname.new(@site.source)).to_s
+      Pathname.new(path).relative_path_from(Pathname.new(site.source)).to_s
     end
 
     def load_cache
@@ -86,4 +286,37 @@ module Jekyll
       File.write(@cache_path, @cache.sort.to_h.to_yaml)
     end
   end
+
+  # {% picture assets/img/hero.jpg alt="Hero" class="cover" %}
+  # Uses the AVIF/WebP versions when they exist, and falls back to the original image
+  class CompressImagesPictureTag < Liquid::Tag
+    def initialize(tag_name, markup, tokens)
+      super
+      @markup = markup
+    end
+
+    def render(context)
+      site = context.registers[:site]
+      src, attributes = Liquid::Template.parse(@markup).render(context).strip.split(/\s+/, 2)
+      raise ArgumentError, "{% picture %} needs an image path, e.g. {% picture assets/img/hero.jpg alt=\"Hero\" %}" if src.to_s.empty?
+
+      url = "/#{src.sub(%r!\A/+!, "")}"
+      published = context.registers[:compress_images_urls] ||= site.static_files.map(&:url).to_set
+      sources = %w[avif webp].select { |format| published.include?("#{url}.#{format}") }.map do |format|
+        %(<source srcset="#{html_url(site, "#{url}.#{format}")}" type="image/#{format}">)
+      end
+      img = %(<img src="#{html_url(site, url)}"#{" #{attributes}" if attributes}>)
+
+      sources.empty? ? img : "<picture>#{sources.join}#{img}</picture>"
+    end
+
+    private
+
+    def html_url(site, url)
+      CGI.escapeHTML("#{site.config["baseurl"].to_s.chomp("/")}#{url}".gsub(" ", "%20"))
+    end
+  end
 end
+
+# Don't take over the tag if another plugin (like jekyll_picture_tag) already registered it
+Liquid::Template.register_tag("picture", Jekyll::CompressImagesPictureTag) unless Liquid::Template.tags["picture"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-compress-images
 version: !ruby/object:Gem::Version
-  version: '1.3'
+  version: '1.4'
 platform: ruby
 authors:
 - Valerija Spasojevic
@@ -76,14 +76,14 @@ dependencies:
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
 - !ruby/object:Gem::Dependency
@@ -116,6 +116,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/valerijaspasojevic/jekyll-compress-images
   changelog_uri: https://github.com/valerijaspasojevic/jekyll-compress-images/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -134,5 +135,6 @@ requirements: []
 rubygems_version: 3.4.15
 signing_key:
 specification_version: 4
-summary: Jekyll plugin for compress/optimize images (jpg, png, gif, svg)
+summary: Jekyll plugin for compressing images (jpg, png, gif, svg), with optional
+  WebP and AVIF versions
 test_files: []