jekyll_picture_tag 1.11.0 → 1.12.0

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,43 @@
+--- 
+sort: 6
+---
+
+# Image Quality
+
+## Quality
+
+  _Format:_ `quality: 0 <= integer <= 100`
+
+  _Example:_ `quality: 80`
+
+  _Default:_ `75`
+
+  Specify an image compression level for all image formats (where it makes
+  sense, anyway).
+
+## Format Quality
+
+  _Format:_
+
+  ```yaml
+  format_quality:
+    (format): 0 <= integer <= 100
+    (...)
+  ```
+
+  _Example:_
+
+  ```yaml
+  format_quality:
+    jpg: 75
+    png: 65
+    webp: 55
+  ```
+
+  _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.

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 %}
+  ```

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: 1
+---
+
+# 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: 11
+---
+
+# 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: 4
+---
+
+# 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.
+