jekyll_picture_tag 1.9.0 → 1.12.0

data/docs/users/notes/git_lfs.md

@@ -0,0 +1,7 @@
+# Git LFS
+
+  I'm 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.
+

data/docs/users/notes/github_pages.md

@@ -0,0 +1,5 @@
+# Github Pages?
+
+  Github Pages only allows a very short whitelist of plugins, which sadly does not include JPT. You
+  can either run it locally, then commit and push the generated files (rather than the source
+  files), or just host it some other way. I recommend Netlify.

data/docs/users/notes/html_attributes.md

@@ -0,0 +1,5 @@
+# HTML attributes
+
+  Jekyll Picture Tag has comprehensive attribute support for all generated HTML. You can add
+  attributes both through the [liquid tag]({{ site.baseurl }}/usage), and the [preset]({{
+  site.baseurl }}/presets) (scroll down a bit).

data/docs/users/notes/index.md

@@ -0,0 +1,6 @@
+---
+sort: 5
+---
+# Notes and FAQ
+
+{% include list.liquid %}

data/docs/users/notes/input_checking.md

@@ -0,0 +1,6 @@
+# Getting cryptic build errors?
+
+  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.
+

data/docs/users/notes/kramdown_bug.md

@@ -0,0 +1,41 @@
+# 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.**

data/docs/users/notes/managing_images.md

@@ -0,0 +1,21 @@
+# Managing Generated Images
+
+Jekyll Picture Tag creates resized versions of your images when you build the
+site. It uses a caching system to speed up site compilation, and re-uses images
+as much as possible. Filenames take the following format:
+
+`(original name without extension)-(width)-(id-string).(filetype)`
+
+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/users/presets/cropping.md

@@ -0,0 +1,61 @@
+---
+sort: 5
+---
+
+# Cropping
+
+**Check the warning in the 
+[installation guide]({{ site.baseurl }}/users/installation) 
+before using this feature.**
+
+## Crop & Media Crop
+
+_Format:_
+
+```yaml
+    crop: (geometery)
+    media_crop:
+      (media_preset): (geometry)
+      (media_preset): (geometry)
+      (...)
+```
+
+_Example:_
+
+```yaml
+    crop: 16:9
+    media_crop:
+      tablet: 3:2
+      mobile: 1:1
+```
+
+Crop geometry, given either generally or for specific media presets. The
+hierarchy is: `tag argument` > `media_crop:` > `crop:`.
+
+This setting accepts the same arguments as the `crop geometry` 
+[tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop).
+
+## Gravity & Media Gravity
+
+```yaml
+    gravity: (gravity)
+    media_gravity:
+      (media_preset): (gravity)
+      (media_preset): (gravity)
+      (...)
+```
+
+_Example:_
+
+```yaml
+    gravity: north
+    media_gravity:
+      tablet: east
+      mobile: southwest
+```
+
+Crop gravity, given either generally or for specific media presets. The hierarchy is:
+`tag argument` > `media_gravity:` > `gravity:` > `center` (default).
+
+This setting accepts the same arguments as the `crop gravity` 
+[tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop).

data/docs/users/presets/default.md

@@ -0,0 +1,23 @@
+---
+sort: 13
+---
+
+# 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
+```

data/docs/users/presets/examples.md

@@ -0,0 +1,79 @@
+---
+sort: 12
+---
+# 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,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 %}