jekyll_picture_tag 1.13.0 → 2.0.2

data/docs/users/presets/index.md

@@ -2,7 +2,7 @@
 sort: 3
 ---
 
-# Writing Presets
+# Presets
 
 Presets are named collections of settings that determine basically everything
 about JPT's output. Think of them like frameworks that you can plug images into;
@@ -14,26 +14,6 @@ the `_data/` directory as well.
 Any settings which are specific to particular markup formats are documented on
 their respective markup format page.
 
-## Required Knowledge
-
-If you don't know the difference between resolution switching and art direction,
-stop now and learn responsive images. Ideally, write a few yourself until you
-understand them.
-
-Here are some good guides:
-
-* [MDN Responsive Images guide](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)
-* [CSS Tricks Guide to Reponsive Images](https://css-tricks.com/a-guide-to-the-responsive-images-syntax-in-html/)
-* [Cloud 4 - Responsive Images 101](https://cloudfour.com/thinks/responsive-images-101-definitions/)
-
-## Media Queries
-
-**Media queries are not presets**, but they are used when writing them. They are
-defined in `_data/picture.yml` alongside presets. More information
-[here](media_queries).
-
-## Presets
-
 _General Format:_
 
 ```yaml
@@ -65,37 +45,31 @@ presets:
     noscript: true
 ```
 
-Each entry is a pre-defined collection of settings to build a given chunk of
-text (usually HTML) and its respective images. You can select one as the first
-argument given to the tag:
+## Media Queries
 
-{% raw %}
-`{% picture my-preset image.jpg %}`
-{% endraw %}
+**Media queries are not presets**, but they are used when writing them. They are
+defined in `_data/picture.yml` alongside presets. They look like this:
 
-The `default` preset will be used if none is specified. A preset name can't
-contain a `.` (period). You can create as many as you like.
+```yaml
+# _data/picture.yml
 
-```note
-`media_queries` and `presets` used to be called `media_presets` and
-`markup_presets`.  These names were causing some confusion, so they were
-changed. The old names will continue working for the forseeable future, at least
-until the next major version update.
+media_queries:
+  (name): '(media query)'
+  (name): '(media query)'
+  (name): '(media query)'
 ```
 
-## Markup Format
-
-The high level, overall markup format is controlled with the `markup:` setting,
-documented [here](markup_formats).
+Example:
 
-## Choosing a Srcset format
- 
-For images that are different sizes on different screens (most images), use a
-[width-based srcset](width_srcsets) (which is the default). 
+```yaml
+media_queries:
+  full_width: 'min-width: 901px'
+  tablet: 'min-width: 601px'
+  mobile: 'max-width: 600px'
+```
 
-Use a [pixel-ratio srcset](pixel_ratio_srcsets) when the image will always be
-the same size, regardless of screen width (thumbnails and icons). 
+More information [here](media_queries).
 
-## Settings reference
+## Reference
 
 {% include list.liquid %}

data/docs/users/presets/link_source.md

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

data/docs/users/presets/media_queries.md

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

data/docs/users/presets/nomarkdown_override.md

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

data/docs/users/presets/pixel_ratio_srcsets.md

@@ -1,5 +1,5 @@
 ---
-sort: 4
+sort: 6
 ---
 
 # 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: 5
 ---
 
 # 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/presets/writing_presets.md

@@ -0,0 +1,65 @@
+---
+sort: 1
+---
+
+# How to write a preset
+
+## 0. Pick a name
+
+* Preset names should be a single word, and they can't contain periods.
+* `default` is used when you don't specify one in a liquid tag.
+* Anything beginning with `jpt-` is off limits.
+
+## 1. Pick a Markup Format
+
+The high level, overall markup format is controlled with the `markup:` setting, documented
+[here](markup_formats). You probably want the default setting of `auto`, unless you're doing some
+form of post-processing.
+
+If you have a lot of images below-the-fold, consider setting up lazy-loading with an appropriate
+javascript library (there are tons) and `data_auto`.
+
+## 2. Choose a srcset format.
+ 
+For images that are different sizes on different screens (most images), use a [width-based
+srcset](width_srcsets) (which is the default). When using this format, it's important to create a
+sizes attribute, documented at the link above.
+
+Use a [pixel-ratio srcset](pixel_ratio_srcsets) when the image will always be the same size,
+regardless of screen width (thumbnails, avatars, icons, etc). 
+
+## 3. Choose a set of image widths.
+
+For width-based srcsets, set `widths:`. For pixel-ratio srcsets, set `base_width:` and
+`pixel_ratios:`. You want 3-6 sizes that cover a wide range of devices.
+
+## 4. Choose a set of image formats.
+
+Accomplish this by setting `formats: [format1, format2, etc...]`
+
+* `webp` has [broad support](https://caniuse.com/?search=webp) and is an obvious choice.
+* `avif` has [bad](https://caniuse.com/?search=avif) (but improving) support, and for some reason is slow to generate, but gets better
+  file sizes than webp.
+* `jp2` is [Apple's baby](https://caniuse.com/?search=jp2).
+* `original` spits out whatever you put in.
+
+Order matters; browsers will use the first one they support. 
+
+* `[webp, original]` is a good compromise of build resources, support, and performance.
+* `[webp, jp2, original]` brings Safari users along for the ride.
+* `[avif, original]` If you don't care about browsers that aren't chrome, or build time.
+* `[avif, webp, jp2, original]` might be overkill, but it keeps everyone happy.
+
+## 5. Consider enabling dimension attributes.
+
+This step prevents page reflow on image load (especially when lazy loading), but requires some prep.
+
+1. Make sure your CSS is correct. You need something like `width: 100%` and `height: auto` (which
+   is why they aren't turned on by default.) Without this step, you'll get crazy sizes and/or
+   stretched images.
+2. Set `dimension_attributes: true`
+
+## 6. Make any other necessary changes.
+
+Look through the options in the sidebar to the left, adjust as required. Note that the `data_*`
+output formats have a few special options, documented on their respective pages.

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,43 +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', '< 4.0']
+
+  # 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', '~> 0.8'
-  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 '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