jekyll_picture_tag 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abfaaaa312c42464c11595294a11c10848f810cb6c1c63ce085b73b557501f8f
-  data.tar.gz: 31c075ac80ee1ee500999b4f54c05d1b0b29b4a13230a3f84914dc4b9a035325
+  metadata.gz: fa7bf95094ae98a78cd4ff1d40fd70d74378590d68a39273300ba216280a9794
+  data.tar.gz: 9e552372626ff7f1a54b8bacc902112b7cfd9c65ce01c6d8957fd411ff88a1ce
 SHA512:
-  metadata.gz: 5372b24c10a7049e20f1e2546a2f20cb2c0714cd4f8f8482e7005f503f9b192fe00ad5b4e07599e715cb280dad366a4477d3dd85ad5fc82743ac24309bf1688b
-  data.tar.gz: 66640daa48af3f8507a0d0675bd0fc6527a77c02401cdc06bc3ce967d946c61e53233a1a51b0e31812e5dbb462fb2cb37a42681e9b6fa1b00e31a9b7ea8763e0
+  metadata.gz: 8a7a4c78be31edc35758dc6fa5f5f90a0ba0bcc5801f3ebf570b13ba649d04f4b2df88472c8b583439b9e3888537e26f9eb3678a364abe5ef6d299a65b5fe216
+  data.tar.gz: aab45d2868253d91d82e8ce63b0fab117a394427bc6b4a5248cf395b5a29e29e9bddbcfcdb8e4a365e087d3bde93a06bedfc16a8c37b9bef71aac2479d4fd84f

data/docs/global_configuration.md

@@ -65,7 +65,12 @@ picture:
 
     *Default:* `false`
 
-  Normally, JPT will raise an error if a source image is missing, causing the entire site build to fail. This setting allows you to bypass this behavior and continue the build, either for certain build environments or all the time. I highly encourage you to set this to `development`, and set the jekyll build environment to `production` when you build for production so you don't shoot yourself in the foot (publish a site with broken images). You can read more about Jekyll environments [here](https://jekyllrb.com/docs/configuration/environments/).
+  Normally, JPT will raise an error if a source image is missing, causing the entire site build to
+  fail. This setting allows you to bypass this behavior and continue the build, either for certain
+  build environments or all the time. I highly encourage you to set this to `development`, and set
+  the jekyll build environment to `production` when you build for production so you don't shoot
+  yourself in the foot (publish a site with broken images). You can read more about Jekyll
+  environments [here](https://jekyllrb.com/docs/configuration/environments/).
   
 * **Use Relative Urls**
 
@@ -111,10 +116,58 @@ picture:
 
   *Example:* `nomarkdown: false`
 
-  *Default*: `true`
+  *Default:* `true`
 
   Whether or not to surround j-p-t's output with a `{::nomarkdown}..{:/nomarkdown}` block when called
   from within a markdown file. 
 
   This setting is overridden by the same setting in a preset. See [the notes]({{ site.baseurl
   }}/notes) for more detailed information. 
+
+* **Fast Build**
+
+  *Format:* `fast_build: (true|false|environment|array of environments)`
+
+  *Examples:* 
+
+    - `fast_build: true`
+
+    - `fast_build: development`
+
+    - `fast_build: [development, staging]`
+
+  *Default:* `false`
+
+  Makes a tradeoff: Speeds repeated build times for sites with many images, by assuming that the
+  filename alone is enough to uniquely identify a source image. This doesn't speed up image
+  generation, just detection of whether or not it's necessary.
+
+  Ordinarily, JPT generates an MD5 hash for every source image, every site build. This ensures that
+  if you replace one image with another, but keep the filename the same, JPT will correctly generate
+  images for the new file. If you have many large images and/or limited hardware, this can take some
+  time and make the development process painful. Enable this setting to skip MD5 hash checking on
+  existing generated images (most of the time), and just assume that if the filename, format, and
+  width match then it's the right one. If there are multiple possible matches (resulting from
+  leftover generated images from previous filename replacements), it'll compute a hash instead of
+  guessing randomly.
+
+* **Disable Jekyll Picture Tag**
+
+  *Format:* `disabled: (true|false|environment|array of environments)`
+
+  *Examples:* 
+
+    - `disabled: true`
+
+    - `disabled: development`
+
+    - `disabled: [development, staging]`
+
+  *Default:* `false`
+
+  Disable image and markup generation entirely. Useful for debugging, or to speed up site builds
+  when you're working on something else.
+
+  Hint: If you're going to toggle this on and off frequently, you might just use an environment
+  variable. Set this to something like `nopics`, and then start the Jekyll server with something
+  like `JEKYLL_ENV=nopics bundle exec jekyll serve` when you don't want image generation.

