jekyll_picture_tag 1.13.0 → 2.0.2

data/docs/users/presets/cropping.md

@@ -1,22 +1,18 @@
 ---
-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)
       (...)
 ```
 
@@ -29,33 +25,36 @@ _Example:_
       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,46 +1,54 @@
 --- 
-sort: 6
+sort: 8
 ---
 
-# Image Quality
+# Image Quality & Options
 
-Image quality can be as simple as a constant for all images, or can be varied based on image width
-and output format.
+Image quality is set per-format, using `format_quality`.
 
-```note
-For lossless webp images, set quality to 100.
-```
+## Constant Quality
 
+  _Format:_
 
-## Quality
-
-### Constant
-
-  _Format:_ `quality: 0 <= integer <= 100`
+  ```yaml
+  format_quality:
+    (format): 0 <= integer <= 100
+    (...)
+  ```
 
-  _Example:_ `quality: 80`
+  _Example:_
 
-  _Default:_ `75`
+  ```yaml
+  format_quality:
+    jpg: 75
+    png: 65
+    webp: 55
+  ```
 
-  Specify an image compression level for all widths, all image formats.
+  _Defaults:_ 
 
-### Variable
+  - webp - 50
+  - avif - 30
+  - jp2 - 30
+  - all others - 75
 
-  _Format:_ 
+## Variable Quality
 
-```yaml
-  quality: 
-    (image width): (quality setting)
-    (image width): (quality setting) 
-```
+  ```yaml
+    format_quality: 
+      (format):
+        (image width): (quality setting)
+        (image width): (quality setting) 
+  ```
 
-  _Example:_ 
+  _Example:_
 
-```yaml
-  quality: 
-    1000: 65
-    300: 100
-```
+  ```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:
@@ -59,47 +67,54 @@ sacrificing image quality for low-density screens. Taking the example settings a
   * A 200px image will use a quality of 100.
   * A 500px image will use a quality of 90.
 
+## Strip Metadata
 
-## Format Quality
+_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
-  format_quality:
-    (format): 0 <= integer <= 100
+  image_options: 
+    format:
+      setting1: value
+      setting2: value
+      (...)
     (...)
   ```
 
-  ```yaml
-    format_quality: 
-      (format):
-        (image width): (quality setting)
-        (image width): (quality setting) 
-  ```
-
-
   _Example:_
 
   ```yaml
-  format_quality:
-    jpg: 75
-    png: 65
-    webp: 55
+  image_options:
+    webp:
+      lossless: true
   ```
 
+  _Default:_
+
   ```yaml
-    format_quality: 
-      jpg:
-        1000: 65
-        300: 100
-      (...)
+  image_options:
+    avif: 
+      compression: av1
+      speed: 8
   ```
 
-  _Default:_ quality setting
-
-  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. 
-
-  Note that this setting can accept the same variable quality setting format as the basic `quality` setting.
+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).
+
+For all formats, note that
+- `Q:` (quality) is handled by the settings above.
+- `strip` is handled by the `strip_metadata` setting documented above.