jekyll_picture_tag 1.10.2 → 2.0.0pre1

data/docs/users/tutorial.md

@@ -0,0 +1,97 @@
+---
+sort: 3
+---
+
+# Tutorial
+
+## Hello, world!
+
+Once you've followed the [installation](installation) instructions, it's a good
+time to make sure we're set up correctly. Drop an image or two in the site root
+(or `source` directory if you [configured it](configuration/directories)), pick
+some page and write the following (substitute the image filename as
+appropriate):
+
+{% raw %}
+```
+{% picture my_image.jpg %}
+```
+{% endraw %}
+
+Build/serve the site and check it out! Your image should be there, and if you inspect it with the
+dev tools you should see an `<img>` tag with a `srcset` attribute. You're officially serving
+responsive images.
+
+## Webp
+
+JPT includes several built-in presets and media queries, documented in the
+[examples](presets/examples). They're intended as a starting point and a learning tool, not for
+production use. Don't dig to deeply into that link just yet, try them out first:
+
+{% raw %}
+```
+{% picture jpt-webp my_image.jpg %}
+```
+{% endraw %}
+
+Now instead of a lone `<img>` tag, you get a `<picture>` surrounding two `<source>`s and an `<img>`.
+The first source contains webp images, and the second contains jpgs. Success! Lighthouse is happier
+and happier.
+
+## Alt text
+
+Good web developers add alt text. JPT makes this easy:
+
+{% raw %}
+```
+{% picture my_image.jpg --alt Happy Puppy %}
+```
+{% endraw %}
+
+## Crop
+
+
+{% raw %}
+```
+{% picture my_image.jpg 16:9 %}
+```
+{% endraw %}
+
+Feeling cinematic? If you don't like how the image gets cropped, you can adjust it:
+
+{% raw %}
+```
+{% picture my_image.jpg 16:9 center %}
+```
+{% endraw %}
+
+Your options are `attention` (which is the default), `entropy`, and `center`.
+
+## Art Direction
+
+(Usually means "Cropping, but only sometimes.")
+
+Art direction is tricky to understand; I know it tripped me up for awhile when learning the subject.
+Here's a short explanation, along with a demo: Let's pretend that we have some image which looks
+good on desktop, but on a mobile screen it's hard to see the subject. Resolution isn't the problem,
+the image just needs to be cropped for smaller screens. JPT makes this easy: 
+
+{% raw %}
+```
+{% picture my_image.jpg 2:1 jpt-mobile: my_image.jpg 1:1 %}
+```
+{% endraw %}
+
+This tag is pretty complicated, so here's a breakdown in plain english:
+* Use the default preset.
+* use my_image.jpg as the base image.
+* Crop it to a 2:1 aspect ratio.
+* When the media query named 'jpt-mobile' is true, also use my_image.jpg
+* but this time crop it square.
+
+Now adjust the browser width. When skinny, you should see a square crop of your image, and when it's
+wide you should see a 2:1 crop of the same image. That's art direction. Note that there's no
+requirement at all for them to be the same image, and you don't have to use JPT to do the cropping.
+
+There are several more liquid tag examples [here](liquid_tag/examples) that you may want to look
+over, as well as the [liquid tag instructions](liquid_tag).

data/jekyll_picture_tag.gemspec

@@ -4,44 +4,58 @@ require 'jekyll_picture_tag/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'jekyll_picture_tag'
-  spec.version       = PictureTag::VERSION
   spec.authors       = ['Robert Wierzbowski', 'Brendan Tobolaski',
                         'Robert Buchberger']
   spec.email         = ['robert@buchberger.cc']
-
+  spec.homepage      = 'https://github.com/rbuchberger/jekyll_picture_tag'
+  spec.metadata      = { 'documentation_uri' =>
+                         'https://rbuchberger.github.io/jekyll_picture_tag/' }
+  spec.license       = 'BSD-3-Clause'
   spec.summary       = 'Easy responsive images for Jekyll.'
   spec.description   = <<-HEREDOC
-    Jekyll Picture Tag is a liquid tag that adds responsive images to your
-    Jekyll static site.Jekyll Picture Tag automatically creates resized source
-    images, is fully configurable, and covers all use cases — including art
-    direction and resolution switching — with a little YAML configuration and a
-    simple template tag.
+    Jekyll Picture Tag adds responsive images to your Jekyll static site. It
+    automatically creates resized source images, is fully configurable, and
+    covers all use cases, including art direction and resolution switching, with
+    a little YAML configuration and a simple template tag.
   HEREDOC