data/docs/releases.md

@@ -2,6 +2,13 @@
 ---
 # Release History
 
+* 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/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/generated_image.rb

@@ -1,8 +1,7 @@
 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
@@ -11,28 +10,90 @@ module PictureTag
       @source = source_file
       @width  = width
       @format = process_format format
+    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
 
     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
+      '.' + @format
+    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
+      Dir.glob File.join(PictureTag.dest_dir, name_left + '?' * 6 + name_right)
+    end
+
     def image
       @image ||= Image.open(@source.name)
     end
 
+    def dest_dir
+      File.dirname absolute_filename
+    end
+
+    def generate_image
+      puts 'Generating new image file: ' + name
+      process_image
+      write_image
+    end
+
     def process_image
       image.combine_options do |i|
         i.resize "#{@width}x"
@@ -44,12 +105,6 @@ 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
 
@@ -60,8 +115,7 @@ module PictureTag
 
     # Make sure destination directory exists
     def check_dest_dir
-      dir = File.dirname absolute_filename
-      FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+      FileUtils.mkdir_p(dest_dir) unless Dir.exist?(dest_dir)
     end
 
     def process_format(format)

data/lib/jekyll_picture_tag/instructions/configuration.rb

@@ -38,28 +38,64 @@ module PictureTag
       end
 
       def continue_on_missing?
-        setting = pconfig['ignore_missing_images']
-
-        # Config setting can be a string, an array, or a boolean
-        if setting.is_a? Array
-          setting.include? jekyll_env
-        elsif setting.is_a? String
-          setting == jekyll_env
-        else
-          setting
-        end
+        env_check pconfig['ignore_missing_images']
+      rescue ArgumentError
+        raise ArgumentError,
+              <<~HEREDOC
+                continue_on_missing setting invalid. Must be either a boolean
+                (true/false), an environment name, or an array of environment
+                names.
+              HEREDOC
       end
 
       def cdn?
         pconfig['cdn_url'] && pconfig['cdn_environments'].include?(jekyll_env)
       end
 
+      def disabled?
+        env_check pconfig['disabled']
+      rescue ArgumentError
+        raise ArgumentError,
+              <<~HEREDOC
+                "disabled" setting invalid. Must be either a boolean
+                (true/false), an environment name, or an array of environment
+                names.
+              HEREDOC
+      end
+
+      def fast_build?
+        env_check pconfig['fast_build']
+      rescue ArgumentError
+        raise ArgumentError,
+              <<~HEREDOC
+                "fast_build" setting invalid. Must be either a boolean
+                (true/false), an environment name, or an array of environment
+                names.
+              HEREDOC
+      end
+
       private
 
       def content
         @content ||= setting_merge(defaults, PictureTag.site.config)
       end
 
+      # There are a few config settings which can either be booleans,
+      # environment names, or arrays of environment names. This method works it
+      # out and returns a boolean.
+      def env_check(setting)
+        if setting.is_a? Array
+          setting.include? jekyll_env
+        elsif setting.is_a? String
+          setting == jekyll_env
+        elsif [true, false].include? setting
+          setting
+        else
+          raise ArgumentError,
+                "#{setting} must either be a string, an array, or a boolean."
+        end
+      end
+
       def setting_merge(default, jekyll)
         jekyll.merge default do |_key, config_setting, default_setting|
           if default_setting.respond_to? :merge

data/lib/jekyll_picture_tag/output_formats/basic.rb

@@ -69,8 +69,20 @@ module PictureTag
         element.media = srcset.media_attribute if srcset.media
       end
 
-      # File, not HTML
+      # GeneratedImage class, not HTML
       def build_fallback_image
