jekyll_picture_tag 1.12.0 → 2.0.1

data/docs/users/presets/cropping.md

@@ -1,61 +1,60 @@
 ---
-sort: 5
+sort: 7
 ---
 
 # Cropping
 
-**Check the warning in the 
-[installation guide]({{ site.baseurl }}/users/installation) 
-before using this feature.**
-
 ## Crop & Media Crop
 
 _Format:_
 
 ```yaml
-    crop: (geometery)
+    crop: (aspect ratio)
     media_crop:
-      (media_preset): (geometry)
-      (media_preset): (geometry)
+      (media_preset): (aspect ratio)
+      (media_preset): (aspect ratio)
       (...)
 ```
 
 _Example:_
 
 ```yaml
-    crop: 16:9
+    crop: '16:9'
     media_crop:
-      tablet: 3:2
-      mobile: 1:1
+      tablet: '3:2'
+      mobile: '1:1'
 ```
 
-Crop geometry, given either generally or for specific media presets. The
+Crop aspect ratio, given either generally or for specific media presets. The
 hierarchy is: `tag argument` > `media_crop:` > `crop:`.
 
-This setting accepts the same arguments as the `crop geometry` 
+This setting accepts the same arguments as the `crop` 
 [tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop).
 
-## Gravity & Media Gravity
+## Keep & Media Keep
 
 ```yaml
-    gravity: (gravity)
-    media_gravity:
-      (media_preset): (gravity)
-      (media_preset): (gravity)
+    keep: (measure)
+    media_keep:
+      (media_preset): (measure)
+      (media_preset): (measure)
       (...)
 ```
 
 _Example:_
 
 ```yaml
-    gravity: north
+    keep: attention
     media_gravity:
-      tablet: east
-      mobile: southwest
+      tablet: entropy
+      mobile: center
 ```
 
-Crop gravity, given either generally or for specific media presets. The hierarchy is:
-`tag argument` > `media_gravity:` > `gravity:` > `center` (default).
+Which part of the image to keep when cropping, given either generally or for specific media presets.
+The hierarchy is: `tag argument` > `media_keep:` > `keep:` > `attention` (default).
 
-This setting accepts the same arguments as the `crop gravity` 
-[tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop).
+This setting accepts the same arguments as the `keep` [tag parameter]({{ site.baseurl
+}}/users/liquid_tag/argument_reference/crop):
+* `center` or `centre`
+* `attention`
+* `entropy`

data/docs/users/presets/default.md

@@ -1,5 +1,5 @@
 ---
-sort: 13
+sort: 14
 ---
 
 # Default preset
@@ -17,7 +17,16 @@ presets:
     noscript: false
     link_source: false
     quality: 75
+    format_quality:
+      webp: 50
+      avif: 30
+      jp2: 30
+    strip_metadata: true
+    image_options:
+      avif:
+        compression: av1
+        speed: 8
     data_sizes: true
-    gravity: center
+    keep: attention
     dimension_attributes: false
 ```

data/docs/users/presets/examples.md

@@ -1,79 +1,111 @@
 ---
-sort: 12
+sort: 2
 ---
-# Example _data/picture.yml
+# Examples
 
-These are example settings- I mostly made them up off the top of my head. You
-probably don't want to just copy-paste them.
+The following example media queries & presets (except for `default`) are built-in with a `jpt-`
+prefix. For example, the `desktop` media query below can be used with `jpt-desktop`, and the `webp`
+preset below can be used with `jpt-webp`.
 
 ```yaml
 # _data/picture.yml
 
+# These are used in several places. You likely want to enter whatever CSS media queries your site
+# uses here.
 media_queries:
-  wide_desktop: 'min-width: 1801px'
-  desktop: 'max-width: 1800px'
-  wide_tablet: 'max-width: 1200px'
-  tablet: 'max-width: 900px'
-  mobile: 'max-width: 600px'
+    mobile: 'max-width: 480px'
+    tablet: 'max-width: 768'
+    laptop: 'max-width: 1024px'
+    desktop: 'max-width: 1200'
+    wide: 'min-width: 1201'
 
 presets:
+  # This entry is purely an example. It is not the default JPT preset, nor is it available as a
+  # built-in.
   default:
-    markup: auto
-    link_source: true # wrap images in a link to the original source image.
-    dimension_attributes: true # Page reflow begone!
-
-    formats: [webp, original] # Must be an array, and order matters.
+    formats: [webp, original] # Order matters!
+    widths: [200, 400, 800, 1200, 1600] # Image widths, in pixels.
 
