jekyll_picture_tag 1.10.2 → 2.0.0pre1

data/docs/users/presets/link_source.md

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

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: 2
+---
+
+# 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: 12
+---
+
+# 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: 5
+---
+
+# 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: 4
+---
+
+# 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.