jekyll_img 0.2.7 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ec131406e5dce078a0d63a5a821f73b8de66ece127990a8c3fa34a348c9d819
-  data.tar.gz: ed9c9f00d0df3b50ea9409593ccc58fa6aca91d2e8c200a4ece28a8b3fc21aa3
+  metadata.gz: bc81e3ae00a242cf25f3444f45da2f621c692d6c7ee4760a17b59e8acc672c4d
+  data.tar.gz: 8b10b63f09b8b586343fd7a4ccc42c205ad1618cb9b422712d2300838799ead3
 SHA512:
-  metadata.gz: 256b5e033e1f7ab3b08a0e37df0091eb39c67430397da6fb44745cd29e0dbc46fa104efe88b4230ca8d17ecb47014006ae11031895f14cf7031632e702f8cf0d
-  data.tar.gz: 15a4431e31fdef70e180dc0a774f9a9eff410276768d42a7f3b727a72f1b1c30fd87a6242199ddf0898bb1e0fa17aa43ce70cf67b727b3981d85be1aa4ede188
+  metadata.gz: 97b5302cf184c4fa544498354f1a8bae327f1567c438d88a232eef174422425d9e416bd6b0568439c1df2544cfb9b534e3cf0603931e00b9b2ff6a708c00abd5
+  data.tar.gz: a3ebcc031fb6e63dc92073cf358a38c7092719df8fbf028a5e3376d5b3447e3a539647d0825f47a47c27b45121345c91fecd1af99fc00b1ee816906b71d9c638

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## 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
 
@@ -226,7 +328,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
+      @img.logger.warn do
+        <<~END_MSG.squish
+          Warning: lazy loading was specified, but the size 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

data/lib/img_props.rb

@@ -6,7 +6,7 @@ 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,
+                :id, :img_display, :lazy, :local_src, :nofollow, :priority, :src, :size, :style, :target, :title,
                 :url, :wrapper_class, :wrapper_style
 
   SIZES = %w[eighthsize fullsize halfsize initial quartersize].freeze

data/lib/jekyll_img/version.rb

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

data/lib/jekyll_img.rb

@@ -35,7 +35,9 @@ 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.nofollow          = @helper.parameter_specified? 'nofollow'
+      props.priority          = ' fetchpriority="high"' if @helper.parameter_specified?('priority')
       props.size              = @helper.parameter_specified?('size') || @helper.parameter_specified?('_size')
       props.src               = @helper.parameter_specified? 'src'
       props.style             = @helper.parameter_specified? 'style'
@@ -45,7 +47,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.8
 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.6.9
 specification_version: 4
 summary: Provides a Jekyll tag that generates images.
 test_files: