jekyll_img 0.2.7 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ec131406e5dce078a0d63a5a821f73b8de66ece127990a8c3fa34a348c9d819
-  data.tar.gz: ed9c9f00d0df3b50ea9409593ccc58fa6aca91d2e8c200a4ece28a8b3fc21aa3
+  metadata.gz: 2fceb334580b84bf7a4238093ab6fb718d1b5fc84a087b1f554764be2ddae477
+  data.tar.gz: b0a489a01ee502e0bb4c6006610a8d82faf3561086fa4f57ce752158e0b9770a
 SHA512:
-  metadata.gz: 256b5e033e1f7ab3b08a0e37df0091eb39c67430397da6fb44745cd29e0dbc46fa104efe88b4230ca8d17ecb47014006ae11031895f14cf7031632e702f8cf0d
-  data.tar.gz: 15a4431e31fdef70e180dc0a774f9a9eff410276768d42a7f3b727a72f1b1c30fd87a6242199ddf0898bb1e0fa17aa43ce70cf67b727b3981d85be1aa4ede188
+  metadata.gz: 14a147fe5e8ee74caffa3c4919d31fc28389ed9c4d5571357fc4797f1efaba10960eb2cefe9a3ebc68a85e76a339acdc9916d1191df11a2f9d1381412fff085a
+  data.tar.gz: 9e7b3b29ea91638fd8f54e5320c9fc14ceef0456057cbd40d7b1d5e9c6803cfa65a01c7c76567e147be5cefcf270ce9721c328e65944b8c873ae63591956a180

data/.rubocop.yml

@@ -53,13 +53,13 @@ Metrics/BlockLength:
     - spec/img_props_spec.rb
 
 Metrics/CyclomaticComplexity:
-  Max: 10
+  Max: 15
 
 Metrics/MethodLength:
   Max: 40
 
 Metrics/PerceivedComplexity:
-  Max: 10
+  Max: 15
 
 Naming/FileName:
   Exclude:

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Change Log
 
+## 0.2.9 / 2025-05-19
+
+* `max-width` option added.
+* `width` option added as an alias for `size`.
+  This requires new CSS classes to be defined:
+  `max_eighthsize`, `max_fullsize`, `max_halfsize`, and `max_quartersize`.
+* More CSS classes defined and more tests added to the Demo app to support `max-width`.
+* `width='calc(something)'` added.
+
+
+## 0.2.8 / 2025-05-16
+
+* An image can now be lazily loaded by providing the `lazy` keyword.
+* An image can now be fetched with high priority by providing the `priority` keyword.
+
+
 ## 0.2.7 / 2024-09-11
 
 * Further tweaking of the generated HTML.

data/README.md

