jekyll_picture_tag 1.7.1 → 1.10.2

data/docs/releases.md

@@ -1,7 +1,23 @@
 ---
 ---
 # Release History
-
+* 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
   * Fix some HTML attribute related bugs
   * Add a few items to the FAQ

data/docs/usage.md

@@ -1,11 +1,12 @@
 ---
 ---
+
 # How to use the Liquid Tag:
 
 ## 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
@@ -16,50 +17,79 @@ use liquid variables anywhere.
 {% raw %}
 `{% picture example.jpg %}`
 
-`{% picture thumbnail example.jpg --alt Example Image %}`
+`{% 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.
 
-* **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.**
+
+  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.
+
+  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.
 
-* **Alternate images**
+  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.
 
-    *Format:* `(media query preset): (filename) (...)`
+  For detailed documentation, see ImageMagick's
+  [crop](http://www.imagemagick.org/script/command-line-options.php#crop) tool.
 
-    *Example:* `tablet: img_cropped.jpg mobile: img_cropped_more.jpg`
+  _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 +100,44 @@ 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`**
-  
-    *Format:* `--alt (alt text)`
+  - **`--alt`**
 
-    *Example:* `--alt Here is my alt text!`
+    _Format:_ `--alt (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.

data/jekyll_picture_tag.gemspec

@@ -38,9 +38,10 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'solargraph'
 
   spec.add_dependency 'addressable', '~> 2.6'
+  spec.add_dependency 'base32', '~> 0.3'
   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

@@ -18,9 +18,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 +39,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/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

@@ -6,3 +6,5 @@ fallback_format: original
 noscript: false
 link_source: false
 quality: 75
+data_sizes: true
+gravity: center

data/lib/jekyll_picture_tag/generated_image.rb

@@ -1,42 +1,135 @@
 require 'mini_magick'
+require 'base32'
 
 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_left + digest + name_right
+    end
+
+    # https://example.com/assets/images/myimage-100-123abc.jpg
+    #                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     def uri
       ImgURI.new(name).to_s
     end
 
+    def cropped_source_width
+      image.width
+    end
+
     private
 
+    # /home/dave/my_blog/_site/generated/somefolder/myimage-100-123abc.jpg
+    #                                    ^^^^^^^^^^^^^^^^^^^^^^^
+    def name_left
+      "#{@source.base_name}-#{@width}-"
+    end
+
+    # /home/dave/my_blog/_site/generated/somefolder/myimage-100-123abc.jpg
+    #                                                           ^^^^^^
+    def digest
+      guess_digest if !@source.digest_guess && PictureTag.fast_build?
+
+      @source.digest
+    end
+
+    # /home/dave/my_blog/_site/generated/somefolder/myimage-100-123abc.jpg
+    #                                                                 ^^^^
+    def name_right
+      crop_code + '.' + @format
+    end
+
+    # Hash the crop settings, so we can detect when they change.  We use a
+    # base32 encoding scheme to pack more information into fewer characters,
+    # without dealing with various filesystem naming limitations that would crop
+    # up using base64 (such as NTFS being case insensitive).
+    def crop_code
+      return '' unless @crop
+
+      Base32.encode(
+        Digest::MD5.hexdigest(@crop + @gravity)
+      )[0..2]
+    end
+
+    # Used for the fast build option: look for a file which matches everything
+    # we know about the destination file without calculating a digest on the
+    # source file, and if it exists we assume it's the right one.
+    def guess_digest
+      matches = dest_glob
+      return unless matches.length == 1
+
+      # Start and finish of the destination image's hash value
+      finish = -name_right.length
+      start = finish - 6
+
+      # The source image keeps track of this guess, so we hand it off:
+      @source.digest_guess = matches.first[start...finish]
+    end
+
+    # Returns a list of images which are probably correct.
+    def dest_glob
+      query = File.join(
+        PictureTag.dest_dir,
+        name_left + '?' * 6 + name_right
+      )
+
+      Dir.glob query
+    end
+
+    def generate_image
+      puts 'Generating new image file: ' + name
+      process_image
+      write_image
+    end
+
     def image
-      @image ||= Image.open(@source.name)
+      @image ||= open_image
+    end
+
+    def open_image
+      image_base = Image.open(@source.name)
+      image_base.combine_options do |i|
+        i.auto_orient
+        if @crop
+          i.gravity @gravity
+          i.crop @crop
+        end
+      end
+
+      image_base
     end
 
     def process_image
       image.combine_options do |i|
         i.resize "#{@width}x"
-        i.auto_orient
         i.strip
       end
 
@@ -44,24 +137,17 @@ module PictureTag
       image.quality PictureTag.quality(@format)
     end
 
-    def generate_image
-      puts 'Generating new image file: ' + name
-      process_image
-      write_image
-    end
-
     def write_image
-      check_dest_dir
+      # Make sure destination directory exists:
+      FileUtils.mkdir_p(dest_dir) unless Dir.exist?(dest_dir)
 
       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)
+    def dest_dir
+      File.dirname absolute_filename
     end
 
     def process_format(format)