jekyll_picture_tag 1.10.2 → 2.0.0pre1

data/docs/users/presets/examples.md

@@ -0,0 +1,111 @@
+---
+sort: 1
+---
+# Example presets
+
+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:
+    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:
+    formats: [webp, original] # Order matters!
+    widths: [200, 400, 800, 1200, 1600] # Image widths, in pixels.
+
+    # 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
+
+    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"'
+
+  # 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:
+      picture: 'class="thumbnail"'
+
+  # 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]
+    noscript: true # add a fallback image inside a <noscript> tag.
+    attributes:
+      parent: class="lazy"
+
+  # 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
+```

data/docs/users/presets/fallback_image.md

@@ -0,0 +1,28 @@
+---
+sort: 10
+---
+
+# Fallback Image
+
+A valid `<picture>` tag must contain an `<img>` tag, and a valid `<img>` tag
+must contain a `src` with a single image. We call this the 'fallback' image.
+
+## Fallback Width
+
+_Format:_ `fallback_width: (integer)`
+
+_Example:_ `fallback_width: 800`
+
+_Default_: `800`
+
+Width of the fallback image.
+
+## Fallback Format
+
+_Format:_ `fallback_format: (format)`
+
+_Example:_ `fallback_format: jpg`
+
+_Default_: `original`
+
+Format of the fallback image.

data/docs/users/presets/html_attributes.md

@@ -0,0 +1,26 @@
+---
+sort: 9
+---
+
+# Arbitrary HTML Attributes
+
+_Format:_
+
+```yaml
+attributes:
+  (element): '(attributes)'
+  (...)
+```
+
+_Example:_
+
+```yaml
+attributes:
+  img: 'class="soopercool" data-awesomeness="11"'
+  picture: 'class="even-cooler"'
+```
+
+HTML attributes you would like to add. The same arguments are available here as
+in the liquid tag: HTML element names, `alt:`, `link:`, and `parent:`. Unescaped
+double quotes cause problems with yml, so it's recommended to surround them with
+single quotes.

data/docs/users/presets/image_formats.md

@@ -0,0 +1,21 @@
+---
+sort: 3
+---
+
+# Image Formats
+
+_Format:_ `formats: [format1, format2, (...)]`
+
+_Example:_ `formats: [webp, original]`
+
+_Default_: `original`
+
+Array (yml sequence) of the image formats you'd like to generate, in decreasing
+order of preference. Browsers will render the first format they find and
+understand, so **If you put jpg before webp, your webp images will never be
+used**. `original` does what you'd expect. To supply webp, you must have an
+imagemagick webp delegate installed. (Most package managers just name it 'webp')
+
+_Supported formats are anything which imagemagick supports, and has an installed
+delegate. See a list by running `$ convert --version`_.
+

data/docs/users/presets/image_quality.md

@@ -0,0 +1,120 @@
+--- 
+sort: 7
+---
+
+# Image Quality & Options
+
+Image quality is set per-format, using `format_quality`.
+
+## Constant Quality
+
+  _Format:_
+
+  ```yaml
+  format_quality:
+    (format): 0 <= integer <= 100
+    (...)
+  ```
+
+  _Example:_
+
+  ```yaml
+  format_quality:
+    jpg: 75
+    png: 65
+    webp: 55
+  ```
+
+  _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 globally, not
+per-format.
+
+## 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. 
+
+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

@@ -0,0 +1,137 @@
+---
+sort: 3
+---
+
+# Writing 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;
+the preset determines what markup, what image sizes, and what image formats to
+create, while the picture tag determines which image(s) will be used.  They are
+stored in `_data/picture.yml`. You will have to create this file, and probably
+the `_data/` directory as well.
+
+Any settings which are specific to particular markup formats are documented on
+their respective markup format page.
+
+_General Format:_
+
+```yaml
+# _data/picture.yml
+
+presets:
+  (name):
+    (option): (setting)
+    (option): (setting)
+    (...)
+  (...)
+```
+
+_Example:_
+
+```yaml
+# _data/picture.yml
+
+presets:
+  default:
+    formats: [webp, original]
+    widths: [200, 400, 800, 1600]
+    link_source: true
+
+  lazy:
+    markup: data_auto
+    widths: [200, 400, 800, 1600]
+    link_source: true
+    noscript: true
+```
+
+## 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
+
+media_queries:
+  (name): '(media query)'
+  (name): '(media query)'
+  (name): '(media query)'
+```
+
+Example:
+
+```yaml
+media_queries:
+  full_width: 'min-width: 901px'
+  tablet: 'min-width: 601px'
+  mobile: 'max-width: 600px'
+```
+
+More information [here](media_queries).
+
+## 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. 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.)