@@ -100,6 +100,108 @@ the following would result in the same image being displayed:
 {% img src="./images/blah" %}
 ```
 
+### Lazy Loading
+
+An image can be lazily loaded by providing the `lazy` keyword.
+This feature relies upon the lazy loading capability built into all modern browsers and does not rely upon JavaScript.
+
+From [Browser-level image lazy loading for the web](https://web.dev/articles/browser-level-image-lazy-loading#dimension-attributes)
+on `web.dev`:
+
+> While the browser loads an image, it doesn't immediately know the image's dimensions,
+> unless they're explicitly specified.
+> To let the browser reserve enough space on a page for images, and avoid disruptive layout shifts,
+> we recommend adding width and height attributes to all  tags.
+>
+> <img src="image.png" loading="lazy" alt="…" width="200" height="200">
+Alternatively, specify their values directly in an inline style:
+>
+> <img src="image.png" loading="lazy" alt="…" style="height:200px; width:200px;">
+
+This would translate to:
+
+```html
+{% img lazy
+  src="blah.webp"
+  style="height:200px; width:200px"
+%}
+```
+
+Note that the image must be fetched in order for HTML `img` attributes `height='auto'` and `width='auto'` to work.
+Thus lazy loading is incompatible with a dimension whose value is specified as `auto`.
+This means that, for lazily loaded images,
+`height` and `width` must have values that are computable without loading the image.
+Because the Jekyll `img` tag's `size` attribute only specifies the `width` attribute,
+and sets `height` to `auto`, it should not be used with the `lazy` keyword.
+
+The following examples of implicit and explicit `auto` dimensions will all give problems:
+
+```html
+{% img lazy
+  caption="A warning will be written to the logger"
+  size="200px"
+  src="blah.webp"
+%}
+
+{% img lazy
+  src="blah.webp"
+  style="height:auto; width:200px"
+%}
+
+{% img lazy
+  src="blah.webp"
+  style="height:200px; width:auto"
+%}
+
+{% img lazy
+  src="blah.webp"
+  style="height:200px"
+%}
+
+{% img lazy
+  src="blah.webp"
+  style="width:200px"
+%}
+```
+
+
+### High Priority Loading
+
+An image can be fetched with high priority by providing the `priority` keyword.
+
+Sample usage:
+
+```html
+{% img priority src="blah.webp" %}
+```
+
+The above generates an HTML `img` tag with a `fetchpriority='high'` attribute.
+
+From [Browser-level image lazy loading for the web](https://web.dev/articles/browser-level-image-lazy-loading#loading-priority)
+on `web.dev`:
+
+> If you want to increase the fetch priority of an important image, use `fetchpriority="high"`.
+>
+> An image with `loading="lazy"` and `fetchpriority="high"` is still delayed while it's off-screen,
+> and then fetched with a high priority when it's almost within the viewport.
+> This combination isn't really necessary because the browser would likely load that image with high priority anyway.
+
+
+Note that the image must be fetched in order for `img` attributes `height='auto'` and `width='auto'` to work.
+This means that `height` and `width` must have values that are computable without loading
+the image or lazy loading will not work properly.
+Because the `img` tag's `size` attribute only specifies the `width` attribute, and sets `height` to `auto`,
+it should not be used.
+
+Sample usage combining lazy and high priority loading:
+
+```html
+{% img lazy priority
+  src="blah.webp"
+  style="height:200px; width:200px"
+%}
+```
+
 
 ## Supported Filetypes
 
@@ -147,12 +249,17 @@ $ demo/_bin/debug -r
 - `caption="A caption"` No default value
 - `classes="class1 class2 classN"` Extra <img> classes; default is `rounded shadow`
 - `id="someId"` No default value
-- `nofollow`  Generates `rel='nofollow'`; only applicable when `url` is specified
-- `size='eighthsize|fullsize|halfsize|initial|quartersize|XXXYY|XXX%'`
+- `max-width='eighthsize|fullsize|halfsize|initial|quartersize|XXXYY|XXX%'`
    Defines width of image.
   - `initial` is the default behavior.
   - `eighthsize`, `fullsize`, `halfsize`, and `quartersize` are relative to the enclosing tag's width.
   - CSS units can also be used, for those cases `XXX` is a float and `YY` is `unit` (see below)
+- `nofollow`  Generates `rel='nofollow'`; only applicable when `url` is specified
+- `width='eighthsize|fullsize|halfsize|initial|quartersize|XXXYY|XXX%'`
+   Defines width of image (alias for `size`).
+  - `initial` is the default behavior.
+  - `eighthsize`, `fullsize`, `halfsize`, and `quartersize` are relative to the enclosing tag's width.
+  - CSS units can also be used, for those cases `XXX` is a float and `YY` is `unit` (see below)
 - `style='css goes here'` CSS style for <img>; no default
 - `target='none|whatever'` Only applicable when `url` is specified; default value is `_blank`
 - `title="A title"` Default value is `caption` text, if provided
@@ -212,8 +319,9 @@ Within the wrapper `<div />`, the embedded `<img />` is displayed with `width=10
 If a caption is required, the generated `<figure />` only makes the space taken by the generated HTML longer;
 the image&rsquo;s width and height are not affected.
 
-The wrapper will not exceed the width of the tag that encloses it if the `size` parameter has values
+The wrapper will not exceed the width of the tag that encloses it if the `width` parameter has values
 `eighthsize`, `fullsize`, `halfsize`, `initial` or `quartersize`.
