jekyll_picture_tag 1.8.0 → 1.11.0

data/docs/releases.md

@@ -1,7 +1,26 @@
 ---
 ---
 # Release History
-
+* 1.11.0 July 27, 2020
+  * **Width and height attribute support!** Begone, page reflow.
+  * Cache image information between builds
+  * Change image naming format. This update will trigger all images to be regenerated, so you may
+    want to delete your generated images folder beforehand.
+* 1.10.2 July 6, 2020
+  * Bugfix for fallback image files not actually getting generated
+* 1.10.1 July 2, 2020
+  * Bugfix for erroneously regenerated images
+* 1.10.0 May 11, 2020
+  * **Image Cropping support!** access the power of ImageMagick's `crop` function.
+  * Don't issue a warning when `default` preset is not found.
+  * Documentation improvements
+* 1.9.0 Feb 2, 2020
+  * Add `fast_build` global setting
+  * Add `disabled` global setting
+  * Reduce unnecessary disk IO; sites with many source images should see build times improve when
+    no new images need to be generated.
+  * Add support for empty attributes; specifically so best-practice for decorative images (`alt=""`)
+    is possible.
 * 1.8.0 Nov 25, 2019
   * Add `data_sizes` setting for the `data_` family of output formats.
 * 1.7.1 Nov 14, 2019

data/docs/usage.md

@@ -1,65 +1,108 @@
 ---
 ---
+
 # How to use the Liquid Tag:
 
+This section describes how to use JPT's liquid tag; what options it takes and what kind of information you can pass through it to influence the form of the final HTML-markup.
+
 ## Format:
 
 {% raw %}
-`{% picture [preset] (base image) [alternate images] [attributes] %}`
+`{% picture [preset] (image) [crop] [alternate images & crops] [attributes] %}`
 {% endraw %}
 
 The only required argument is the base image. Line breaks and extra spaces are fine, and you can
 use liquid variables anywhere.
 
