jekyll_picture_tag 1.14.0 → 2.0.0pre1

data/docs/users/presets/link_source.md

@@ -1,5 +1,5 @@
 ---
-sort: 10
+sort: 11
 ---
 
 # Source Image Link

data/docs/users/presets/media_queries.md

@@ -1,5 +1,5 @@
 ---
-sort: 1
+sort: 2
 ---
 
 # Media Queries

data/docs/users/presets/nomarkdown_override.md

@@ -1,5 +1,5 @@
 ---
-sort: 11
+sort: 12
 ---
 
 # Nomarkdown Override

data/docs/users/presets/pixel_ratio_srcsets.md

@@ -1,5 +1,5 @@
 ---
-sort: 4
+sort: 5
 ---
 
 # Pixel Ratio Srcsets

data/docs/users/presets/width_height_attributes.md

@@ -1,5 +1,5 @@
 ---
-sort: 7
+sort: 8
 ---
 
 # Width & Height (Anti-Loading-Jank)

data/docs/users/presets/width_srcsets.md

@@ -1,19 +1,64 @@
 ---
-sort: 3
+sort: 4
 ---
 
 # Width Based Srcsets
 
-A width based srcset looks like this: 
+A width based srcset looks like this:
 
 ```html
 srcset="myimage-800.jpg 800w, myimage-1200.jpg 1200w, myimage-2000.jpg 2000w"
 ```
 
-It's the default; to use it specify a `widths` setting (or don't, for the
-default set), and optionally the `sizes` and `size` settings.
+You should use it when the size of an image depends on the size of the screen used to show it, which
+generally means anything bigger than about 300 pixels. It's the default; to use it specify a
+`widths` setting (or don't, for the default set), and optionally the `sizes` and `size` settings.
 
-## Widths
+## A word on sizes
+
+The `sizes` attribute is both important, and impossible to offer good defaults for. Web browsers parse
+web pages line-by-line. When they run into an external asset (such as an image) they must download,
+they start that process immediately without waiting to draw the page. This means that at the point
+in time when the browser must decide which image to download, it has no clue how large that image
+will be on the page. The sizes attribute is how we tell it.
+
+It doesn't have to be pixel-perfect, just close enough for the browser to make a good choice.  You
+can't use % (percentage width of the parent container) for the same reason we have to do this at
+all. If you do not provide it, the web browser will assume the image is 100vw (100% the width of
+the viewport.)
+
+## How to create a sizes attribute
+
+First, Load the page and image as they will appear in the final site. (Basically write the rest of
+the preset.)
+
+Next, using either dev tools or by manipulating the browser window itself, determine how large the
+image will be for all reasonable screen sizes. Organize this information into CSS measurements
+(using `vw`, `vh`, `px`, `em`, or a calculation based on those units) associated with your
+named CSS media queries, and enter them into the relevant preset. **Order matters**; enter these
+from most to least restrictive. The browser will ignore everything after the first media query it
+finds that is true.
+
+**Example:** on my particular site, for screens 900px or smaller, inline images are the width of the
+viewport minus 9px of padding on either side. For screens 901px or larger, they are a constant 862px
+wide. The relevant lines in my config file look like this:
+
+```yml
+media_queries: 
+  full_width: 'min-width: 901px'
+  # (...)
+
+presets:
+  default:
+  # (...)
+  sizes:
+    full_width: 862px
+  size: calc(100vw - 18px)
+```
+
+## Settings Reference
+
+### Widths
 
 _Format:_ `widths: [integer, integer, (...)]`
 
@@ -23,7 +68,7 @@ _Default_: `[400, 600, 800, 1000]`
 
 Array of image widths to generate, in pixels.
 
-## Media Widths
+### Media Widths
 
 _Format:_
 
@@ -41,11 +86,11 @@ media_widths:
 
 _Default:_ `widths` setting
 
-If you are using art direction, there is no sense in generating desktop-size
-files for your mobile image. You can specify sets of widths to associate with
-given media queries. If not specified, will use `widths` setting.
+If you are using art direction, there is no sense in generating desktop-size files for your mobile
+image. Similarly, there's no sense in generating 300px wide versions of your ultrawide crop. You can
+specify sets of widths to associate with given media queries.
 
-## Sizes
+### Sizes
 
 _Format:_
 
@@ -64,22 +109,15 @@ sizes:
   desktop: 900px
 ```
 
-Conditional sizes, used to construct the `sizes=` HTML attribute telling the
-browser how wide your image will be (on the screen) when a given media query
-is true. CSS dimensions can be given in `px`, `em`, or `vw`. To be used along
-with a width-based srcset.
-
-Provide these in order of most restrictive to least restrictive. The browser
-will choose the first one with an applicable media query.
-
-You don't have to provide a sizes attribute at all. If you don't, the browser
-will assume the image is 100% the width of the viewport.
+Conditional sizes, used to construct the `sizes=` HTML attribute telling the browser how wide your
+image will be (on the screen) when a given media query is true. CSS dimensions can be given in `px`,
+`em`, or `vw`. Provide these in order of most restrictive to least restrictive. The browser will
+choose the first one with an applicable media query.
 
-## Size
+### Size
 
 _Format:_ `size: (CSS Dimension)`
 
 _Example:_ `size: 80vw`
 
-Unconditional `sizes` setting, to be supplied either alone or after all
-conditional sizes.
+Unconditional `sizes` setting, to be supplied either alone or after all conditional sizes.

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,48 +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', '~> 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 'mime-types', '~> 3.0'
-  spec.add_dependency 'mini_magick', '~> 4.0'
-  spec.add_dependency 'objective_elements', '~> 1.1'
-
-  spec.add_runtime_dependency 'jekyll', '< 5'
 end

data/lib/jekyll_picture_tag.rb

@@ -5,9 +5,12 @@ 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/parsers'
 require_relative 'jekyll_picture_tag/router'
 require_relative 'jekyll_picture_tag/srcsets'
 require_relative 'jekyll_picture_tag/utils'
+require_relative 'jekyll_picture_tag/defaults/presets'
+require_relative 'jekyll_picture_tag/defaults/global'
 
 # Title: Jekyll Picture Tag
 # Authors: Rob Wierzbowski   : @robwierzbowski
@@ -50,7 +53,6 @@ module PictureTag
     # 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)
-      Utils.warning 'You have called JPT without any arguments.' if raw_params.empty?
       @raw_params = raw_params
       super
     end
@@ -61,7 +63,9 @@ module PictureTag
     def render(context)
       setup(context)
 
-      if PictureTag.disabled? || @raw_params.empty?
+      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

@@ -1,3 +1,64 @@
-require_relative 'cache/base'
-require_relative 'cache/source'
-require_relative 'cache/generated'
+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