jekyll-imgwh 1.2.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97ed49b87d0bbe492af4ed8522310efabdc9746d7704dda82cbacd7b86aa23de
-  data.tar.gz: 3cf0726edda511915644e2c8fff32ef114caa347debf38a39ef20b0a59e2caf4
+  metadata.gz: 7efeac12ff14b51441a976e3ea7b7d9c286d9429d59aeebfae72ed8666f7313c
+  data.tar.gz: 69f883d0d544d950cff948d71aeb5ff5333f11ad2810458b30a171192b9c50f4
 SHA512:
-  metadata.gz: 46cd039ca46ee40493efde196c88e47970c85f422c7e061af8403119cb946571770e1a84d0239d20c5aa2aee3f003102e6cc2640e7c1c9b22ebacfbd5001ce56
-  data.tar.gz: 5c259abe5bf29223445f2b2a59f151076015847b97ef740f4730ffc64ea6374e4e62e431e046bea936f0d0926e3c46d0290d0f7ed5937ec97bd4c6c35e003596
+  metadata.gz: 1a0e4b3815bd80f84029a9f3ee4ca5237a9d70f4aa14f930914ddd134298eb1668da03b49e8a643aae8311c4cb4d5d970eea9af4d6ffbceaabf93360c07d2a66
+  data.tar.gz: 152ed5a03712c50cd8e412cd5c9892cbeac5317b7605489f0124df1a59d800908d4046b7704f8c035384f668a30988d89ebfe9ed6ceaa18f211d7393a79e9122

data/README.md