-    widths: [200, 400, 800, 1600] # Must be an array.
-    media_widths: # Because a cell phone doesn't want 1600 pixels.
-      mobile: [200, 400, 600] 
-      tablet: [400, 600, 800]
-
-    sizes: 
-      mobile: 100vw
+    # The sizes attribute is both important, and impossible to offer good defaults for. You need to
+    # learn about it. Short version: Web browsers parse web pages line-by-line. When they run into
+    # an external asset they must download, they start that process immediately, without waiting to
+    # finish rendering 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.
+    #
+    # If you do not provide this, the web browser will assume the image is 100vw (100% the width of
+    # the viewport.)
+    #
+    # This doesn't have to be pixel-perfect, just close enough for the browser to make a good
+    # choice. Keys are media queries defined above, values are how large the image will be when
+    # that media query is true. You can't use % (percentage width of the parent container) for the
+    # same reason we have to do this at all.
+    sizes:
+      mobile: calc(100vw - 16px)
       tablet: 80vw
+
+    # Size is unconditional; provided either after all conditional sizes (above) or alone. If you
+    # only have a 'size' (no 'sizes'), and it's a constant (px, em, or rem), you should use a
+    # pixel-ratio srcset.
     size: 800px
 
-    fallback_width: 800
-    fallback_format: original
+    link_source: true # wrap images in a link to the original source image.
+    dimension_attributes: true # Page reflow begone!
 
+    # You can add any HTML attribute you like, to any HTML element which JPT creates:
     attributes:
+      # parent refers to the outermost tag; <picture> if it's present, otherwise the <img>.
       parent: 'data-downloadable="true"'
       picture: 'class="awesome" data-volume="11"'
       img: 'class="some-other-class"'
       a: 'class="image-link"'
 
-  # This is an example of how you would create a 'multiplier' based srcset;
-  # useful when an image will always be the same size on all screens (icons,
-  # graphics, thumbnails, etc), but you'd like to supply higher resolution
-  # images to devices with higher pixel ratios.
-  icon:
-    base_width: 20 # How wide the 1x image should be.
-    pixel_ratios: [1, 1.5, 2]
-    fallback_width: 20
+  # You can use this as jpt-webp. All following presets follow the same pattern.
+  webp:
+    formats: [webp, original]
+
+  # Avif is the new hotness coming down the pipe. Browser support is bad and they are slow to
+  # generate, but you get good file sizes even compared to webp of similar quality.
+  avif:
+    formats: [avif, webp, original]
+
+  # Your build times will suffer, but everyone is happy.
+  loaded:
+    formats: [avif, jp2, webp, original]
+    dimension_attributes: true
+
+  # This is an example of how you would create a 'multiplier' based srcset; useful when an image
+  # will always be the same size on all screens (icons, graphics, thumbnails, etc), but you'd like
+  # to supply higher resolution images to devices with higher pixel ratios.
+  thumbnail:
+    base_width: 250 # How wide the 1x image should be.
+    pixel_ratios: [1, 1.5, 2] # Which multipliers to target.
+    fallback_width: 250 # The default is 800, which is probably too big.
+    formats: [webp, original]
     attributes:
-      img: 'class="icon"'
+      picture: 'class="thumbnail"'
 
-  # Here's an example of how you'd configure jekyll-picture-tag to work with
-  # something like lazyload: https://github.com/verlok/lazyload
+  # Another pixel-ratio example.
+  avatar:
+    # Say your layout demands a square:
+    crop: 1:1
+    base_width: 100
+    pixel_ratios: [1, 1.5, 2]
+    fallback_width: 100,
+
+  # Here's an example of how you'd configure JPT to work with something like lazyload:
+  # https://github.com/verlok/lazyload
+  # Remember to add a sizes attribute, unless it's close to 100vw all the time.
   lazy:
     markup: data_auto
     formats: [webp, original]
-    widths: [200, 400, 600, 800]
     noscript: true # add a fallback image inside a <noscript> tag.
-    attributes: 
-      img: class="lazy"
+    attributes:
+      parent: class="lazy"
 
-  # This is an example of how you'd get generated image and a URL, and nothing
-  # else.
+  # This is an example of how you'd get a single generated image, a URL, and nothing else.
   direct:
     markup: direct_url
     fallback_format: webp
     fallback_width: 600