-  spec.homepage      = 'https://github.com/rbuchberger/jekyll_picture_tag'
-  spec.license       = 'BSD-3-Clause'
-  spec.require_paths = ['lib']
 
+  spec.version       = PictureTag::VERSION
+  spec.require_paths = ['lib']
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
+    f.match(%r{^(test)/})
   end
 
-  spec.required_ruby_version = ['>= 2.5', '< 3']
+  spec.required_ruby_version = ['>= 2.6', '< 3']
+
+  # addressable is used to url-encode image filenames.
+  spec.add_runtime_dependency 'addressable', '~> 2.6'
+  # Jekyll versions older than 4.0 are not supported.
+  spec.add_runtime_dependency 'jekyll', '~> 4.0'
+  # MIME types are needed for <source> tags' type= attributes.
+  spec.add_runtime_dependency 'mime-types', '~> 3.0'
+  # objective_elements handles HTML generation.
+  spec.add_runtime_dependency 'objective_elements', '~> 1.1'
+  # rainbow is used to colorize terminal output.
+  spec.add_runtime_dependency 'rainbow', '~> 3.0'
+  # ruby-vips interfaces with libvips.
+  spec.add_runtime_dependency 'ruby-vips', '~> 2.0.17'
 
+  # libvips handles all image processing operations.
+  spec.requirements << 'libvips'
+
+  # Development dependencies are not installed when using this gem. You can
+  # ignore these, unless you are working on JPT itself.
   spec.add_development_dependency 'bundler', '~> 2.0'
-  spec.add_development_dependency 'minitest', '~> 5.11'
+  spec.add_development_dependency 'minitest', '~> 5.14'
+  spec.add_development_dependency 'minitest-rg'
   spec.add_development_dependency 'mocha', '~> 1.9'
-  spec.add_development_dependency 'nokogiri', '~> 1.10'
+  spec.add_development_dependency 'nokogiri', '~> 1.1'
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'rake', '~> 12.3'
-  spec.add_development_dependency 'rubocop'
-  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'rubocop', '~> 1.7.0'
+  spec.add_development_dependency 'rubocop-minitest', '~> 0.10.0'
+  spec.add_development_dependency 'rubocop-performance', '~> 1.9.0'
+  spec.add_development_dependency 'rubocop-rake', '~> 0.5.0'
+  spec.add_development_dependency 'simplecov', '~> 0.20.0'
   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.2'
-
-  spec.add_runtime_dependency 'jekyll', '< 5'
 end

data/lib/jekyll_picture_tag.rb

@@ -1,14 +1,16 @@
 require 'jekyll'
 require 'objective_elements'
 
-require_relative 'jekyll_picture_tag/generated_image'
+require_relative 'jekyll_picture_tag/cache'
+require_relative 'jekyll_picture_tag/images'
 require_relative 'jekyll_picture_tag/instructions'
 require_relative 'jekyll_picture_tag/output_formats'
-require_relative 'jekyll_picture_tag/source_image'
+require_relative 'jekyll_picture_tag/parsers'
+require_relative 'jekyll_picture_tag/router'
 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/defaults/presets'
+require_relative 'jekyll_picture_tag/defaults/global'
 
 # Title: Jekyll Picture Tag
 # Authors: Rob Wierzbowski   : @robwierzbowski
@@ -61,7 +63,9 @@ module PictureTag
     def render(context)
       setup(context)
 
-      if PictureTag.disabled?
+      if PictureTag.disabled? || PictureTag.raw_params.empty?
+        Utils.warning 'You have called JPT without any arguments.'
+
         ''
       else
         PictureTag.output_class.new.to_s
@@ -71,11 +75,9 @@ module PictureTag
     private
 
     def setup(context)
+      PictureTag.clear_instructions
       PictureTag.context = context
-
-      # 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)
+      PictureTag.raw_params = @raw_params
 
       # We need to explicitly prevent jekyll from overwriting our generated
       # image files:

data/lib/jekyll_picture_tag/cache.rb

@@ -0,0 +1,64 @@
+require 'json'
+
+module PictureTag
+  # Store expensive bits of information between text files. Originally cached
+  # width & heights of images in addition to digests, now just image digests.
+  class Cache
+    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
+      return if PictureTag.config['disable_disk_cache']
+
+      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')
+    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
+
+    def template
+      { digest: nil }
+    end
+  end
+end

data/lib/jekyll_picture_tag/defaults/global.rb

