jekyll_picture_tag 1.6.0 → 1.7.0

data/docs/migration.md

@@ -0,0 +1,178 @@
+# Migrating from versions < 1.0
+
+This document details the changes from previous versions (Everything before 1.0), and how to migrate
+an existing site to the new version. It won't be updated to reflect new features -- it simply
+describes how to get your site working with the new version.
+
+## Changes from previous versions:
+
+-   The default output formats are bone-stock HTML. Picturefill, as of version 3, no longer requires
+    special markup, so it remains compatible. Other javascript image solutions are supported with
+    the `data_` selection of markup formats. Interchange support is removed, though adding it again
+    is not difficult if there is demand for it.
+-   There are now 2 basic markup formats to choose from: `<source>` tags within a `<picture>`, and a
+    single `<img>` tag. If markup is set to 'auto', or if it is not set at all, the plugin will
+    automatically determine which is most appropriate. These formats also have `data_` counterparts
+    (i.e.  `data_auto`), which accomplish the same thing except setting respective data-attributes
+    to allow for lazy loading and such.
+-   There are also 2 srcset formats: one which supplies image width, and another which supplies
+    multiples (pixel ratios) of the base size.
+-   Source Keys are replaced by media query presets, which can also be used to create the 'sizes'
+    attribute.
+-   Jekyll Picture Tag no longer accepts height arguments, and will no longer crop images for you.
+    Aspect ratio will always be maintained.
+-   Multiple image widths are now supported, which will be used to create a corresponding srcset.
+-   Multiple image formats are now possible, including webp.
+-   PictureTag can now generate sizes attributes.
+-   Configuration takes a very different format. It should be simpler to write your config than the
+    old version, and migrating to it should not be difficult. Instead of creating individual source
+    keys, you supply an array of widths you'd like to construct. You can also supply an array (yaml
+    sequence) of formats, including 'original'.
+-   Only global settings are placed in `_config.yml`. Presets are moved to `_data/picture.yml`.
+
+## Migration
+
+### Liquid Tags
+
+Previous tag syntax has been extended, but backwards compatibility (and behaviour of previous
+versions) is maintained. 
+
+`{% picture img.jpg (implicit attributes) --(argument) (explicit attributes) %}`
+
+Implicit attributes are the old way. They are specified after the last source image, and before any
+explicit attributes (if they are included). These attributes are applied to the `<img>` tag, as in
+previous versions.
+
+Explicit attributes are the new way, documented in the readme. It is possible to use a mix of both,
+though I'm not sure why you would want to.
+
+There is one instance I can think of where you will have to change your tags:
+
+-   You use art direction with more than one different preset.
+-   These presets have source keys of the same name.
+-   These source keys have different associated media queries.
+
+If all of the above are true, you will either have to pick one media query which works for both, or
+rename one of them and change it everywhere it's used.
+
+Another trouble spot will be CSS; your output markup may change, meaning your CSS selectors may stop
+working.
+
+Outside of those situations, and provided you have created media_presets to match your old source
+keys, your existing tags should keep working. If they don't, it's a bug. Please report it.
+
+### Configuration
+
+The new configuration is described in the readme so I won't document it here, but I will show an old
+config alongside an equivalent new one.
+
+Example old configuration:
+
+```yml
+# _config.yml
+
+picture:
+  source: assets/images/_fullsize
+  output: generated
+  markup: picture
+  presets:
+    # Full width pictures
+    default:
+      ppi: [1, 1.5]
+      attr:
+        class: blog-full
+        itemprop: image
+      source_lrg:
+        media: "(min-width: 40em)"
+        width: 700
+      source_med:
+        media: "(min-width: 30em)"
+        width: 450
+      source_default:
+        width: 350
+        height: 200
+    # Half width pictures
+    half:
+      ppi: [1, 1.5]
+      attr:
+        data-location: "{{location}}"
+        data-active: nil
+      source_lrg:
+        media: "(min-width: 40em)"
+        width: 400
+      source_med:
+        media: "(min-width: 30em)"
+        width: 250
+      source_default:
+        width: 350
+    # Self-set resolution sources. Useful if you don't want a 1:1 image size to dppx ratio.
+    gallery:
+      source_wide_hi:
+        media: "(min-width: 40em) and (min-resolution: 1.5dppx)"
+        width: 900
+        height: 600
+      source_wide:
+        media: "(min-width: 40em)"
+        width: 600
+        height: 400
+      source_default:
+        width: 250
+        height: 250
+```
+
+Equivalent new configuration:
+
+```yml
+# _config.yml
+
+picture:
+  source: assets/images/_fullsize
+  output: generated
+```
+
+```yml
+# _data/picture.yml
+
+# Media presets are named media queries. To maintain compatibility with your tags, you need to
+# create presets of the same name as your old source keys. There is no limit to how many of them you
+# can have, so you're free to create additional new ones with better names to use going forward.
+media_presets:
+  source_lrg: '(min-width: 40em)'
+  source_med: '(min-width: 30em)'
+  source_wide_hi: "(min-width: 40em) and (min-resolution: 1.5dppx)"
+  source_wide: "(min-width: 40em)"
+
+markup_presets:
+  # You can't specify both widths and pixel ratios anymore. Choose one.
+  # Full width pictures, width-based srcset
+  default:
+    markup: picture
+    widths: [350, 450, 700]
+    attributes:
+      picture: 'class="blog-full" itemprop="image"'
+      
+  # Full width pictures, multiplier based srcset
+  default-ppi:
+    markup: picture
+    base_width: 350
+    pixel_ratios: [1, 1.5]
+    attributes:
+      picture: 'class="blog-full" itemprop="image"'
+
+  # Half width pictures
+  half:
+    widths: [250, 350, 400]
+    attributes: 
+      picture: 'data-location="{{location}}" data-active="nil"'
+
+  # Note you can't set heights anymore. You'll have to crop your images either ahead of time, or
+  # do it with CSS.
+  # 
+  # You have to use arrays for widths, even if only specifying a single value. There's no reason you
+  # can't add more.
+  gallery:
+    widths: [250]
+    media_widths:
+      source_wide_hi: [900]
+      source_wide: [600]
+```