-
-  # Here's a naked srcset. Doesn't even give you the surrounding quotes.
-  srcset:
-    markup: naked_srcset
-    formats: [webp] # must be an array, even if it only has one item
-
 ```

data/docs/users/presets/fallback_image.md

@@ -1,5 +1,5 @@
 ---
-sort: 9
+sort: 11
 ---
 
 # Fallback Image

data/docs/users/presets/html_attributes.md

@@ -1,5 +1,5 @@
 ---
-sort: 8
+sort: 10
 ---
 
 # Arbitrary HTML Attributes

data/docs/users/presets/image_formats.md

@@ -1,12 +1,12 @@
 ---
-sort: 2
+sort: 4
 ---
 
 # Image Formats
 
-_Format:_ `format: [format1, format2, (...)]`
+_Format:_ `formats: [format1, format2, (...)]`
 
-_Example:_ `format: [webp, original]`
+_Example:_ `formats: [webp, original]`
 
 _Default_: `original`
 

data/docs/users/presets/image_quality.md

@@ -1,21 +1,12 @@
 --- 
-sort: 6
+sort: 8
 ---
 
-# Image Quality
+# Image Quality & Options
 
-## Quality
+Image quality is set per-format, using `format_quality`.
 
-  _Format:_ `quality: 0 <= integer <= 100`
-
-  _Example:_ `quality: 80`
-
-  _Default:_ `75`
-
-  Specify an image compression level for all image formats (where it makes
-  sense, anyway).
-
-## Format Quality
+## Constant Quality
 
   _Format:_
 
@@ -34,10 +25,96 @@ sort: 6
     webp: 55
   ```
 
-  _Default:_ quality setting
+  _Defaults:_ 
+
+  - webp - 50
+  - avif - 30
+  - jp2 - 30
+  - all others - 75
+
+## Variable Quality
+
+  ```yaml
+    format_quality: 
+      (format):
+        (image width): (quality setting)
+        (image width): (quality setting) 
+  ```
+
+  _Example:_
+
+  ```yaml
+    format_quality: 
+      jpg:
+        1000: 65
+        300: 100
+  ```
+
+Set a variable image quality, based on image width. Provide exactly 2 image widths and associated
+quality settings. Quality will be calculated as follows:
+
+  * For images smaller than the lowest image width, the setting for the lowest width is used. 
+  * For images larger than the highest image width, the setting for the highest width is used. 
+  * For images in between the 2, the quality setting will be linearly interpolated to some value in
+    between.
+
+  ![](quality_width_graph.png)
+
+Using this setting, you can get away with more compression on high pixel density screens without
+sacrificing image quality for low-density screens. Taking the example settings above:
+
+  * A 1500px image will use a quality of 65.
+  * A 200px image will use a quality of 100.
+  * A 500px image will use a quality of 90.
+
+## Strip Metadata
+
+_Format:_ `strip_metadata: (true|false)`
+
+_Example:_ `strip_metadata: false`
+
+_Default:_ `true`
+
+Remove EXIF data, which can save a few tens of kilobytes per image. This is set for all formats.
+
+## Image Format Options
+
+  _Format:_
+
+  ```yaml
+  image_options: 
+    format:
+      setting1: value
+      setting2: value
+      (...)
+    (...)
+  ```
+
+  _Example:_
+
+  ```yaml
+  image_options:
+    webp:
+      lossless: true
+  ```
+
+  _Default:_
+
+  ```yaml
+  image_options:
+    avif: 
+      compression: av1
+      speed: 8
+  ```
+
+Control the write options passed to libvips for each image output format. To see a list of options
+available for a given image format, search for the method `vips_(format)save` in
+[this](https://libvips.github.io/libvips/API/current/VipsForeignSave.html) API documentation. For
+example, png options can be found by searching for `vips_pngsave()`, leading
+[here](https://libvips.github.io/libvips/API/current/VipsForeignSave.html#vips-pngsave). See the
+optional arguments. `avif`'s options are under `vips_heifsave()`,
+[here](https://libvips.github.io/libvips/API/current/VipsForeignSave.html#vips-heifsave).
 
-  Specify quality settings for various image formats, allowing you to take
-  advantage of webp's better compression algorithm without trashing your jpg
-  images (for example). If you don't give a setting for a particular format
-  it'll fall back to the `quality` setting above, and if you don't set _that_
-  it'll default to 75.
+For all formats, note that
+- `Q:` (quality) is handled by the settings above.
+- `strip` is handled by the `strip_metadata` setting documented above.

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 %}