@@ -0,0 +1,208 @@
+[![Gem Version](https://badge.fury.io/rb/jekyll-imgwh.svg)](https://badge.fury.io/rb/jekyll-imgwh)
+
+A [Jekyll](https://jekyllrb.com/) plugin to simplify maintenance of the images on the site.
+
+It provides a [Liquid tag `imgwh`](#liquid-tag) for `<img>` elements, which ensures image still exists and automatically fills `width` and `height` attributes allowing image to take up space before it loads, to mitigate content layout shifts.
+
+It also provides a [Liquid filter `imgwh`](#liquid-filter), which returns image size as an array.
+
+# Installation
+
+Add preferred variant from the following ones to your site's `Gemfile` and run `bundle install`:
+
+```ruby
+gem "jekyll-imgwh", group: :jekyll_plugins
+gem "jekyll-imgwh", group: :jekyll_plugins, git: "https://github.com/ojuuji/jekyll-imgwh"
+gem "jekyll-imgwh", group: :jekyll_plugins, path: "/local/path/to/jekyll-imgwh"
+```
+
+# Usage
+
+## Liquid Tag
+
+This plugin exposes Liquid tag `imgwh` with the following syntax:
+
+```liquid
+{% imgwh <src> [<rest>] %}
+```
+
+i.e. `<src>` is required and `<rest>` is optional. They both can include Liquid markup.
+
+After rendering, `<rest>` is added to generated HTML `<img>` element as-is, and `<src>` is used as a value for `src` attribute.
+
+Plugin extracts size of the referenced image and automatically sets `width` and `height` attributes in the generated HTML `<img>` element.
+
+Extra whitespace around `<src>` and `<rest>` is stripped.
+
+Example:
+
+```liquid
+{%    imgwh     "/assets/{{ site.title | slugify }}.png"     alt="{{ site.title }}"       %}
+```
+
+with `site.title="My Site"` and image size 200x67 it would generate the following HTML `<img>` element:
+
+```html
+<img src="/assets/my-site.png" width="200" height="67" alt="My Site">
+```
+
+### Quotes and Whitespace
+
+`<src>` can be specified with single quotes, double quotes, or without quotes. This also defines quotation for the generated `src`, `width`, and `height` attributes: they always use the same quotes as `<src>`:
+
+```
+{% imgwh "/foo.png" %} -> <img src="/foo.png" width="123" height="456">
+{% imgwh '/foo.png' %} -> <img src='/foo.png' width='123' height='456'>
+{% imgwh  /foo.png  %} -> <img src=/foo.png width=123 height=456>
+```
+
+Whitespace can be freely used in single- and double-quoted `<src>`. To use the same quote character in the `<src>` value specify it twice:
+
+```
+{% imgwh "/f{{  'oo'  | append: "".png"" }}" %} -> OK (src="/foo.png")
+{% imgwh "/f{{  'oo'  | append:  ".png"  }}" %} -> ERROR
+{% imgwh '/f{{  'oo'  | append:  ".png"  }}' %} -> ERROR
+{% imgwh '/f{{ ''oo'' | append:  ".png"  }}' %} -> OK (src='/foo.png')
+```
+
+For unquoted `<src>` whitespace is allowed only within Liquid filters (i.e. between `{{` and `}}`):
+
+```
+{% imgwh  /f{{  'oo'  | append:  ".png"  }}  %} -> OK (src=/foo.png)
+{% imgwh  /My Site.png %}                       -> ERROR (tries to open "/My" image)
+{% imgwh  /{{ site.title }}.png %}              -> OK (src=/My Site.png)
+```
+
+Note, in the last example, although plugin did not fire an error, generated `src` attribute is not valid (`<img>` element would use `src=/My`). After rendering Liquid markup in the `<src>` value, plugin does not perform any further normalization for the resulting URI. It is up to the caller to provide correct URI. Plugin only extracts and URL-decodes the path from it.
+
+## Liquid Filter
+
+This plugin exposes a Liquid filter `imgwh`, which returns image size as an array.
+
+It accepts no extra arguments and follows the same [path resolution](#path-resolution) rules as the tag.
+
+For example, if `/assets/images/logo.png` size is 520x348, this template
+
+```liquid
+<pre>
+  {{ "/assets/images/logo.png" | imgwh | inspect }}
+  {{ "/assets/images/logo.png" | imgwh | first }}
+  {{ "/assets/images/logo.png" | imgwh | last }}
+</pre>
+```
+
+would render to
+
+```html
+<pre>
+  [520, 348]
+  520
+  348
+</pre>
+```
+
+## Path Resolution
+
+When the given URI contains scheme, plugin raises an error unless this scheme is listed in [`allowed_schemes`](#allowed_schemes) option (which is empty by default). In case of allowed scheme plugin tries to retrieve image size using the given URI as-is.
+
+For URIs without scheme plugin uses URL-decoded path from URI to find image on the local filesystem.
+
+When the image path is absolute, image is searched relative to the site source directory.
+
+When the image path is relative, image is searched relative to the directory of the current page (`page.dir`).
+
+When the image is not found, and a theme is used, and the path is absolute, image is also searched relative to the theme root directory.
+
+For the local files, like Jekyll itself, plugin does not allow using files outside the source or theme root directories (in fact, plugin uses the path sanitize helpers from Jekyll). It will not be an immediate error in this case (for example, `"/../foo.png"` i.e. one level above the site root), but the image will be searched then in the source directory and the theme root directory no matter how many levels above the site root it is.
+
+## Error Handling
+
+In case plugin cannot determine the image size (due to a syntax error, Liquid template error, image being nonexistent, not an image, etc.) it unconditionally raises an error which stops the site generation.
+
+# Configuration
+
+This plugin uses the following configuration options by default. The configuration file is the same as Jekyll's (which is `_config.yml` unless overridden):
+
+```yml
+jekyll-imgwh:
+  allowed_schemes: []
+  extra_rest:
+```
+
+These are default options i.e. you do not need to specify any of them unless you want to use different value.
+
+### `allowed_schemes`
+
+By default plugin allows only local image files to be used. This means if the given image URI contains non-empty scheme, plugin raises an error.
+
+Option `allowed_schemes` adds exception for the schemes specified in it. For URIs with allowed schemes plugin will try to access them and retrieve the image size.
+
+For example, to allow HTTPS image URLs and [data URLs](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data) use the following:
+
+```yml
+jekyll-imgwh:
+  allowed_schemes: ["data", "https"]
+```
+
+### `extra_rest`
+
+Remember `imgwh` tag syntax? This option injects additional text into all generated HTML `<img>` elements. So we may say the tag syntax is actually this:
+
+```liquid
+{% imgwh <src> <extra_rest> [<rest>] %}
+```
+
+For example, since all generated HTML `<img>` elements get the size attributes, it might be a good idea to set lazy loading for the images:
+
+```yml
+jekyll-imgwh:
+  extra_rest: loading="lazy"
+```
+
+Like `<src>` and `<rest>`, `<extra_rest>` can also include Liquid markup, which is rendered in context of images where `<extra_rest>` is injected.
+
+# Troubleshooting
+
+When error is related to the image image file, plugin mentions the file path in the error message:
+
+```
+$ bundle exec jekyll serve
+<...>
+  Liquid Exception: jekyll-imgwh: 'Y:/ssg/assets/images/foo.png' could not be found in index.html
+<...>
+```
+
+Plugin also logs a lot of info which can help to resolve errors raised by it. Use `jekyll serve --verbose` flag to output this debug info.
+
+For example, for template
+
+```
+{% imgwh "/assets/images/{{ product.key }}.png" alt="{{ project.title }} Logo" class="www-logo" %}
+```
+
+it would print something like this in case of successful generation:
+
+```
+$ bundle exec jekyll serve --verbose
+<...>
+      jekyll-imgwh: ---
+      jekyll-imgwh: content: '"/assets/images/{{ product.key }}.png" alt="{{ project.title }} Logo" class="www-logo"'
+      jekyll-imgwh: src: '/assets/images/{{ product.key }}.png'
+      jekyll-imgwh: rest: 'alt="{{ project.title }} Logo" class="www-logo"'
+      jekyll-imgwh: src rendered: '/assets/images/foo.png'
+      jekyll-imgwh: image path: 'Y:/ssg/assets/images/foo.png'
+      jekyll-imgwh: image size: [128, 64]
+      jekyll-imgwh: rest rendered: 'alt="My Product Logo" class="www-logo"'
+<...>
+```
+
+# Development
+
+To get started with the development:
+
+```sh
+git clone https://github.com/ojuuji/jekyll-imgwh.git
+cd jekyll-imgwh
+bundle install
+bundle exec rspec
+```

data/lib/jekyll/imgwh/helpers.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "fastimage"
+require "jekyll"
+require "jekyll/imgwh/version"
+require "uri"
+
+module Jekyll
+  module Imgwh
+    module Helpers
+      def debug(message)
+        Jekyll.logger.debug "#{NAME}:", message
+      end
+
+      def image_size(src, context)
+        uri = URI(src)
+
+        if uri.scheme.nil?
+          src = resolve_path(CGI.unescape(uri.path), context)
+        else
+          allowed_schemes = context.registers[:site].config.dig(NAME, "allowed_schemes") || []
+          unless allowed_schemes.include?(uri.scheme)
+            raise ArgumentError, "#{NAME}: URIs with '#{uri.scheme}' scheme are not allowed"
+          end
+        end
+
+        FastImage.size(src) or raise LoadError, "#{NAME}: could not get size of image '#{src}'"
+      end
+
+      def resolve_path(path, context)
+        local_path = path.start_with?("/") ? path : File.join(context.registers[:page]["dir"], path)
+        local_path = context.registers[:site].in_source_dir(local_path)
+        debug "image path: '#{local_path}'"
+        return local_path if File.file?(local_path)
+
+        themed_path = context.registers[:site].in_theme_dir(path) if path.start_with?("/")
+        raise LoadError, "#{NAME}: '#{local_path}' could not be found" unless themed_path
+
+        debug "themed image path: '#{themed_path}'"
+        return themed_path if File.file?(themed_path)
+
+        raise LoadError, "#{NAME}: none of '#{local_path}', '#{themed_path}' could be found"
+      end
+    end
+  end
+end

data/lib/jekyll/imgwh/tag.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "jekyll/imgwh/helpers"
+
+module Jekyll
+  module Imgwh
+    class Tag < Liquid::Tag
+      include Helpers
+
+      def initialize(tag_name, content, tokens)
+        super
+
+        @content = content.strip
+
+        if (m = @content.match(%r/^(["'])((?:\1\1|(?!\1).)+)\1(?:\s+(.+))?$/))
+          @quote, @src, @rest = m.captures
+          @src = @src.gsub("#{@quote}#{@quote}", @quote)
+
+        elsif (m = @content.match(%r/^(?!["'])((?:(?!\{\{)\S|\{\{.+?\}\})+)(?:\s+(.+))?$/))
+          @quote = ""
+          @src, @rest = m.captures
+
+        else
+          raise SyntaxError, "#{NAME}: invalid #{tag_name} tag: '#{@content}'"
+        end
+      end
+
+      def render(context)
+        ["---", "content: '#{@content}'", "src: '#{@src}'", "rest: '#{@rest}'"].map { |x| debug x }
+
+        src = Liquid::Template.parse(@src).render(context)
+        debug "src rendered: '#{src}'"
+        img = "<img src=#{quoted src}"
+
+        size = image_size(src, context)
+        debug "image size: #{size}"
+        img << " width=#{quoted size[0]} height=#{quoted size[1]}" << render_rest(context) << ">"
+      end
+
+      private
+
+      def quoted(value)
+        "#{@quote}#{value}#{@quote}"
+      end
+
+      def render_rest(context)
+        rest = +""
+
+        extra_rest = context.registers[:site].config.dig(NAME, "extra_rest")
+        unless extra_rest.nil?
+          extra_rest = Liquid::Template.parse(extra_rest).render(context)
+          debug "extra_rest rendered: '#{extra_rest}'"
+          rest << " #{extra_rest}" unless extra_rest.empty?
+        end
+
+        tag_rest = Liquid::Template.parse(@rest).render(context)
+        debug "rest rendered: '#{tag_rest}'"
+        rest << " #{tag_rest}" unless tag_rest.empty?
+
+        rest
+      end
+    end
+  end
+end

data/lib/{jekyll-imgwh → jekyll/imgwh}/version.rb

@@ -3,6 +3,6 @@
 module Jekyll
   module Imgwh
     NAME = "jekyll-imgwh"
-    VERSION = "1.2.0"
+    VERSION = "1.3.1"
   end
 end

data/lib/jekyll-imgwh.rb

@@ -1,114 +1,18 @@
 # frozen_string_literal: true
 
-require "cgi"
-require "fastimage"
-require "jekyll"
-require "jekyll-imgwh/version"
-require "uri"
+require "jekyll/imgwh/tag"
 
 module Jekyll
   module Imgwh
-    class Tag < Liquid::Tag
-      def initialize(tag_name, content, tokens)
-        super
+    Liquid::Template.register_tag "imgwh", Tag
 
-        @content = content.strip
-
-        if (m = @content.match(%r/^(["'])((?:\1\1|(?!\1).)+)\1(?:\s+(.+))?$/))
-          @quote, @src, @rest = m.captures
-          @src = @src.gsub("#{@quote}#{@quote}", @quote)
-
-        elsif (m = @content.match(%r/^(?!["'])((?:(?!\{\{)\S|\{\{.+?\}\})+)(?:\s+(.+))?$/))
-          @quote = ""
-          @src, @rest = m.captures
-
-        else
-          raise SyntaxError, "#{NAME}: invalid #{tag_name} tag: '#{@content}'"
-        end
-      end
-
-      def debug(message)
-        Jekyll.logger.debug "#{NAME}:", message
-      end
-
-      def render(context)
-        ["---", "content: '#{@content}'", "src: '#{@src}'", "rest: '#{@rest}'"].map { |x| debug x }
-
-        src = Liquid::Template.parse(@src).render(context)
-        debug "src rendered: '#{src}'"
-        img = "<img src=#{quoted src}"
-
-        size = image_size(src, context)
-        debug "image size: #{size}"
-        img << " width=#{quoted size[0]} height=#{quoted size[1]}" << render_rest(context) << ">"
-      end
-
-      private
-
-      def quoted(value)
-        "#{@quote}#{value}#{@quote}"
-      end
-
-      def image_size(src, context)
-        uri = URI(src)
-
-        if uri.scheme.nil?
-          src = resolve_path(CGI.unescape(uri.path), context)
-        else
-          allowed_schemes = context.registers[:site].config.dig(NAME, "allowed_schemes") || []
-          unless allowed_schemes.include?(uri.scheme)
-            raise ArgumentError, "#{NAME}: URIs with '#{uri.scheme}' scheme are not allowed"
-          end
-        end
-
-        FastImage.size(src) or raise LoadError, "#{NAME}: could not get size of image '#{src}'"
-      end
-
-      def render_rest(context)
-        rest = +""
-
-        extra_rest = context.registers[:site].config.dig(NAME, "extra_rest")
-        unless extra_rest.nil?
-          extra_rest = Liquid::Template.parse(extra_rest).render(context)
-          debug "extra_rest rendered: '#{extra_rest}'"
-          rest << " #{extra_rest}" unless extra_rest.empty?
-        end
-
-        tag_rest = Liquid::Template.parse(@rest).render(context)
-        debug "rest rendered: '#{tag_rest}'"
-        rest << " #{tag_rest}" unless tag_rest.empty?
-
-        rest
-      end
-
-      def resolve_path(path, context)
-        local_path = resolve_local_path(path, context)
-        return local_path if File.file?(local_path)
-
-        themed_path = resolve_themed_path(path, context) if path.start_with?("/")
-        raise LoadError, "#{NAME}: '#{local_path}' could not be found" unless themed_path
-
-        return themed_path if File.file?(themed_path)
-
-        raise LoadError, "#{NAME}: none of '#{local_path}', '#{themed_path}' could be found"
-      end
-
-      def resolve_local_path(path, context)
-        path = File.join(context.registers[:page]["dir"], path) unless path.start_with?("/")
-        local_path = File.join(context.registers[:site].source, path)
-        debug "image path: '#{local_path}'"
-
-        local_path
-      end
-
-      def resolve_themed_path(path, context)
-        themed_path = context.registers[:site].in_theme_dir(path)
-        debug "themed image path: '#{themed_path}'"
+    def imgwh(src)
+      image_size(src, @context)
+    end
 
-        themed_path
-      end
+    Liquid::Template.register_filter(self)
 
-      Liquid::Template.register_tag "imgwh", self
-    end
+    # Include after register_filter so they do not leak to Liquid yet are accessible within imgwh()
+    include Helpers
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-imgwh
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.1
 platform: ruby
 authors:
 - Mikalai Ananenka
 bindir: bin
 cert_chain: []
-date: 2025-04-23 00:00:00.000000000 Z
+date: 2025-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fastimage
@@ -107,22 +107,24 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description: 'Jekyll tag for HTML <img> element which verifies that image exists and
-  automatically fills width and height attributes.
-
-  '
 email:
 - ojuuji@gmail.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
 files:
+- README.md
 - lib/jekyll-imgwh.rb
-- lib/jekyll-imgwh/version.rb
+- lib/jekyll/imgwh/helpers.rb
+- lib/jekyll/imgwh/tag.rb
+- lib/jekyll/imgwh/version.rb
 homepage: https://github.com/ojuuji/jekyll-imgwh
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/ojuuji/jekyll-imgwh
+  bug_tracker_uri: https://github.com/ojuuji/jekyll-imgwh/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -139,5 +141,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: Jekyll tag for HTML <img> element with auto filled size attributes
+summary: A tag for <img> element with some automation, and a filter returning image
+  size.
 test_files: []