+You can also use the `max-width` option.
 
 The wrapper's width can be defined independently of its enclosing tag by using
 [CSS units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#numbers_lengths_and_percentages)
@@ -226,7 +334,7 @@ Using CSS units means that large enough values could cause the image to exceed t
 
 ## Installation
 
-Add this line to your Jekyll project's Gemfile, within the `jekyll_plugins` group:
+Add this line to your Jekyll project's `Gemfile`, within the `jekyll_plugins` group:
 
 ```ruby
 group :jekyll_plugins do

data/jekyll_img.gemspec

@@ -3,11 +3,11 @@ require_relative 'lib/jekyll_img/version'
 Gem::Specification.new do |spec|
   github = 'https://github.com/mslinn/jekyll_img'
 
-  spec.authors = ['Mike Slinn']
-  spec.email = ['mslinn@mslinn.com']
-  spec.files = Dir['.rubocop.yml', 'LICENSE.*', 'Rakefile', '{lib,spec}/**/*', '*.gemspec', '*.md']
+  spec.authors  = ['Mike Slinn']
+  spec.email    = ['mslinn@mslinn.com']
+  spec.files    = Dir['.rubocop.yml', 'LICENSE.*', 'Rakefile', '{lib,spec}/**/*', '*.gemspec', '*.md']
   spec.homepage = 'https://www.mslinn.com/jekyll_plugins/jekyll_img.html'
-  spec.license = 'MIT'
+  spec.license  = 'MIT'
   spec.metadata = {
     'allowed_push_host' => 'https://rubygems.org',
     'bug_tracker_uri'   => "#{github}/issues",
@@ -15,18 +15,20 @@ Gem::Specification.new do |spec|
     'homepage_uri'      => spec.homepage,
     'source_code_uri'   => github,
   }
-  spec.name = 'jekyll_img'
+  spec.name                 = 'jekyll_img'
+  spec.platform             = Gem::Platform::RUBY
   spec.post_install_message = <<~END_MESSAGE
 
     Thanks for installing #{spec.name}!
 
   END_MESSAGE
-  spec.require_paths = ['lib']
+  spec.require_paths         = ['lib']
   spec.required_ruby_version = '>= 2.6.0'
-  spec.summary = 'Provides a Jekyll tag that generates images.'
-  spec.test_files = spec.files.grep %r{^(test|spec|features)/}
-  spec.version = JekyllImgVersion::VERSION
+  spec.summary               = 'Provides a Jekyll tag that generates images.'
+  spec.test_files            = spec.files.grep %r{^(test|spec|features)/}
+  spec.version               = JekyllImgVersion::VERSION
 
   spec.add_dependency 'jekyll', '>= 3.5.0'
-  spec.add_dependency 'jekyll_plugin_support', '>= 1.0.0'
+  spec.add_dependency 'jekyll_draft', '>= 3.0.0'
+  spec.add_dependency 'jekyll_plugin_support', '>= 3.0.0'
 end

data/lib/img_builder.rb

@@ -11,11 +11,12 @@ end
 
 # Constructs HTML img tag from properties
 class ImgBuilder
-  attr_reader :source
+  attr_reader :img, :props, :source
 
-  def initialize(props)
-    props.compute_dependant_properties
+  def initialize(img, props)
+    @img = img
     @props = props
+    @props.compute_dependant_properties
     @source = Source.new @props.src
   end
 
@@ -35,12 +36,24 @@ class ImgBuilder
         src="#{@source.src_fallback}"
         #{@props.attr_style_img}
         #{@props.attr_title}
+        #{@props.lazy}
+        #{@props.priority}
       />
     END_IMG
   end
 
   # See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture
   def generate_picture
+    if @props.lazy && (@props.size || @props.max_width)
+      @img.logger.warn do
+        <<~END_MSG.squish
+          Warning: lazy loading was specified, but the size or max_width attribute was specified for the href tag
+          on line #{@img.line_number} (after front matter) of #{@img.page['path']}.
+          Specify dimensions via style or class attributes instead.
+        END_MSG
+      end
+    end
+
     return generate_img if @props.src.start_with? 'http'
 
     # avif is not well supported yet
@@ -71,9 +84,11 @@ class ImgBuilder
   end
 
   def generate_wrapper
-    classes = "imgWrapper #{@props.img_display} #{@props.align} #{@props.attr_size_class} #{@props.wrapper_class}".squish
+    classes = ("imgWrapper #{@props.img_display} #{@props.align} #{@props.attr_size_class} " +
+              "#{@props.attr_max_width_class} #{@props.wrapper_class}").squish
+    styles = "#{@props.attr_width_style} #{@props.attr_max_width_style} #{@props.wrapper_style}".squish
     <<~END_HTML.remove_blank_lines
-      <div class='#{classes}' style='#{@props.attr_width_style} #{@props.wrapper_style}'>
+      <div class='#{classes}' style='#{styles}'>
         #{"<figure>\n" if @props.caption}
           #{@props.url ? generate_url_wrapper : generate_picture}
           #{generate_figcaption if @props.caption}

data/lib/img_props.rb

@@ -6,8 +6,8 @@ require 'uri'
 # All methods except compute_dependant_properties can be called in any order
 class ImgProperties
   attr_accessor :align, :alt, :attr_wrapper_align_class, :attribute, :attribution, :caption, :classes, :die_on_img_error,
-                :id, :img_display, :local_src, :nofollow, :src, :size, :style, :target, :title,
-                :url, :wrapper_class, :wrapper_style
+                :id, :img_display, :lazy, :local_src, :max_width, :nofollow, :priority, :src, :size, :style,
+                :target, :title, :url, :wrapper_class, :wrapper_style
 
   SIZES = %w[eighthsize fullsize halfsize initial quartersize].freeze
   UNITS = %w[Q ch cm em dvh dvw ex in lh lvh lvw mm pc px pt rem rlh svh svw vb vh vi vmax vmin vw %].freeze
@@ -29,6 +29,16 @@ class ImgProperties
     " rel='nofollow'" if @nofollow
   end
 
+  def attr_max_width_class
+    return nil if @max_width == false || @max_width.nil? || max_width_unit_specified?
+
+    unless SIZES.include?(@max_width)
+      msg = "'#{@max_width}' is not a recognized size; must be one of #{SIZES.join(', ')}, or an explicit unit."
+      raise Jekyll::ImgError, msg
+    end
+    "max_#{@max_width}"
+  end
+
   def attr_size_class
     return nil if @size == false || @size.nil? || size_unit_specified?
 
@@ -54,6 +64,10 @@ class ImgProperties
     "title='#{@title}'" if @title && !@title.empty?
   end
 
+  def attr_max_width_style
+    "max-width: #{@max_width};" if max_width_unit_specified?
+  end
+
   def attr_width_style
     "width: #{@size};" if size_unit_specified?
   end
@@ -98,10 +112,18 @@ class ImgProperties
     # raise Jekyll::ImgError, "#{@src} does not exist" unless File.exist?(src)
   end
 
+  def max_width_unit_specified?
+    max_width_not_specified = @max_width == false || @max_width.to_s.strip.empty?
+    return false if max_width_not_specified
+
+    @max_width&.end_with?(*UNITS) || @max_width&.start_with?('calc')
+  end
+
   def size_unit_specified?
-    return false if @size == false || @size.to_s.strip.empty?
+    size_not_specified = @size == false || @size.to_s.strip.empty?
+    return false if size_not_specified
 
-    @size.end_with?(*UNITS)
+    @size&.end_with?(*UNITS) || @size&.start_with?('calc')
   end
 
   def url?(src)

data/lib/jekyll_img/version.rb

@@ -1,3 +1,3 @@
 module JekyllImgVersion
-  VERSION = '0.2.7'.freeze
+  VERSION = '0.2.9'.freeze
 end

data/lib/jekyll_img.rb

@@ -35,8 +35,13 @@ module Jekyll
       props.classes           = @helper.parameter_specified? 'class'
       props.die_on_img_error  = @die_on_img_error
       props.id                = @helper.parameter_specified? 'id'
+      props.lazy              = ' loading="lazy"' if @helper.parameter_specified?('lazy')
+      props.max_width         = @helper.parameter_specified?('max-width')
       props.nofollow          = @helper.parameter_specified? 'nofollow'
-      props.size              = @helper.parameter_specified?('size') || @helper.parameter_specified?('_size')
+      props.priority          = ' fetchpriority="high"' if @helper.parameter_specified?('priority')
+      props.size              = @helper.parameter_specified?('size') ||
+                                @helper.parameter_specified?('_size') ||
+                                @helper.parameter_specified?('width')
       props.src               = @helper.parameter_specified? 'src'
       props.style             = @helper.parameter_specified? 'style'
       props.target            = @helper.parameter_specified? 'target'
@@ -45,7 +50,7 @@ module Jekyll
       props.wrapper_class     = @helper.parameter_specified? 'wrapper_class'
       props.wrapper_style     = @helper.parameter_specified? 'wrapper_style'
 
-      @builder = ImgBuilder.new(props)
+      @builder = ImgBuilder.new(self, props)
       @builder.to_s
     rescue ImgError => e # jekyll_plugin_support handles StandardError
       @logger.error { e.logger_message }

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_img
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.9
 platform: ruby
 authors:
 - Mike Slinn
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -24,21 +23,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 3.5.0
+- !ruby/object:Gem::Dependency
+  name: jekyll_draft
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: jekyll_plugin_support
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0
-description:
+        version: 3.0.0
 email:
 - mslinn@mslinn.com
 executables: []
@@ -89,8 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
-signing_key:
+rubygems_version: 3.7.1
 specification_version: 4
 summary: Provides a Jekyll tag that generates images.
 test_files: