jekyll_picture_tag 1.7.0 → 1.10.1

data/docs/releases.md

@@ -0,0 +1,64 @@
+---
+---
+# Release History
+
+* 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
+* 1.7.0 Aug 12, 2019
+  * Add support for setting generated image quality, either generally or specific to given
+    formats.
+  * Add support for spaces and other url-encoded characters in filenames
+  * Documentation restructure - Moved it out of the wiki, into the `docs` folder.
+  * Bugfix: Fallback image width will now be checked against source image width.
+  * Bugfix: Minor fix to nomarkdown wrapper output
+  * link_source will now target the base source image, rather than finding the biggest one.
+  * Remove fastimage dependency, add addressable dependency.
+  * Moderately significant refactoring and code cleanup 
+  * Decent set of tests added
+* 1.6.0 Jul  2, 2019:
+  * Missing Preset warning respects `data_dir` setting
+  * Add `continue_on_missing` option
+* 1.5.0 Jun 26, 2019: 
+  * better `{::nomarkdown}` necessity detection
+  * allow user to override `{::nomarkdown}` autodetection
+* 1.4.0 Jun 26, 2019:
+  * Rename gem from `jekyll-picture-tag` to `jekyll_picture_tag`, allowing us to use rubygems again.
+  * Add new output format: `naked_srcset`.
+* 1.3.1 Jun 21, 2019: Bugfix
+* 1.3.0 Jun  7, 2019:
+  * Initial compatibility with Jekyll 4.0
+  * bugfixes
+  * change to generated image naming-- The first build after this update will be longer, and you
+    might want to clear out your generated images.
+* 1.2.0 Feb  9, 2019:
+  * Add nomarkdown fix
+  * noscript option
+  * relative url option
+  * anchor tag wrappers
+* 1.1.0 Jan 22, 2019:
+  * Add direct_url markup format,
+  * auto-orient images before stripping metadata
+* 1.0.2 Jan 18, 2019: Fix ruby version specification
+* 1.0.1 Jan 13, 2019: Added ruby version checking
+* **1.0.0** Nov 27, 2018: Rewrite from the ground up. See the [migration guide]({{ site.baseurl }}/migration).
+* 0.2.2 Aug  2, 2013: Bugfixes
+* 0.2.1 Jul 17, 2013: Refactor again, add Liquid parsing.
+* 0.2.0 Jul 14, 2013: Rewrite code base, bring in line with Jekyll Image Tag.
+* 0.1.1 Jul  5, 2013: Quick round of code improvements.
+* 0.1.0 Jul  5, 2013: Initial release.

data/docs/usage.md

@@ -1,131 +1,143 @@
-# Liquid Tag Usage
+---
+---
 
-The tag takes a mix of user input and pointers to configuration settings. The only required argument
-is the base image:
+# How to use the Liquid Tag:
 
-`{% picture [preset] (source image) [alternate images] [attributes] %}`
+## Format:
 
