jekyll_picture_tag 1.11.0 → 2.0.0

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

@@ -0,0 +1,57 @@
+---
+sort: 2
+---
+
+# Javascript Friendly
+
+These are analogous to their plain HTML counterparts, but instead of `src`,
+`srcset`, and `sizes`, you get `data-src`, `data-srcset`, and `data-sizes`. This
+allows you to use javascript for things like [lazy
+loading](https://github.com/verlok/lazyload).
+
+- `data_picture`
+
+  ```html
+    <picture> 
+      <source data-srcset="..." data-sizes="...">
+      <source data-srcset="..." data-sizes="...">
+      (...)
+      <img data-src="...">
+    </picture>
+  ```
+
+- `data_img`
+  ```html
+    <img data-srcset="..." data-src="..." data-sizes="...">
+  ```
+
+- `data_auto` - `data_picture` when needed, otherwise `data_img`.
+
+## Special Options
+
+The following preset settings only apply to these output formats.
+
+- `noscript`
+
+  _Format:_ `noscript: true|false`
+
+  _Default:_ `false`
+
+  Include a basic `img` fallback within a `<noscript>` tag, giving your
+  non-javascript-running users something to look at.
+
+  ```html
+    <img data-srcset="..." data-src="..." data-sizes="...">
+    <noscript>
+      <img src="..." alt="...">
+    </noscript>
+  ```
+
+- `data_sizes`
+
+  _Format:_ `data_sizes: true|false`
+
+  _Default:_ `true`
+
+  This option sets whether you would like JPT's auto-generated sizes to be returned as a
+  `data-sizes` attribute or a normal `sizes` attribute.

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

@@ -0,0 +1,43 @@
+---
+sort: 1
+---
+
+# Markup Formats
+
+Define what format the generated text will take. Select one by setting
+`markup:` in the relevant [preset]({{ site.baseurl }}/users/presets).
+
+_Format:_ `markup: (setting)`
+
+_Default_: `auto`
+
+
+Example:
+
+```yml
+# /_data/picture.yml
+
+markup_presets:
+  my_preset:
+    markup: data_auto
+```
+
+## Valid options:
+
+### Standard HTML:
+- `auto` - default
+- `picture`
+- `img`
+
+### Javascript Friendly:
+- `data_auto`
+- `data_picture`
+- `data_img`
+
+### Fragments:
+- `direct_url`
+- `naked_srcset`
+
+## Reference:
+
+{% include list.liquid %}

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

@@ -0,0 +1,25 @@
+---
+sort: 1
+---
+
+# Standard HTML
+
+- **`picture`** - `<picture>` element surrounding a `<source>` tag for each required srcset, and a
+  fallback `<img>`:
+
+  ```html
+    <picture> 
+      <source srcset="..." sizes="..." media="..." type="...">
+      <source srcset="..." sizes="..." media="..." type="...">
+      (...)
+      <img src="...">
+    </picture
+  ```
+
+- **`img`** - a single `<img>` tag with a `srcset` entry:
+
+  ```html
+  <img src="..." srcset="..." sizes="..." alt="..." width="..." height="...">
+  ```
+
+- **`auto`** - Supply an img tag when you have only one srcset, otherwise supply a picture tag.

data/docs/users/presets/media_queries.md

@@ -0,0 +1,36 @@
+---
+sort: 3
+---
+
+# Media Queries
+
+Jekyll Picture Tag handles media queries by letting you define them by name in
+`_data/picture.yml`, and then referencing that name whenever you need it.
+
+_Format:_
+
+```yaml
+# _data/picture.yml
+
+media_queries:
+  (name): (css media query)
+  (name): (css media query)
+  (...)
+
+```
+
+_Example:_
+
+```yaml
+# _data/picture.yml
+
+media_queries:
+  mobile: "max-width: 600px"
+  tablet: "max-width: 800px"
+  ultrawide: "min-width: 1400px"
+```
+
+They are used in a few different places: specifying alternate source images in
+your liquid tag, building the 'sizes' attribute within your presets, and in a
+few configuration settings. Quotes are recommended, because yml gets confused by
+colons.

data/docs/users/presets/nomarkdown_override.md

@@ -0,0 +1,17 @@
+---
+sort: 13
+---
+
+# Nomarkdown Override
+
+_Format:_ `nomarkdown: (true|false)`
+
+_Example:_ `nomarkdown: false`
+
+_Default:_ `nil`
+
+Hard setting for `{::nomarkdown}` tags, overrides both autodetection and the
+global setting in `_config.yml`.
+
+See this [note]({{ site.baseurl }}/users/notes/kramdown_bug) for a detailed
+explanation.

data/docs/users/presets/pixel_ratio_srcsets.md

@@ -0,0 +1,32 @@
+---
+sort: 6
+---
+
+# Pixel Ratio Srcsets
+
+A Pixel Ratio srcset looks like this:
+
+```html
+srcset="myimage-200.jpg 1.0x, myimage-300.jpg 1.5x, myimage-400.jpg 2.0x" 
+```
+
+To use one, set `pixel_ratios` and `base_width`. They are most appropriate for
+thumbnails and icons, where the image will be the same size on all screens, and
+all you need to account for is pixel ratio.
+
+## Base Width
+
+_Format:_ `base_width: integer`
+
+_Example:_ `base_width: 100`
+
+Sets how wide the 1x image should be. Required when using a Pixel Ratio srcset.
+
+## Pixel Ratios
+
+_Format:_ `pixel_ratios: [number, number, number (...)]`
+
+_Example:_ `pixel_ratios: [1, 1.5, 2]`
+
+Array of images to construct, given in multiples of the base width.
+

data/docs/users/presets/width_height_attributes.md

@@ -0,0 +1,34 @@
+---
+sort: 8
+---
+
+# Width & Height (Anti-Loading-Jank)
+
+_Format:_
+
+```yml
+dimension_attributes: true | false
+```
+
+_Example:_
+
+```yml
+dimension_attributes: true
+```
+
+_Default:_ `false`
+
+Prevent page reflow (aka jank) while images are loading, by adding `width` and
+`height` attributes to the `<img>` tag in the correct aspect ratio.
+
+For an explanation of why and how you want to do this,
+[here](https://youtu.be/4-d_SoCHeWE) is a great explanation.
+
+Caveats: 
+  * You need either `width: auto;` or `height: auto;` set in CSS on the `<img>`
+  tags, or they will be stretched.
+  * This works on `<img>` tags and `<picture>` tags when offering images in
+  multiple widths and formats, but it does not work if you are using art
+  direction (in other words, if you have multiple source images). This is
+  because these attributes can only be applied to the `<img>` tag, of which
+  there is exactly one.

data/docs/users/presets/width_srcsets.md

@@ -0,0 +1,123 @@
+---
+sort: 5
+---
+
+# Width Based Srcsets
+
+A width based srcset looks like this:
+
+```html
+srcset="myimage-800.jpg 800w, myimage-1200.jpg 1200w, myimage-2000.jpg 2000w"
+```
+
+You should use it when the size of an image depends on the size of the screen used to show it, which
+generally means anything bigger than about 300 pixels. It's the default; to use it specify a
+`widths` setting (or don't, for the default set), and optionally the `sizes` and `size` settings.
+
+## A word on sizes
+
+The `sizes` attribute is both important, and impossible to offer good defaults for. Web browsers parse
+web pages line-by-line. When they run into an external asset (such as an image) they must download,
+they start that process immediately without waiting to draw 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.
+
+It doesn't have to be pixel-perfect, just close enough for the browser to make a good choice.  You
+can't use % (percentage width of the parent container) for the same reason we have to do this at
+all. If you do not provide it, the web browser will assume the image is 100vw (100% the width of
+the viewport.)
+
+## How to create a sizes attribute
+
+First, Load the page and image as they will appear in the final site. (Basically write the rest of
+the preset.)
+
+Next, using either dev tools or by manipulating the browser window itself, determine how large the
+image will be for all reasonable screen sizes. Organize this information into CSS measurements
+(using `vw`, `vh`, `px`, `em`, or a calculation based on those units) associated with your
+named CSS media queries, and enter them into the relevant preset. **Order matters**; enter these
+from most to least restrictive. The browser will ignore everything after the first media query it
+finds that is true.
+
+**Example:** on my particular site, for screens 900px or smaller, inline images are the width of the
+viewport minus 9px of padding on either side. For screens 901px or larger, they are a constant 862px
+wide. The relevant lines in my config file look like this:
+
+```yml
+media_queries: 
+  full_width: 'min-width: 901px'
+  # (...)
+
+presets:
+  default:
+  # (...)
+  sizes:
+    full_width: 862px
+  size: calc(100vw - 18px)
+```
+
+## Settings Reference
+
+### Widths
+
+_Format:_ `widths: [integer, integer, (...)]`
+
+_Example:_ `widths: [600, 800, 1200]`
+
+_Default_: `[400, 600, 800, 1000]`
+
+Array of image widths to generate, in pixels.
+
+### Media Widths
+
+_Format:_
+
+```yml
+media_widths:
+  (media_query name): [integer, integer, (...)]
+```
+
+_Example:_
+
+```yml
+media_widths:
+  mobile: [400, 600, 800]
+```
+
+_Default:_ `widths` setting
+
+If you are using art direction, there is no sense in generating desktop-size files for your mobile
+image. Similarly, there's no sense in generating 300px wide versions of your ultrawide crop. You can
+specify sets of widths to associate with given media queries.
+
+### Sizes
+
+_Format:_
+
+```yml
+sizes:
+  (media preset): (CSS dimension)
+  (...)
+```
+
+_Example:_
+
+```yml
+sizes:
+  mobile: 80vw
+  tablet: 60vw
+  desktop: 900px
+```
+
+Conditional sizes, used to construct the `sizes=` HTML attribute telling the browser how wide your
+image will be (on the screen) when a given media query is true. CSS dimensions can be given in `px`,
+`em`, or `vw`. Provide these in order of most restrictive to least restrictive. The browser will
+choose the first one with an applicable media query.
+
+### Size
+
+_Format:_ `size: (CSS Dimension)`
+
+_Example:_ `size: 80vw`
+
+Unconditional `sizes` setting, to be supplied either alone or after all conditional sizes.

data/docs/users/presets/writing_presets.md

@@ -0,0 +1,65 @@
+---
+sort: 1
+---
+
+# 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. Consider enabling 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 necessary changes.
+
+Look through the options in the sidebar to the left, adjust as required. Note that the `data_*`
+output formats have a few special options, documented on their respective pages.