jekyll-imgwh 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97ed49b87d0bbe492af4ed8522310efabdc9746d7704dda82cbacd7b86aa23de
-  data.tar.gz: 3cf0726edda511915644e2c8fff32ef114caa347debf38a39ef20b0a59e2caf4
+  metadata.gz: '039fab28cf4794e19d2f2d706fe5cba88ac46b13c9330d06308a50f4078382e3'
+  data.tar.gz: 18ed412a7b4cfbebbf1a424022df307691303ac5b067c758d22246214be8140e
 SHA512:
-  metadata.gz: 46cd039ca46ee40493efde196c88e47970c85f422c7e061af8403119cb946571770e1a84d0239d20c5aa2aee3f003102e6cc2640e7c1c9b22ebacfbd5001ce56
-  data.tar.gz: 5c259abe5bf29223445f2b2a59f151076015847b97ef740f4730ffc64ea6374e4e62e431e046bea936f0d0926e3c46d0290d0f7ed5937ec97bd4c6c35e003596
+  metadata.gz: 3c215031cc7b9895731e059b14015dc10e5a565f1d29d2434e3e5b47224b851a09e068753ef5770fd16ef41f714d144d77ebdc31234abb85200f0f58617c7e77
+  data.tar.gz: 972b7d444f27c163706b5527c22615bdddc6f0889d69460af73e0e950b6bd077d4325292cd51301ec1673ba66824108544fd7be29a178e62c8b00a7c199f69b8

data/README.md

@@ -0,0 +1,204 @@
+[![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.
+
+## 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"
+```
+
+# 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 = File.join(context.registers[:site].source, 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.0"
   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.0
 platform: ruby
 authors:
 - Mikalai Ananenka
 bindir: bin
 cert_chain: []
-date: 2025-04-23 00:00:00.000000000 Z
+date: 2025-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fastimage
@@ -107,18 +107,18 @@ 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
@@ -139,5 +139,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> elements with some automation, and a filter to get image
+  size
 test_files: []