-For filenames with spaces, you can either surround it with quotes (`"my image.jpg"`) or escape the
-space with a backslash (`"my\ image.jpg"`).
+{% raw %}
+`{% 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.
 
 ## Examples:
 
+{% raw %}
 `{% picture example.jpg %}`
 
-`{% picture thumbnail example.jpg %}`
+`{% picture thumbnail example.jpg 1:1 --alt Example Image %}`
+
+`{% 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 %}`
 
-```
-{% picture 
-  hero 
-  example.jpg 
-  mobile: example_cropped.jpg 
-  --alt Happy Puppy 
-  --picture class="hero" 
+```md
+{% 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
 
-* **Preset**
+Given in order:
 
-  *Format:* `(name of a markup preset described in _data/picture.yml)`
+- **Preset**
 
-  *Default:* `default`
+  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.
 
-  Optionally specify a markup
-  [preset](https://github.com/rbuchberger/jekyll_picture_tag/wiki/Writing-Presets) to use, or leave
-  blank for the `default` preset.
+- **Base Image** (Required)
 
-* **Source 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.
 
-  *Format:* `(Image filename, relative to source setting in _config.yml)`
+  For filenames with spaces, either use double quotes (`"my image.jpg"`) or a backslash (`my\ image.jpg`).
 
-  The base image that will be resized for your picture sources. Can be pretty much any raster image
-  (as long as imagemagick understands it).
+- **Crop**
 
-* **Alternate images**
+  **Check the [ installation guide ](installation) before using this feature.**
 
-    *Format:* `(media query preset): (image filename, relative to source directory)`
+  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.
 
-    *Example:* `tablet: img_cropped.jpg mobile: img_cropped_more.jpg`
+  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.
 
-  Optionally specify any number of alternate base images for given [media queries](#media-presets)
-  (specified in `_data/picture.yml`). This is one of of picture's strongest features, often referred
-  to as the [art direction use case](http://usecases.responsiveimages.org/#art-direction).
+  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.
 
-  Give your images in order of ascending specificity (The first image is the most general). They will
-  be provided to the browser in reverse order, and it will select the first one with a media query
-  that evaluates true.
+  For detailed documentation, see ImageMagick's
+  [crop](http://www.imagemagick.org/script/command-line-options.php#crop) tool.
 
-* **Attributes**
+  _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.
 
-  Optionally specify any number of HTML attributes. These will be added to any attributes you've
-  set in a preset. They can take a few different formats:
+- **Alternate images**
 
-  ##### `--link`
+  _Format:_ `(media query preset): (filename) (...)`
 
-  *Format:* `--link (some url)`
+  _Example:_ `tablet: img_cropped.jpg mobile: img_cropped_more.jpg`
 
-  *Examples*: `--link https://example.com`, `--link /blog/some_post/`
+  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
+  direction](http://usecases.responsiveimages.org/#art-direction), and is one of JPT's strongest
+  features.
 
-    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.
+  Give your images in order of ascending specificity (The first image is the most general). They will
+  be provided to the browser in reverse order, and it will select the first one with an applicable
+  media query.
 
-    **Note**: Don't disable the `nomarkdown` global setting if you would like do this within markdown
-    files and you are using Kramdown (Jekyll's default markdown parser.)
-  ##### `--alt`
-  
-  *Format:* `--alt (alt text)`
+- **Attributes**
 
-  *Example:* `--alt Here is my alt text!`
+  Optionally specify any number of HTML attributes, or an href target. These will be added to any
+  attributes you've set in a preset.
 
-  Shortcut for `--img alt="..."`
-  
-  ##### `--(element)`
+  - **`--link`**
 
-  *Format:* `--(picture|img|source|a|parent) (Standard HTML attributes)`
+    _Format:_ `--link (some url)`
 
-  *Example:* `--img class="awesome-fade-in" id="coolio" --a data-awesomeness="11"`
+    _Examples_: `--link https://example.com`, `--link /blog/some_post/`
 
-  Apply attributes to a given HTML element. Your options are:
+    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.
 
-  * `picture`
-  * `img`
-  * `source`
-  * `a` (anchor tag)
-  * `parent`
+    **Note**: If you get either mangled HTML or extra {::nomarkdown} tags when using this, read
+    [here]({{ site.baseurl }}/notes).
 
-  `--parent` will be applied to the `<picture>` if present, otherwise the `<img>`; useful when using
-    the `auto` output format.
+  - **`--alt`**
 
-  ##### Old syntax
+    _Format:_ `--alt (alt text)`
 
-  The old syntax is to just dump all attributes at the end:
+    _Example:_ `--alt Here is my alt text!`
 
-  `{% picture example.jpg alt="alt text" class="super-duper" %}`
+    Convenience shortcut for `--img alt="..."`
 
-  This will continue to work. For backwards compatibility, behavior of previous versions is
-  maintained: all attributes specified this way are applied to the img tag.
+  - **`--(element)`**
 
-#### Line breaks
-Line breaks and spaces are interchangeable, the following is perfectly acceptable:
+    _Format:_ `--(picture|img|source|a|parent) (Standard HTML attributes)`
 
-```
-{%
-  picture my-preset
-    img.jpg
-    mobile: alt.jpg
-    --alt Alt Text
-    --picture class="stumpy"
-%}
-```
-#### Liquid variables
+    _Example:_ `--img class="awesome-fade-in" id="coolio" --a data-awesomeness="11"`
+
+    Apply attributes to a given HTML element. Your options are:
 
-You can use liquid variables in a picture tag:
+    - `picture`
+    - `img`
+    - `source`
+    - `a` (anchor tag)
+    - `parent`
 
-`{% picture {{ post.featured_image }} --alt Our Project %}`
+    `--parent` will be applied to the `<picture>` if present, otherwise the `<img>`; useful when
+    using an `auto` output format.

data/jekyll_picture_tag.gemspec

@@ -35,11 +35,13 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 12.3'
   spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'simplecov'
+  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'
+  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)