+The `preset` determines the actual HTML code that gets written to your files;
+it is basically a recipy that takes information that you provide in the
+liquid tag and turns it into HTML markup. When the `preset` is omitted
+default settings will be used, in the simplest case resulting in an `img`-tag
+containing an srcset pointing to your newly generated image sizes. You are
+free to override the `default` preset and define your own presets, giving
+full flexibility in what JPT will write to your files. See [markup preset]({{
+site.baseurl }}/presets#markup-presets) for more information on this.
+
 ## Examples:
 
 {% raw %}
 `{% picture example.jpg %}`
 
-`{% picture thumbnail example.jpg --alt Example Image %}`
+`{% picture {{ page.example_liquid_picture_var }} %}`
+
+`{% picture thumbnail example.jpg 1:1 --alt Example Image %}`
 
-`{% picture example.jpg --picture class="attribute-demo" %}`
+`{% picture example.jpg 16:9 north --picture class="attribute-demo" %}`
 
 `{% picture blog_index {{ post.image }} --link {{ post.url }} %}`
 
 `{% picture "some example.jpg" mobile: other\ example.jpg %}`
 
 ```md
-{% picture 
-  hero 
-  example.jpg 
-  tablet: example_cropped.jpg
-  mobile: example_cropped_more.jpg 
-  --alt Happy Puppy 
-  --picture class="hero" 
+{% picture
+  hero
+  example.jpg 16:9 east
+  tablet: example_cropped.jpg 3:2 east
+  mobile: example_cropped_more.jpg 1:1-50+0 east
+  --alt Happy Puppy
+  --picture class="hero"
   --link /
 %}
 ```
+
 {% endraw %}
 
 ## Argument reference
 
 Given in order:
 
-* **Preset**
+- **Preset**
 
   Select a [markup preset]({{ site.baseurl }}/presets#markup-presets), or omit to use the `default` preset. Presets
   are collections of settings that determine nearly everything about JPT's output, from the image
-  formats used to the exact format your markup will take.
+  formats used to the exact format your final HTML-markup will take.
 
-* **Base Image** (Required)
+- **Base Image** (Required)
 
   Can be any raster image (as long as you have the required ImageMagick delegate). Relative to
   jekyll's root directory, or the `source` [setting]({{ site.baseurl }}/global_configuration) if you've configured it.
 
-  For filenames with spaces, either use double quotes (`"my image.jpg"`) or a backslash (`my\
-  image.jpg`).
+  For filenames with spaces, either use double quotes (`"my image.jpg"`) or a backslash (`my\ image.jpg`).
+
+- **Crop**
+
+  **Check the [ installation guide ](installation) before using this feature.**
 
-* **Alternate images**
+  Crop an image to a given aspect ratio or size. This argument is given as a `geometry` and
+  (optionally) a `gravity`, which can appear in either order and are thin wrappers around
+  ImageMagick's [geometry](http://www.imagemagick.org/script/command-line-processing.php#geometry)
+  and [gravity](http://www.imagemagick.org/script/command-line-options.php#gravity) settings. The
+  values given here will override the preset settings (if present), can be given after every image,
+  and apply only to the preceding image.
 
-    *Format:* `(media query preset): (filename) (...)`
+  Geometry can take many forms, but most likely you'll want to set an aspect ratio-- given in the
+  standard `width:height` ratio such as `3:2`. Gravity sets which portion of the image to keep, and
+  is given in compass directions (`north`, `southeast`, etc) or `center` (default). Cropping happens
+  before resizing; the preset `widths` setting is a post-crop value.
 
-    *Example:* `tablet: img_cropped.jpg mobile: img_cropped_more.jpg`
+  If you'd like more fine-grained control, this can be offset by appending `+|-x` and (optionally)
+  `y` pixel values to the _geometry_ (not the gravity!). Example: `1:1+400 west` means "Crop to a
+  1:1 aspect ratio, starting 400 pixels from the left side.", and `north 3:2+0+100` means "Crop to
+  3:2, starting 100 pixels from the top." These can get a bit persnickety; there's nothing to stop
+  you from running off the side of the image. Pay attention.
+
+  For detailed documentation, see ImageMagick's
+  [crop](http://www.imagemagick.org/script/command-line-options.php#crop) tool.
+
+  _Note:_ If you do a lot of trial and error with these, it's a good idea to manually delete your
+  generated images folder more often as each change will build a new set of images without removing
+  the old ones.
+
+- **Alternate images**
+
+  _Format:_ `(media query preset): (filename) (...)`
+
+  _Example:_ `tablet: img_cropped.jpg mobile: img_cropped_more.jpg`
 
   Optionally specify any number of alternate base images for given [screen
   sizes]({{ site.baseurl }}/presets/#media-presets) (specified in `_data/picture.yml`). This is called [art
@@ -70,44 +113,45 @@ Given in order:
   be provided to the browser in reverse order, and it will select the first one with an applicable
   media query.
 
-* **Attributes**
+- **Attributes**
 
   Optionally specify any number of HTML attributes, or an href target. These will be added to any
   attributes you've set in a preset.
 
-  * **`--link`**
+  - **`--link`**
+
+    _Format:_ `--link (some url)`
 
-    *Format:* `--link (some url)`
+    _Examples_: `--link https://example.com`, `--link /blog/some_post/`
 
-    *Examples*: `--link https://example.com`, `--link /blog/some_post/`
+    Wrap the image in an anchor tag, with the `href` attribute set to whatever value you give it.
+    This will override automatic source image linking, if you have enabled it.
 
-      Wrap the image in an anchor tag, with the `href` attribute set to whatever value you give it.
-      This will override automatic source image linking, if you have enabled it.
+    **Note**: If you get either mangled HTML or extra {::nomarkdown} tags when using this, read
+    [here]({{ site.baseurl }}/notes).
 
-      **Note**: If you get either mangled HTML or extra {::nomarkdown} tags when using this, read
-      [here]({{ site.baseurl }}/notes).
+  - **`--alt`**
 
-  * **`--alt`**
-  
-    *Format:* `--alt (alt text)`
+    _Format:_ `--alt (alt text)`
 
-    *Example:* `--alt Here is my alt text!`
+    _Example:_ `--alt Here is my alt text!`
 
     Convenience shortcut for `--img alt="..."`
-  
-  * **`--(element)`**
 
-    *Format:* `--(picture|img|source|a|parent) (Standard HTML attributes)`
+  - **`--(element)`**
+
+    _Format:_ `--(picture|img|source|a|parent) (Standard HTML attributes)`
 
-    *Example:* `--img class="awesome-fade-in" id="coolio" --a data-awesomeness="11"`
+    _Example:_ `--img class="awesome-fade-in" id="coolio" --a data-awesomeness="11"`
 
     Apply attributes to a given HTML element. Your options are:
 
-    * `picture`
-    * `img`
-    * `source`
-    * `a` (anchor tag)
-    * `parent`
+    - `picture`
+    - `img`
+    - `source`
+    - `a` (anchor tag)
+    - `parent`
 
     `--parent` will be applied to the `<picture>` if present, otherwise the `<img>`; useful when
     using an `auto` output format.
+  **Note:** Attributes that are set in the liquid picture tag, but don't occur in the used `preset` will be ignored (e.g. adding `--picture class="cool-css"` with a preset that does not write a html `<picture>` tag).

data/jekyll_picture_tag.gemspec

@@ -40,7 +40,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'addressable', '~> 2.6'
   spec.add_dependency 'mime-types', '~> 3'
   spec.add_dependency 'mini_magick', '~> 4'
-  spec.add_dependency 'objective_elements', '~> 1.1.1'
+  spec.add_dependency 'objective_elements', '~> 1.1.2'
 
   spec.add_runtime_dependency 'jekyll', '< 5'
 end

data/lib/jekyll_picture_tag.rb

@@ -9,6 +9,7 @@ require_relative 'jekyll_picture_tag/srcsets'
 require_relative 'jekyll_picture_tag/utils'
 require_relative 'jekyll_picture_tag/img_uri'
 require_relative 'jekyll_picture_tag/router'
+require_relative 'jekyll_picture_tag/cache'
 
 # Title: Jekyll Picture Tag
 # Authors: Rob Wierzbowski   : @robwierzbowski
@@ -18,9 +19,9 @@ require_relative 'jekyll_picture_tag/router'
 #
 # Description: Easy responsive images for Jekyll.
 #
-# Download: https://github.com/rbuchberger/jekyll_picture_tag
-# Documentation: https://github.com/rbuchberger/jekyll_picture_tag/readme.md
-# Issues: https://github.com/rbuchberger/jekyll_picture_tag/issues
+# Download: https://rubygems.org/gems/jekyll_picture_tag
+# Documentation: https://rbuchberger.github.io/jekyll_picture_tag/
+# Issues: https://github.com/rbuchberger/jekyll_picture_tag/
 #
 # Syntax:
 # {% picture [preset] img.jpg [media_query: alt-img.jpg] [attributes] %}
@@ -39,30 +40,47 @@ require_relative 'jekyll_picture_tag/router'
 #
 # See the documentation for full configuration and usage instructions.
 module PictureTag
+  # The router module is important. If you're looking for the actual code which
+  # handles a `PictureTag.(some method)`, start there.
   extend Router
+
   ROOT_PATH = __dir__
 
   # This is the actual liquid tag, which provides the interface with Jekyll.
   class Picture < Liquid::Tag
+    # First jekyll initializes our class with a few arguments, of which we only
+    # care about the params (arguments passed to the liquid tag). Jekyll makes
+    # no attempt to parse them; they're given as a string.
     def initialize(tag_name, raw_params, tokens)
       @raw_params = raw_params
       super
     end
 
+    # Then jekyll calls the 'render' method and passes it a mostly undocumented
+    # context object, which appears to hold the entire site including its
+    # configuration and the parsed _data dir.
     def render(context)
-      # Jekyll passes in a mostly undocumented context object, which appears to
-      # hold the entire site, including configuration and the _data dir.
+      setup(context)
+
+      if PictureTag.disabled?
+        ''
+      else
+        PictureTag.output_class.new.to_s
+      end
+    end
+
+    private
+
+    def setup(context)
       PictureTag.context = context
 
-      # The instruction set depends on both the context and the tag parameters:
+      # Now that we have both the tag parameters and the context object, we can
+      # build our instruction set.
       PictureTag.instructions = Instructions::Set.new(@raw_params)
 
       # We need to explicitly prevent jekyll from overwriting our generated
-      # files:
+      # image files:
       Utils.keep_files
-
-      # Return a string:
-      PictureTag.output_class.new.to_s
     end
   end
 end

data/lib/jekyll_picture_tag/cache.rb

@@ -0,0 +1,3 @@
+require_relative 'cache/base'
+require_relative 'cache/source'
+require_relative 'cache/generated'

data/lib/jekyll_picture_tag/cache/base.rb

@@ -0,0 +1,59 @@
+require 'json'
+
+module PictureTag
+  module Cache
+    # Basic image information cache functionality
+    module Base
+      def initialize(base_name)
+        @base_name = base_name
+      end
+
+      def [](key)
+        data[key]
+      end
+
+      def []=(key, value)
+        raise ArgumentError unless template.keys.include? key
+
+        data[key] = value
+      end
+
+      # Call after updating data.
+      def write
+        FileUtils.mkdir_p(File.join(base_directory, sub_directory))
+
+        File.open(filename, 'w+') do |f|
+          f.write JSON.generate(data)
+        end
+      end
+
+      private
+
+      def data
+        @data ||= if File.exist?(filename)
+                    JSON.parse(File.read(filename)).transform_keys(&:to_sym)
+                  else
+                    template
+                  end
+      end
+
+      # /home/dave/my_blog/.jekyll-cache/jpt/(cache_dir)/assets/myimage.jpg.json
+      # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+      def base_directory
+        File.join(PictureTag.site.cache_dir, 'jpt', cache_dir)
+      end
+
+      # /home/dave/my_blog/.jekyll-cache/jpt/(cache_dir)/assets/myimage.jpg.json
+      #                                                 ^^^^^^^^
+      def sub_directory
+        File.dirname(@base_name)
+      end
+
+      # /home/dave/my_blog/.jekyll-cache/jpt/somefolder/myimage.jpg.json
+      # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+      def filename
+        File.join(base_directory, @base_name + '.json')
+      end
+    end
+  end
+end

data/lib/jekyll_picture_tag/cache/generated.rb

@@ -0,0 +1,20 @@
+module PictureTag
+  module Cache
+    # Caches generated image details, so we can skip expensive operations whenever
+    # possible.
+    # Stored width and height are values for the source image, after cropping.
+    class Generated
+      include Base
+
+      private
+
+      def cache_dir
+        'generated'
+      end
+
+      def template
+        { width: nil, height: nil }
+      end
+    end
+  end
+end

data/lib/jekyll_picture_tag/cache/source.rb

@@ -0,0 +1,19 @@
+module PictureTag
+  module Cache
+    # Caches source image details, so we can skip expensive operations whenever
+    # possible.
+    class Source
+      include Base
+
+      private
+
+      def template
+        { digest: nil, width: nil, height: nil }
+      end
+
+      def cache_dir
+        'source'
+      end
+    end
+  end
+end

data/lib/jekyll_picture_tag/defaults/global.yml

@@ -7,3 +7,5 @@ picture:
   cdn_environments: ['production']
   nomarkdown: true
   ignore_missing_images: false
+  disabled: false
+  fast_build: false

data/lib/jekyll_picture_tag/defaults/presets.yml

@@ -7,3 +7,5 @@ noscript: false
 link_source: false
 quality: 75
 data_sizes: true
+gravity: center
+dimension_attributes: false

data/lib/jekyll_picture_tag/generated_image.rb

@@ -1,47 +1,104 @@
 require 'mini_magick'
 
 module PictureTag
-  # Generated Image
-  # Represents a generated source file.
+  # Represents a generated image file.
   class GeneratedImage
     attr_reader :width, :format
+
     include MiniMagick
 
-    def initialize(source_file:, width:, format:)
+    def initialize(source_file:, width:, format:, crop: nil, gravity: '')
       @source = source_file
       @width  = width
       @format = process_format format
+      @crop = crop
+      @gravity = gravity
+    end
 
-      generate_image unless File.exist?(absolute_filename) || @source.missing
+    def exists?
+      File.exist?(absolute_filename)
     end
 
-    def name
-      "#{@source.base_name}-#{@width}-#{@source.digest}.#{@format}"
+    def generate
+      generate_image unless @source.missing || exists?
     end
 
+    # /home/dave/my_blog/_site/generated/somefolder/myimage-100-123abc.jpg
+    # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     def absolute_filename
       @absolute_filename ||= File.join(PictureTag.dest_dir, name)
     end
 
+    # /home/dave/my_blog/_site/generated/somefolder/myimage-100-123abc.jpg
+    #                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    def name
+      @name ||= "#{@source.base_name}-#{@width}-#{id}.#{@format}"
+    end
+
+    # https://example.com/assets/images/myimage-100-123abc.jpg
+    #                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     def uri
       ImgURI.new(name).to_s
     end
 
+    # Post crop
+    def source_width
+      update_cache unless cache[:width]
+
+      cache[:width]
+    end
+
+    # Post crop
+    def source_height
+      update_cache unless cache[:height]
+
+      cache[:height]
+    end
+
     private
 
+    # We exclude width and format from the cache name, since it isn't specific to them.
+    def cache
+      @cache ||= Cache::Generated.new("#{@source.base_name}-#{id}")
+    end
+
+    def update_cache
+      return if @source.missing
+
+      # Ensure it's generated:
+      image
+
+      cache[:width] = @source_dimensions[:width]
+      cache[:height] = @source_dimensions[:height]
+
+      cache.write
+    end
+
+    # Hash all inputs and truncate, so we know when they change without getting too long.
+    # /home/dave/my_blog/_site/generated/somefolder/myimage-100-1234abcde.jpg
+    #                                                           ^^^^^^^^^
+    def id
+      @id ||= Digest::MD5.hexdigest([@source.digest, @crop, @gravity, quality].join)[0..8]
+    end
+
+    # Post crop, before resizing and reformatting
     def image
-      @image ||= Image.open(@source.name)
+      @image ||= open_image
     end
 
-    def process_image
-      image.combine_options do |i|
-        i.resize "#{@width}x"
+    def open_image
+      image_base = Image.open(@source.name)
+      image_base.combine_options do |i|
         i.auto_orient
-        i.strip
+        if @crop
+          i.gravity @gravity
+          i.crop @crop
+        end
       end
 
-      image.format @format
-      image.quality PictureTag.quality(@format)
+      @source_dimensions = { width: image_base.width, height: image_base.height }
+
+      image_base
     end
 
     def generate_image
@@ -50,20 +107,28 @@ module PictureTag
       write_image
     end
 
+    def quality
+      PictureTag.quality(@format)
+    end
+
+    def process_image
+      image.combine_options do |i|
+        i.resize "#{@width}x"
+        i.strip
+      end
+
+      image.format @format
+      image.quality quality
+    end
+
     def write_image
-      check_dest_dir
+      FileUtils.mkdir_p(File.dirname(absolute_filename))
 
       image.write absolute_filename
 
       FileUtils.chmod(0o644, absolute_filename)
     end
 
-    # Make sure destination directory exists
-    def check_dest_dir
-      dir = File.dirname absolute_filename
-      FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
-    end
-
     def process_format(format)
       if format.casecmp('original').zero?
         @source.ext