@@ -0,0 +1,18 @@
+module PictureTag
+  # Default settings for _config.yml
+  DEFAULT_CONFIG = {
+    'picture' => {
+      'source' => '',
+      'output' => 'generated',
+      'suppress_warnings' => false,
+      'relative_url' => true,
+      'cdn_environments' => ['production'],
+      'nomarkdown' => true,
+      'ignore_missing_images' => false,
+      'disabled' => false,
+      'fast_build' => false,
+      'ignore_baseurl' => false,
+      'baseurl_key' => 'baseurl'
+    }
+  }.freeze
+end

data/lib/jekyll_picture_tag/defaults/presets.rb

@@ -0,0 +1,57 @@
+module PictureTag
+  DEFAULT_PRESET = { 'markup' => 'auto',
+                     'formats' => ['original'],
+                     'widths' => [400, 600, 800, 1000],
+                     'fallback_width' => 800,
+                     'fallback_format' => 'original',
+                     'noscript' => false,
+                     'link_source' => false,
+                     'quality' => 75,
+                     'format_quality' => { 'webp' => 50,
+                                           'avif' => 30,
+                                           'jp2' => 30 },
+                     'data_sizes' => true,
+                     'keep' => 'attention',
+                     'dimension_attributes' => false,
+                     'strip_metadata' => true,
+                     'image_options' => {
+                       'avif' => { 'compression' => 'av1', 'speed' => 8 }
+                     } }.freeze
+
+  STOCK_PRESETS = {
+    'jpt-webp' => { 'formats' => %w[webp original] },
+
+    'jpt-avif' => { 'formats' => %w[avif webp original] },
+
+    'jpt-lazy' => { 'markup' => 'data_auto',
+                    'noscript' => true,
+                    'formats' => %w[webp original],
+                    'attributes' => { 'parent' => 'class="lazy"' } },
+
+    'jpt-loaded' => { 'formats' => %w[avif jp2 webp original],
+                      'dimension_attributes' => true },
+
+    'jpt-direct' => { 'markup' => 'direct_url',
+                      'fallback_format' => 'webp',
+                      'fallback_width' => 600 },
+
+    'jpt-thumbnail' => { 'base_width' => 250,
+                         'pixel_ratios' => [1, 1.5, 2],
+                         'formats' => %w[webp original],
+                         'fallback_width' => 250,
+                         'attributes' => { 'picture' => 'class="icon"' } },
+
+    'jpt-avatar' => { 'base_width' => 100,
+                      'pixel_ratios' => [1, 1.5, 2],
+                      'fallback_width' => 100,
+                      'crop' => '1:1' }
+  }.freeze
+
+  STOCK_MEDIA_QUERIES = {
+    'jpt-mobile' => 'max-width: 480px',
+    'jpt-tablet' => 'max-width: 768',
+    'jpt-laptop' => 'max-width: 1024px',
+    'jpt-desktop' => 'max-width: 1200',
+    'jpt-wide' => 'min-width: 1201'
+  }.freeze
+end

data/lib/jekyll_picture_tag/images.rb

@@ -0,0 +1,4 @@
+require_relative 'images/image_file'
+require_relative 'images/generated_image'
+require_relative 'images/img_uri'
+require_relative 'images/source_image'

data/lib/jekyll_picture_tag/images/generated_image.rb

@@ -0,0 +1,92 @@
+require 'ruby-vips'
+
+module PictureTag
+  # Represents a generated image, but not the file itself. Its purpose is to
+  # make its properties available for query, and hand them off to the ImageFile
+  # class for generation.
+  class GeneratedImage
+    attr_reader :width
+
+    def initialize(source_file:, width:, format:)
+      @source = source_file
+      @width  = width
+      @raw_format = format
+    end
+
+    def format
+      @format ||= process_format(@raw_format)
+    end
+
+    def exists?
+      File.exist?(absolute_filename)
+    end
+
+    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/somefolder/myimage-100-123abc.jpg
+    #                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    def uri
+      ImgURI.new(name).to_s
+    end
+
+    # Post crop
+    def source_width
+      image.width
+    end
+
+    # Post crop
+    def source_height
+      image.height
+    end
+
+    def quality
+      PictureTag.quality(format, width)
+    end
+
+    private
+
+    # 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(settings.join)[0..8]
+    end
+
+    def settings
+      [@source.digest, @source.crop, @source.keep, quality]
+    end
+
+    def image
+      @image ||= Vips::Image.new_from_file @source.name
+    end
+
+    def generate_image
+      return if @source.missing
+
+      ImageFile.new(@source, self)
+    end
+
+    def process_format(format)
+      if format.casecmp('original').zero?
+        @source.ext
+      else
+        format.downcase
+      end
+    end
+  end
+end