jekyll_picture_tag 1.11.0 → 2.0.0

data/docs/users/presets/examples.md

@@ -0,0 +1,111 @@
+---
+sort: 2
+---
+# Examples
+
+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: 11
+---
+
+# 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: 10
+---
+
+# 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: 4
+---
+
+# 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: 8
+---
+
+# 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 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).
+
+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,75 @@
+---
+sort: 3
+---
+
+# 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).
+
+## Reference
+
+{% include list.liquid %}

data/docs/users/presets/link_source.md

@@ -0,0 +1,16 @@
+---
+sort: 12
+---
+
+# Source Image Link
+
+_Format:_ `link_source: (true|false)`
+
+_Example:_ `link_source: true`
+
+_Default:_ `false`
+
+Surround image with a link to the original source file. Your source image
+directory must be published as part of the compiled site. If you run into weird
+issues with the output, see the [notes]({{ site.baseurl }}/notes).
+

data/docs/users/presets/markup_formats/fragments.md

@@ -0,0 +1,48 @@
+---
+sort: 3
+---
+
+# Fragments
+
+The following are not complete markup; they're building blocks that you can use
+to make things outside the scope of JPT.
+
+- `direct_url` Generates an image and returns only its url. Uses
+  `fallback_width` and `fallback_format`.
+
+  ```yml
+  # _data/picture.yml
+
+  markup_presets:
+    direct:
+      markup: direct_url
+      fallback_width: 800
+      fallback_format: webp
+  ```
+
+  ```
+  {% raw %}
+  {% picture direct myimage.jpg %} --> /generated/myimage-800-abcd12345.webp
+  {% endraw %}
+  ```
+
+- `naked_srcset`: Builds a srcset and nothing else (not even the surrounding quotes). Note that the
+  (image) `format` setting must still be an array, even if you only give it one
+  value. (This is on the list of things to improve.)
+
+  ```yml
+  # _data/picture.yml
+
+  markup_presets:
+    only_srcset:
+      markup: naked_srcset
+      widths: [800, 1200, 1600]
+      format: [webp]
+  ```
+
+  ```
+  {% raw %}
+  {% picture only_srcset myimage.jpg %} --> 
+  /generated/myimage-800-abcd12345.webp 800w, /generated/myimage-1200-abcd12345.webp 1200w, (...)
+  {% endraw %}
+  ```