data/docs/notes.md

@@ -0,0 +1,85 @@
+# Notes and FAQ
+
+## Extra {::nomarkdown} tags or mangled HTML?
+
+**TLDR up front:** There's a bug involving `<picture>` tags wrapped in `<a>` tags which is not in my
+power to fix.
+
+* If you're getting extra `{::nomarkdown}` tags floating around your images, add `nomarkdown: false`
+  to either the relevant preset or under `picture` in `_config.yml`. 
+
+* If you're getting mangled HTML when trying to wrap images with anchor tags, add `nomarkdown: true`
+  to the preset. 
+  
+#### What's going on here:
+
+Kramdown is Jekyll's default markdown parser. Kramdown gets grumpy when you give it a block level
+element (such as a `<picture>`) surrounded by a span level element (such as an `<a>`), and horribly
+mangles it. The fix for this is to tell Kramdown to chill with a `{::nomarkdown}..{:/nomarkdown}`
+wrapper.
+
+Jekyll Picture Tag can be called from many different places: a markdown file, an HTML file, an HTML
+layout for a markdown file, and an HTML include, to name a few. JPT tries its best to determine
+whether its output will be parsed by Kramdown or not, but Jekyll itself doesn't make this
+particularly easy which results in some false positives. (The one I'm most aware of is when a
+markdown file uses an HTML layout which includes a picture tag.) 
+
+Unfortunately, I don't see an easy way to fix this. We've gotten this far mostly by trial and error.
+I'll continue to work on improving the autodetection, but you can override this behavior explicitly. 
+
+#### The fix:
+
+By default, JPT will add a `{::nomarkdown}` tag if all of the following are true:
+* It thinks it's called from a markdown page
+* The image will be wrapped in an anchor tag (i.e. `link_source_image:` or a `--link` parameter)
+* This behavior hasn't been explicitly disabled. 
+
+You can disable nomarkdown tags globally by setting `nomarkdown: false` under the `picture:` key in
+`_config.yml`.
+
+You can enable or disable markdown tags per preset by adding `nomarkdown: true|false` to them.
+**This setting overrides everything else, both JPT autodetection and the global setting.**
+
+## Input checking
+
+Jekyll Picture Tag is very trusting. It doesn't do much checking of your inputs, and it does not
+fail gracefully if you for example pass it a string when it expects an array. It's on the to-do
+list, but for now if you get cryptic errors then double-check your settings and tag arguments.
+
+## Git LFS
+
+Putting this here because it bit me: If you want to use git LFS, make sure that your hosting
+provider makes those images available during the build process.  Netlify, for example, does not. You
+won't find this out until you have gone through the entire migration process and try to deploy for
+the first time.
+
+## Lazy Loading, and other javascript related tomfoolery
+
+Use one of the `data_` output formats and something like
+[LazyLoad](https://github.com/verlok/lazyload). The 'lazy' preset in the example config will work.
+
+## PictureFill
+
+[Picturefill](http://scottjehl.github.io/picturefill/) version 3 no longer requires special markup.
+Standard outputs should be compatible.
+
+## Managing Generated Images
+
+Jekyll Picture Tag creates resized versions of your images when you build the site. It uses a smart
+caching system to speed up site compilation, and re-uses images as much as possible. Filenames
+take the following format:
+
+`(original filename without extension)-(width)-(source hash).(appropriate extension)`
+
+Source hash is the first 5 characters of an md5 checksum of the source image.
+
+Try to use a base image that is larger than the largest resized image you need. Jekyll Picture Tag
+will warn you if a base image is too small, and won't upscale images.
+
+By specifying a `source` directory that is ignored by Jekyll you can prevent huge base images from
+being copied to the compiled site. For example, `source: assets/images/_fullsize` and `output:
+generated` will result in a compiled site that contains resized images but not the originals. Note
+that this will break source image linking, if you wish to enable it. (Can't link to images that
+aren't public!)
+
+The `output` directory is never deleted by Jekyll. You may want to empty it once in awhile, to clear out unused images. 

data/docs/presets.md

@@ -0,0 +1,407 @@
+# Writing Presets
+
+Presets are stored in `_data/picture.yml`, to avoid cluttering `_config.yml`. You will have to
+create this file, and probably the `_data/` directory as well.
+
+All settings are optional, moderately sensible defaults have been implemented.
+
+## Required Knowledge
+
+If you don't understand responsive images, you won't know what to do with these settings. Jekyll
+Picture tag is basically a programmatic implementation of the [MDN Responsive Images
+guide](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).
+
+If you don't know the difference between resolution switching and art direction, stop now and read it
+in detail. Ideally, play around with a basic HTML file, a few test images, and a few different
+browser widths until you understand it.
+
+## Example settings
+
+A more thorough example can be found under `docs/examples/_data/picture.yml`.
+
+```yml
+
+# _data/picture.yml
+
+media_presets:
+  wide_desktop: 'min-width: 1801px'
+  desktop: 'max-width: 1800px'
+  wide_tablet: 'max-width: 1200px'
+  tablet: 'max-width: 900px'
+  mobile: 'max-width: 600px'
+
+markup_presets:
+  default:
+    formats: [webp, original]
+    widths: [200, 400, 800, 1600]
+    media_widths:
+      mobile: [200, 400, 600]
+      tablet: [400, 600, 800]
+    size: 800px
+    sizes:
+      mobile: 100vw
+      desktop: 60vw
+    attributes:
+      picture: 'class="awesome" data-volume="11"'
+      img: 'class="some-other-class"'
+
+  icon:
+    base-width: 20
+    pixel_ratios: [1, 1.5, 2]
+
+  lazy:
+    markup: data_auto
+    formats: [webp, original]
+    widths: [200, 400, 600, 800]
+    noscript: true
+    attributes:
+      img: class="lazy"
+
+```
+
+## Media Presets
+
+*Format:*
+
+```yml
+media_presets:
+  (name): (css media query)
+  (name): (css media query)
+  (name): (css media query)
+  (...)
+
+```
+
+*Example:*
+
+```yml
+media_presets:
+  desktop: 'min-width: 1200px'
+```
+
+These are named media queries for use in a few different places.
+
+Keys are names by which you can refer to the media queries supplied as their respective values.
+These are used for specifying alternate source images in your liquid tag, and for building the
+'sizes' attribute within your presets. Quotes are required around the media
+queries, because yml gets confused by free colons.
+
+## Markup Presets
+
+*Format:*
+
+```yml
+markup_presets:
+  (name):
+    (option): (setting)
+    (option): (setting)
+    (option): (setting)
+    (...)
+  (another name):
+    (option): (setting)
+    (option): (setting)
+    (option): (setting)
+    (...)
+```
+
+*Example:*
+
+```yml
+markup_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
+```
+
+These are the 'presets' from previous versions, with different structure. Each entry is a
+pre-defined collection of settings to build a given chunk of HTML and its respective images. You
+can select one as the first argument given to the tag:
+
+`{% picture my-preset image.jpg %}`
+
+The `default` preset will be used if none is specified. A preset name can't contain the `.`, `:`,
+or `/` characters.
+
+#### A Note on srcsets, for the bad kids who didn't do the required reading.
+
+There are 2 srcset formats, one based on providing widths, the other based on providing multipliers.
+
+Width based srcsets look like this: `srcset="img.jpg 600w, img2.jpg 800w, img3.jpg 1000w"`. The
+`(number)w` tells the browser how wide that image file is. Browsers are smart, they know their
+device's pixel ratio, so in combination with the sizes attribute (if given, otherwise it assumes the
+image will be 100vw) they can select the best-fitting image for the space it will fill on the screen. This is generally the one you want to use.
+
+Multiplier based srcsets look like this: `srcset="img.jpg 1x, img2.jpg 1.5x, img3.jpg 3x"`. The
+browser is less smart here; it looks at its own device's pixel ratio, compares it to the given
+multiplier, and picks the closest one. It doesn't consider anything else at all. Multiplier based
+srcsets are best used when the image will always be the same size, on all screen sizes.
+
+To use a width based srcset in a preset, specify a `widths` setting (or don't, for the default), and
+optionally the `sizes` and `size` settings.
+
+To use a multiplier based srcset, set `pixel_ratios` and `base_width`.
+
+### Markup preset settings
+
+* **Markup format**
+
+  *Format:* `markup: (setting)`
+
+  *Default*: `auto`
+
+  Defines what format the generated HTML will take. Here are your options:
+
+  * `picture`: `<picture>` element surrounding a `<source>` tag for each required srcset, and a
+    fallback `<img>`.
+  * `img`: output a single `<img>` tag with a `srcset` entry.
+  * `auto`: Supply an img tag when you have only one srcset, otherwise supply a picture tag.
+  * `data_picture`, `data_img`, `data_auto`: Analogous to their 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)
+  * `direct_url`: Generates an image and returns only its url. Uses `fallback_` properties (width
+    and format)
+  * `naked_srcset`: Builds a srcset and nothing else (not even the surrounding quotes). Useful with
+    libraries requiring more complex or customized markup. Note that the (image) `format` setting
+    must still be an array, even if you can only give it one value.
+ 
+* **Image Formats**
+
+  *Format:* `format: [format1, format2, (...)]`  
+
+  *Example:* `format: [webp, original]`
+
+  *Default*: `original`
+
+  *Supported formats are anything which imagemagick supports, including the
+  following:*
+  * jpg/jpeg
+  * png
+  * gif
+  * webp
+  * jxr
+  * jp2
+
+  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')
+
+* **widths**
+
+  *Format:* `widths: [integer, integer, (...)]`
+
+  *Example:* `widths: [600, 800, 1200]`
+
+  *Default*: `[400, 600, 800, 1000]`
+
+  Array of image widths to generate, in pixels. For use when you want a size-based srcset
+  (`srcset="img.jpg 800w, img2.jpg 1600w"`).
+
+* **media_widths**
+
+    *Format:*
+
+    ```yml
+    media_widths:
+      (media preset 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. You can specify sets of widths to associate with given media queries. If not specified,
+  will use `widths` setting.
+
+* **Fallback Width**
+
+    *Format:* `fallback_width: (integer)`             
+
+    *Example:* `fallback_width: 800`
+
+    *Default*: `800`
+
+  Width of the fallback image.
+
+* **Fallback Image**
+
+    *Format:*  `fallback_format: (format)`
+
+    *Example:* `fallback_format: jpg`
+
+    *Default*: `original`
+
+  Format of the fallback image
+
+* **Sizes**
+
+    *Format:*
+    ```yml
+    sizes:
+      (media preset): (CSS dimension)
+      (media preset): (CSS dimension)
+      (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`. To be used along with a width based srcset.
+
+  Provide these in order of most restrictive to least restrictive. The browser will choose the 
+  first one with an applicable media query.
+
+  You don't have to provide a sizes attribute at all. If you don't, the browser will assume the
+  image is 100% the width of the viewport.
+
+  The same sizes attribute is used for every source tag in a given picture tag. This causes some
+  redundant markup, specifying sizes for situations when an image will never be rendered, but it 
+  keeps things a bit simpler.
+
+* **Size**
+
+  *Format:* `size: (CSS Dimension)`
+
+  *Example:* `size: 80vw`
+
+  Unconditional image width to give the browser (by way of the html sizes attribute), to be supplied
+  either alone or after all conditional sizes.
+
+* **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. If you set this, you must also
+  give a `base_width`.
+
+  Set this when you want a multiplier based srcset (example: `srcset="img.jpg 1x, img2.jpg 2x"`).
+
+* **Base Width**
+
+  *Format:* `base_width: integer`
+
+  *Example:* `base_width: 100`
+
+  When using pixel ratios, you must supply a base width. This sets how wide the 1x image should be.
+
+* **Quality**
+
+  *Format:* `quality: integer <= 100`
+
+  *Example:* `quality: 80`
+
+  *Default:* `75`
+
+  This allows you to specify an image compression level for all image formats (where it makes sense,
+  anyway). The next option allows you to set them per format.
+
+* **Format Quality**
+
+  *Format:* 
+
+  ```yml
+  format_quality:
+    (format): integer <= 100
+    (format): integer <= 100
+    (format): integer <= 100
+    (...)
+  ```
+
+  *Example:*
+
+  ```
+  format_quality:
+    jpg: 75
+    png: 65
+    webp: 55
+  ```
+
+  *Default:* quality setting (above)
+
+  This allows you to 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.
+
+* **HTML Attributes**
+
+  *Format:*
+
+  ```yml
+  attributes:
+    (element): '(attributes)'
+    (element): '(attributes)'
+    (element): '(attributes)'
+    (...)
+  ```
+
+  *Example:*
+
+  ```yml
+  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; element names, `alt:`, `url:`, and `parent:`. Unescaped double quotes cause problems with
+  yml, so it's recommended to surround them with single quotes.
+
+* **Noscript**
+
+    *Format:* `noscript: (true|false)`
+
+    *Example:* `noscript: true`
+
+    *Default:* `false`
+
+  For use with the `data_` output formats. When true, will include a basic `img` fallback within a
+  `<noscript>` tag after the standard html. This allows you to use lazy loading or other javascript
+  image tools, without breaking all of your images for non-javascript-enabled users.
+
+* **Source Image Linking**
+
+    *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
+  [notes](notes.md).
+
+* **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 [notes](notes.md) for a detailed explanation. 
+