+        fallback = GeneratedImage.new(
+          source_file: PictureTag.source_images.first,
+          format: PictureTag.fallback_format,
+          width: PictureTag.fallback_width
+        )
+
+        return fallback if fallback.exists?
+
+        build_new_fallback_image
+      end
+
+      def build_new_fallback_image
         GeneratedImage.new(
           source_file: PictureTag.source_images.first,
           format: PictureTag.fallback_format,

data/lib/jekyll_picture_tag/router.rb

@@ -69,6 +69,14 @@ module PictureTag
       config.pconfig
     end
 
+    def disabled?
+      config.disabled?
+    end
+
+    def fast_build?
+      config.fast_build?
+    end
+
     # Preset forwarding
 
     def widths(media)

data/lib/jekyll_picture_tag/source_image.rb

@@ -4,6 +4,7 @@ module PictureTag
   # to be reused by many different generated images.
   class SourceImage
     attr_reader :name, :shortname, :missing, :media_preset
+    attr_accessor :digest_guess
     include MiniMagick
 
     def initialize(relative_filename, media_preset = nil)
@@ -23,12 +24,16 @@ module PictureTag
     def digest
       @digest ||= if @missing
                     'x' * 6
+                  elsif PictureTag.fast_build? && @digest_guess
+                    # Digest guess will be handed off to this class by the first
+                    # generated image which needs it (via attr_accessor).
+                    @digest_guess
                   else
                     Digest::MD5.hexdigest(File.read(@name))[0..5]
                   end
     end
 
-    # Includes path relative to default sorce folder, and the original filename.
+    # Includes path relative to default source folder and the original filename.
     def base_name
       @shortname.delete_suffix File.extname(@shortname)
     end

data/lib/jekyll_picture_tag/srcsets/basic.rb

@@ -24,7 +24,7 @@ module PictureTag
       end
 
       def files
-        @files ||= widths.collect { |w| generate_file(w) }
+        @files ||= build_files
       end
 
       def to_a
@@ -46,15 +46,6 @@ module PictureTag
         nil
       end
 
-      # Check our source image size vs requested sizes
-      def check_widths(targets)
-        if targets.any? { |t| t > @source_image.width }
-          handle_small_source(targets, @source_image.width)
-        else
-          targets
-        end
-      end
-
       # Generates an HTML attribute
       def media_attribute
         "(#{PictureTag.media_presets[@media]})"
@@ -62,17 +53,39 @@ module PictureTag
 
       private
 
-      def handle_small_source(targets, image_width)
-        Utils.warning(
-          " #{@source_image.shortname} is #{image_width}px wide, smaller than" \
-          " at least one size in the set #{targets}. Will not enlarge."
-        )
+      def build_files
+        # By 'files', we mean the GeneratedImage class.
+        return target_files if target_files.all?(&:exists?)
+
+        # This triggers GeneratedImage to actually build an image file.
+        files = checked_targets
+        files.each(&:generate)
+
+        files
+      end
 
-        small_targets = targets.dup.delete_if { |t| t >= image_width }
+      def checked_targets
+        if target_files.any? { |f| f.width > @source_image.width }
 
-        small_targets.push image_width
+          small_source_warn
 
-        small_targets
+          files = target_files.reject { |f| f.width >= @source_image.width }
+          files.push(generate_file(@source_image.width))
+        end
+
+        files || target_files
+      end
+
+      def target_files
+        @target_files ||= widths.collect { |w| generate_file(w) }
+      end
+
+      def small_source_warn
+        Utils.warning(
+          " #{@source_image.shortname} is #{@source_image.width}px wide,"\
+          " smaller than at least one size in the set #{widths}. Will not"\
+          ' enlarge.'
+        )
       end
 
       def generate_file(width)

data/lib/jekyll_picture_tag/srcsets/pixel_ratio.rb

@@ -6,11 +6,9 @@ module PictureTag
       private
 
       def widths
-        target = PictureTag.preset['pixel_ratios'].collect do |p|
+        PictureTag.preset['pixel_ratios'].collect do |p|
           p * PictureTag.preset['base_width']
         end
-
-        check_widths target
       end
 
       def build_srcset_entry(file)

data/lib/jekyll_picture_tag/srcsets/width.rb

@@ -22,7 +22,7 @@ module PictureTag
       private
 
       def widths
-        check_widths PictureTag.widths(@media)
+        PictureTag.widths(@media)
       end
 
       def build_srcset_entry(file)

data/lib/jekyll_picture_tag/version.rb

@@ -1,3 +1,3 @@
 module PictureTag
-  VERSION = '1.8.0'.freeze
+  VERSION = '1.9.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_picture_tag
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Robert Wierzbowski
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-25 00:00:00.000000000 Z
+date: 2020-02-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler