jekyll_picture_tag 1.10.1 → 1.14.0

data/docs/users/presets/default.md

@@ -0,0 +1,24 @@
+---
+sort: 14
+---
+
+# Default preset
+
+Here are the default preset settings:
+
+```yml
+presets:
+  default:
+    markup: auto
+    formats: [original]
+    widths: [400, 600, 800, 1000]
+    fallback_width: 800
+    fallback_format: original
+    noscript: false
+    link_source: false
+    quality: 75
+    data_sizes: true
+    gravity: center
+    dimension_attributes: false
+    strip_metadata: true
+```

data/docs/users/presets/examples.md

@@ -0,0 +1,79 @@
+---
+sort: 13
+---
+# Example _data/picture.yml
+
+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.
+
+```yaml
+# _data/picture.yml
+
+media_queries:
+  wide_desktop: 'min-width: 1801px'
+  desktop: 'max-width: 1800px'
+  wide_tablet: 'max-width: 1200px'
+  tablet: 'max-width: 900px'
+  mobile: 'max-width: 600px'
+
+presets:
+  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.
+
+    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
+      tablet: 80vw
+    size: 800px
+
+    fallback_width: 800
+    fallback_format: original
+
+    attributes:
+      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
+    attributes:
+      img: 'class="icon"'
+
+  # Here's an example of how you'd configure jekyll-picture-tag to work with
+  # something like lazyload: https://github.com/verlok/lazyload
+  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"
+
+  # This is an example of how you'd get generated image and 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

@@ -0,0 +1,28 @@
+---
+sort: 9
+---
+
+# 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: 8
+---
+
+# 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: 2
+---
+
+# Image Formats
+
+_Format:_ `format: [format1, format2, (...)]`
+
+_Example:_ `format: [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,105 @@
+--- 
+sort: 6
+---
+
+# Image Quality
+
+Image quality can be as simple as a constant for all images, or can be varied based on image width
+and output format.
+
+```note
+For lossless webp images, set quality to 100.
+```
+
+
+## Quality
+
+### Constant
+
+  _Format:_ `quality: 0 <= integer <= 100`
+
+  _Example:_ `quality: 80`
+
+  _Default:_ `75`
+
+  Specify an image compression level for all widths, all image formats.
+
+### Variable
+
+  _Format:_ 
+
+```yaml
+  quality: 
+    (image width): (quality setting)
+    (image width): (quality setting) 
+```
+
+  _Example:_ 
+
+```yaml
+  quality: 
+    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.
+
+
+## Format Quality
+
+  _Format:_
+
+  ```yaml
+  format_quality:
+    (format): 0 <= integer <= 100
+    (...)
+  ```
+
+  ```yaml
+    format_quality: 
+      (format):
+        (image width): (quality setting)
+        (image width): (quality setting) 
+  ```
+
+
+  _Example:_
+
+  ```yaml
+  format_quality:
+    jpg: 75
+    png: 65
+    webp: 55
+  ```
+
+  ```yaml
+    format_quality: 
+      jpg:
+        1000: 65
+        300: 100
+      (...)
+  ```
+
+  _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.

data/docs/users/presets/index.md

@@ -0,0 +1,101 @@
+---
+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.
+
+## 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
+# _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
+```
+
+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:
+
+{% raw %}
+`{% picture my-preset image.jpg %}`
+{% endraw %}
+
+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.
+
+```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.
+```
+
+## Markup Format
+
+The high level, overall markup format is controlled with the `markup:` setting,
+documented [here](markup_formats).
+
+## 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). 
+
+Use a [pixel-ratio srcset](pixel_ratio_srcsets) when the image will always be
+the same size, regardless of screen width (thumbnails and icons). 
+
+## Settings reference
+
+{% include list.liquid %}

data/docs/users/presets/link_source.md

@@ -0,0 +1,16 @@
+---
+sort: 10
+---
+
+# 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 %}
+  ```