jekyll-imgwh 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '039fab28cf4794e19d2f2d706fe5cba88ac46b13c9330d06308a50f4078382e3'
-  data.tar.gz: 18ed412a7b4cfbebbf1a424022df307691303ac5b067c758d22246214be8140e
+  metadata.gz: c07b034a8e148f443f9a0da9950592f0425786509651fb7f67ab5bf6bae1c076
+  data.tar.gz: d87846a205f7259100a63a3153a285105958e0903345e3c926fe7a4a0c7aaa9a
 SHA512:
-  metadata.gz: 3c215031cc7b9895731e059b14015dc10e5a565f1d29d2434e3e5b47224b851a09e068753ef5770fd16ef41f714d144d77ebdc31234abb85200f0f58617c7e77
-  data.tar.gz: 972b7d444f27c163706b5527c22615bdddc6f0889d69460af73e0e950b6bd077d4325292cd51301ec1673ba66824108544fd7be29a178e62c8b00a7c199f69b8
+  metadata.gz: ea444a44d2d81ae1b695ae405a7017c8f17800131229f84658f6fa7eab9efcb65fb5ee9cd4063c32a4a1ab0e4446de5ddde625515cb82766989e6ac4cc103339
+  data.tar.gz: 28ae016af67d07656650d1dbe293f652c025eef1ebb7e8e3e02f825a4447132aeeb6a54b41eeb39eafaf1def3c7d443d7f471e5f30ad0ae54c410a69c5a2a961

data/README.md

