jekyll_picture_tag 1.14.0 → 2.0.0pre1

data/docs/users/presets/default.md

@@ -1,5 +1,5 @@
 ---
-sort: 14
+sort: 12
 ---
 
 # Default preset
@@ -17,8 +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
-    strip_metadata: true
 ```

data/docs/users/presets/examples.md

@@ -1,79 +1,111 @@
 ---
-sort: 13
+sort: 1
 ---
-# Example _data/picture.yml
+# Example presets
 
-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: 10
 ---
 
 # Fallback Image

data/docs/users/presets/html_attributes.md

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

data/docs/users/presets/image_formats.md

@@ -1,12 +1,12 @@
 ---
-sort: 2
+sort: 3
 ---
 
 # 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: 7
 ---
 
-# 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:_ `strip_metadata: (true|false)`
+
+_Example:_ `strip_metadata: false`
+
+_Default:_ `true`
 
-## Format Quality
+Remove EXIF data, which can save a few tens of kilobytes per image. This is set globally, not
+per-format.
+
+## 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. 
+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. 
 
-  Note that this setting can accept the same variable quality setting format as the basic `quality` setting.
+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

@@ -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,93 @@ 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
+
+**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:
+
+```yaml
+# _data/picture.yml
 
-{% raw %}
-`{% picture my-preset image.jpg %}`
-{% endraw %}
+media_queries:
+  (name): '(media query)'
+  (name): '(media query)'
+  (name): '(media query)'
+```
 
-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.
+Example:
 
-```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.
+```yaml
+media_queries:
+  full_width: 'min-width: 901px'
+  tablet: 'min-width: 601px'
+  mobile: 'max-width: 600px'
 ```
 
-## Markup Format
+More information [here](media_queries).
 
-The high level, overall markup format is controlled with the `markup:` setting,
-documented [here](markup_formats).
+## How to write a preset
 
-## Choosing a Srcset format
+### 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). 
+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.
 
-Use a [pixel-ratio srcset](pixel_ratio_srcsets) when the image will always be
-the same size, regardless of screen width (thumbnails and icons). 
+Accomplish this by setting `formats: [format1, format2, etc...]`
 
-## Settings reference
+* `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. Turn on 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 changes you need
+
+Here's a list of all preset settings available:
 
 {% include list.liquid %}
+
+(Note that the `data_*` output formats have a few special options, documented on their respective
+pages.)