@@ -1,4 +1,4 @@
-[![Gem Version](https://badge.fury.io/rb/jekyll-imgwh.svg)](https://badge.fury.io/rb/jekyll-imgwh)
+# jekyll-imgwh [![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.
 
@@ -6,7 +6,7 @@ It provides a [Liquid tag `imgwh`](#liquid-tag) for `<img>` elements, which ensu
 
 It also provides a [Liquid filter `imgwh`](#liquid-filter), which returns image size as an array.
 
-# Installation
+## Installation
 
 Add preferred variant from the following ones to your site's `Gemfile` and run `bundle install`:
 
@@ -16,9 +16,9 @@ gem "jekyll-imgwh", group: :jekyll_plugins, git: "https://github.com/ojuuji/jeky
 gem "jekyll-imgwh", group: :jekyll_plugins, path: "/local/path/to/jekyll-imgwh"
 ```
 
-# Usage
+## Usage
 
-## Liquid Tag
+### Liquid Tag
 
 This plugin exposes Liquid tag `imgwh` with the following syntax:
 
@@ -43,39 +43,49 @@ Example:
 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">
+<img src="/assets/my-site.png" width="200" height="67" loading="lazy" alt="My Site">
 ```
 
-### Quotes and Whitespace
+#### 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>`:
+`<src>` can be specified with single quotes, double quotes, or without quotes. This also defines quotation for auto generated 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>
+```liquid
+{% imgwh "/foo.png" %} ⟶ <img src="/foo.png" width="123" height="456" loading="lazy">
+{% imgwh '/foo.png' %} ⟶ <img src='/foo.png' width='123' height='456' loading='lazy'>
+{% imgwh  /foo.png  %} ⟶ <img src=/foo.png width=123 height=456 loading=lazy>
 ```
 
 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')
+```liquid
+{% 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)
+```liquid
+{% 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
+When rendering markup for `imgwh` tag, plugin adds `imgwh_quote` variable to the rendering context. This variable contains the quote character used in the `imgwh` tag currently being evaluated. Note, it is available only in the markup used inside `imgwh` tag.
+
+Examples:
+
+```liquid
+{% imgwh "/foo.png" bar={{imgwh_quote}}baz{{imgwh_quote}} %} ⟶ <img src="/foo.png" ... bar="baz">
+{% imgwh '/foo.png' bar={{imgwh_quote}}baz{{imgwh_quote}} %} ⟶ <img src='/foo.png' ... bar='baz'>
+{% imgwh  /foo.png  bar={{imgwh_quote}}baz{{imgwh_quote}} %} ⟶ <img src=/foo.png ... bar=baz>
+```
+
+### Liquid Filter
 
 This plugin exposes a Liquid filter `imgwh`, which returns image size as an array.
 
@@ -101,7 +111,7 @@ would render to
 </pre>
 ```
 
-## Path Resolution
+### 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.
 
@@ -113,18 +123,20 @@ When the image path is relative, image is searched relative to the directory of
 
 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
+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
+## 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:
+imgwh:
   allowed_schemes: []
-  extra_rest:
+  extra_rest: loading={{imgwh_quote}}lazy{{imgwh_quote}}
 ```
 
 These are default options i.e. you do not need to specify any of them unless you want to use different value.
@@ -138,7 +150,7 @@ Option `allowed_schemes` adds exception for the schemes specified in it. For URI
 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:
+imgwh:
   allowed_schemes: ["data", "https"]
 ```
 
@@ -150,21 +162,25 @@ Remember `imgwh` tag syntax? This option injects additional text into all genera
 {% 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:
+Since all generated HTML `<img>` elements get the size attributes, plugin also sets lazy loading for the images via this option.
+
+If you want to omit any extra attributes, set `extra_rest` to an empty value:
 
 ```yml
-jekyll-imgwh:
-  extra_rest: loading="lazy"
+imgwh:
+  extra_rest: ""
 ```
 
-# Troubleshooting
+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:
 
-```
+```shell
 $ bundle exec jekyll serve
 <...>
-  Liquid Exception: jekyll-imgwh: 'Y:/ssg/assets/images/foo.png' could not be found in index.html
+  Liquid Exception: imgwh: 'Y:/ssg/assets/images/foo.png' could not be found in index.html
 <...>
 ```
 
@@ -172,27 +188,27 @@ Plugin also logs a lot of info which can help to resolve errors raised by it. Us
 
 For example, for template
 
-```
-{% imgwh "/assets/images/{{ product.key }}.png" alt="{{ project.title }} Logo" class="www-logo" %}
+```shell
+{% imgwh '/assets/images/{{ product.key }}.png' alt='{{ project.title }} Logo' class='www-logo' %}
 ```
 
 it would print something like this in case of successful generation:
 
-```
+```shell
 $ 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"'
+      imgwh: ---
+      imgwh: markup: "'/assets/images/{{ site.key }}.png' alt='{{ site.title }} Logo' class='www-logo'"
+      imgwh: src: "/assets/images/{{ site.key }}.png"
+      imgwh: rest: "alt='{{ site.title }} Logo' class='www-logo'"
+      imgwh: src rendered: "/assets/images/foo.png"
+      imgwh: image path: 'Y:/ssg/assets/images/foo.png'
+      imgwh: image size: [128, 64]
+      imgwh: rest rendered: "alt='My Product Logo' class='www-logo'"
 <...>
 ```
 
-# Development
+## Development
 
 To get started with the development:
 
@@ -202,3 +218,27 @@ cd jekyll-imgwh
 bundle install
 bundle exec rspec
 ```
+
+### Using in own code
+
+Example how to use the path resolving logic from the plugin in your code:
+
+```ruby
+require "jekyll/imgwh/helpers"
+
+module Utils
+  def file_size(src)
+    File.size(resolve_path(src, @context))
+  end
+
+  Liquid::Template.register_filter(self)
+
+  include Jekyll::Imgwh::Helpers
+end
+```
+
+Save it as `_plugins/file_size.rb` in your site (can use other file name but must place in `_plugins` directory unless it is overridden in the site config). Now you can use it like this:
+
+```liquid
+{{ "/attachments/some/archive.tar.gz" | file_size }}
+```

data/lib/jekyll/imgwh/helpers.rb

@@ -3,14 +3,17 @@
 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
+      def name
+        "imgwh"
+      end
+
+      def debug(*messages)
+        messages.each { |message| Jekyll.logger.debug "#{name}:", message }
       end
 
       def image_size(src, context)
@@ -19,28 +22,28 @@ module Jekyll
         if uri.scheme.nil?
           src = resolve_path(CGI.unescape(uri.path), context)
         else
-          allowed_schemes = context.registers[:site].config.dig(NAME, "allowed_schemes") || []
+          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"
+            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}'"
+        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)
+        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
+        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"
+        raise LoadError, "#{name}: none of '#{local_path}', '#{themed_path}' could be found"
       end
     end
   end

data/lib/jekyll/imgwh/tag.rb

@@ -8,33 +8,38 @@ module Jekyll
       include Helpers
 
       def initialize(tag_name, content, tokens)
+        content.strip!
         super
 
-        @content = content.strip
-
-        if (m = @content.match(%r/^(["'])((?:\1\1|(?!\1).)+)\1(?:\s+(.+))?$/))
+        if (m = @markup.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+(.+))?$/))
+        elsif (m = @markup.match(%r/^(?!["'])((?:(?!\{\{)\S|\{\{.+?\}\})+)(?:\s+(.+))?$/))
           @quote = ""
           @src, @rest = m.captures
 
         else
-          raise SyntaxError, "#{NAME}: invalid #{tag_name} tag: '#{@content}'"
+          raise SyntaxError, "#{@tag_name}: invalid tag markup: #{@markup.inspect}"
         end
       end
 
       def render(context)
-        ["---", "content: '#{@content}'", "src: '#{@src}'", "rest: '#{@rest}'"].map { |x| debug x }
+        debug "---", "markup: #{@markup.inspect}", "src: #{@src.inspect}", "rest: #{@rest.inspect}"
+
+        context.stack do
+          context["#{@tag_name}_quote"] = @quote
+
+          src = Liquid::Template.parse(@src).render(context)
+          debug "src rendered: #{src.inspect}"
 
-        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}"
 
-        size = image_size(src, context)
-        debug "image size: #{size}"
-        img << " width=#{quoted size[0]} height=#{quoted size[1]}" << render_rest(context) << ">"
+          rest = render_rest(context)
+
+          "<img src=#{quoted src} width=#{quoted size[0]} height=#{quoted size[1]}#{rest}>"
+        end
       end
 
       private
@@ -46,15 +51,16 @@ module Jekyll
       def render_rest(context)
         rest = +""
 
-        extra_rest = context.registers[:site].config.dig(NAME, "extra_rest")
-        unless extra_rest.nil?
+        extra_rest = context.registers[:site].config.dig(@tag_name, "extra_rest")
+        extra_rest ||= "loading={{#{@tag_name}_quote}}lazy{{#{@tag_name}_quote}}"
+        unless extra_rest.empty?
           extra_rest = Liquid::Template.parse(extra_rest).render(context)
-          debug "extra_rest rendered: '#{extra_rest}'"
+          debug "extra_rest rendered: #{extra_rest.inspect}"
           rest << " #{extra_rest}" unless extra_rest.empty?
         end
 
         tag_rest = Liquid::Template.parse(@rest).render(context)
-        debug "rest rendered: '#{tag_rest}'"
+        debug "rest rendered: #{tag_rest.inspect}"
         rest << " #{tag_rest}" unless tag_rest.empty?
 
         rest

data/lib/jekyll/imgwh/version.rb

@@ -2,7 +2,6 @@
 
 module Jekyll
   module Imgwh
-    NAME = "jekyll-imgwh"
-    VERSION = "1.3.0"
+    VERSION = "1.4.0"
   end
 end

data/lib/jekyll-imgwh.rb

@@ -4,8 +4,6 @@ require "jekyll/imgwh/tag"
 
 module Jekyll
   module Imgwh
-    Liquid::Template.register_tag "imgwh", Tag
-
     def imgwh(src)
       image_size(src, @context)
     end
@@ -13,6 +11,9 @@ module Jekyll
     Liquid::Template.register_filter(self)
 
     # Include after register_filter so they do not leak to Liquid yet are accessible within imgwh()
+    extend self
     include Helpers
+
+    Liquid::Template.register_tag(name, Tag)
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-imgwh
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Mikalai Ananenka
 bindir: bin
 cert_chain: []
-date: 2025-04-24 00:00:00.000000000 Z
+date: 2025-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fastimage
@@ -122,7 +122,9 @@ files:
 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,6 +141,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: A tag for <img> elements with some automation, and a filter to get image
-  size
+summary: A tag for <img> element with some automation, and a filter returning image
+  size.
 test_files: []