jekyll_picture_tag 1.7.0 → 1.10.1

data/docs/{examples/_data/picture.yml → example_presets.md}

@@ -1,7 +1,12 @@
-# These are example settings. I mostly made them up off the top of my head. You
-# probably don't want to just copy-paste these settings. It's worth your time to
-# learn responsive images, so you'll understand what these settings mean.
-# The full documentation for these settings can be found in docs/presets.md
+---
+---
+# /_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. The full documentation
+for these can be found [here]({{ site.baseurl }}/presets).
+
+```yml
 
 # Media presets are just named css media queries, used in several places:
 # - To specify alternate source images (for art direction)
@@ -14,44 +19,47 @@ media_presets:
   tablet: 'max-width: 900px'
   mobile: 'max-width: 600px'
 
-# Markup presets allow you to group settings together, and select one of them by name in your jekyll
-# tag. All settings are optional.
+# Markup presets allow you to group settings together, and select one of them by
+# name in your jekyll tag. All settings are optional.
 markup_presets:
-  # If you don't specify a preset in the liquid tag (just say 
-  # {% picture image.jpg %}), you'll get the 'default' preset:
+
   default:
-    # What form the output markup should take.
+    # What form the output markup should take:
     markup: auto
 
     # Must be an array, and order matters. Defaults to just 'original', which
     # does what you'd expect.
     formats: [webp, original]
 
-    # Must be an array: which image sizes (width in pixels) to generate (unless directed otherwise
-    # below). If not specified, will use sensible default values.
+    # Must be an array: which image sizes (width in pixels) to generate (unless
+    # directed otherwise below). If not specified, will use sensible default
+    # values.
     widths: [200, 400, 800, 1600]
 
-    # Alternate source images (for art direction) are associated with media query presets. Here, you
-    # can optionally specify a different set of sizes to generate for those alternate source images.
-    # This is how you avoid generating a 1600 pixel wide image that's only shown on narrow screens.
+    # Alternate source images (for art direction) are associated with media
+    # query presets. Here, you can optionally specify a different set of sizes
+    # to generate for those alternate source images.  This is how you avoid
+    # generating a 1600 pixel wide image that's only shown on narrow screens.
     # Must be arrays.
     media_widths: 
       mobile: [200, 400, 600] 
       tablet: [400, 600, 800]
 
-    # For building the 'sizes' attribute on img and source tags. specifies how wide the image will
-    # be when a given media query is true. Note that every source in a given <picture> tag will have
-    # the same associated sizes attribute.
+    # For building the 'sizes' attribute on img and source tags. specifies how
+    # wide the image will be when a given media query is true. Note that every
+    # source in a given <picture> tag will have the same associated sizes
+    # attribute.
     sizes: 
       mobile: 100vw
       tablet: 80vw
 
-    # Specifies an optional, unconditional size attribute. Can be given alone, or if specified in
-    # combination with 'sizes' below, will be given last (when no media queries apply).
+    # Specifies an optional, unconditional size attribute. Can be given alone,
+    # or if specified in combination with 'sizes' below, will be given last
+    # (when no media queries apply).
     size: 800px
 
-    # Specify the properties of the fallback image. If not specified, will return a 900 pixel
-    # wide image in the original format.
+    # Specify the properties of the fallback image. If not specified, will
+    # return a 900 pixel wide image in the original format.
     fallback_width: 800
     fallback_format: original
 
@@ -67,7 +75,7 @@ markup_presets:
     # your source images will need to be part of the deployed site for this to
     # work. If you have issues such as mangled HTML or extra {::nomarkdown}
     # tags floating around, see docs/notes.md
-    link-source: true
+    link_source: true
 
   # 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,
@@ -80,8 +88,8 @@ markup_presets:
     attributes:
       img: 'class="icon"'
 
-  # Here's an example of how you'd configure jekyll-picture-tag to work with something like
-  # lazyload:
+  # Here's an example of how you'd configure jekyll-picture-tag to work with
+  # something like lazyload:
   # https://github.com/verlok/lazyload
   lazy:
     # data_auto gives you data-src, data-srcset, and data-sizes instead of src,
@@ -93,7 +101,8 @@ markup_presets:
     attributes: 
       img: class="lazy"
 
-  # This is an example of how you'd get generated image and a URL, and nothing else.
+  # This is an example of how you'd get generated image and a URL, and nothing
+  # else.
   direct:
     markup: direct_url
     fallback_format: webp # Default original
@@ -103,3 +112,5 @@ markup_presets:
   srcset:
     markup: naked_srcset
     formats: [webp] # must be an array, even if it only has one item
+
+```

data/docs/global_configuration.md

@@ -1,3 +1,5 @@
+---
+---
 # Global Configuration
 
 **All configuration is optional**. If you are happy with the defaults, you don't have to touch a
@@ -24,8 +26,10 @@ picture:
   To make writing tags easier you can specify a source directory for your assets. Base images in the
   tag will be relative to the `source` directory, which is relative to the Jekyll site root.
 
+  {% raw %}
   For example, if `source` is set to `assets/images/_fullsize`, the tag
   `{% picture enishte/portrait.jpg --alt An unsual picture %}` will look for a file at
+  {% endraw %}
   `assets/images/_fullsize/enishte/portrait.jpg`.
 
 * **Destination Image Directory**
@@ -61,7 +65,12 @@ picture:
 
     *Default:* `false`
 
-  Normally, JPT will raise an error if a source image is missing, causing the entire site build to fail. This setting allows you to bypass this behavior and continue the build, either for certain build environments or all the time. I highly encourage you to set this to `development`, and set the jekyll build environment to `production` when you build for production so you don't shoot yourself in the foot (publish a site with broken images). You can read more about Jekyll environments [here](https://jekyllrb.com/docs/configuration/environments/).
+  Normally, JPT will raise an error if a source image is missing, causing the entire site build to
+  fail. This setting allows you to bypass this behavior and continue the build, either for certain
+  build environments or all the time. I highly encourage you to set this to `development`, and set
+  the jekyll build environment to `production` when you build for production so you don't shoot
+  yourself in the foot (publish a site with broken images). You can read more about Jekyll
+  environments [here](https://jekyllrb.com/docs/configuration/environments/).
   
 * **Use Relative Urls**
 
@@ -107,9 +116,58 @@ picture:
 
   *Example:* `nomarkdown: false`
 
-  *Default*: `true`
+  *Default:* `true`
 
   Whether or not to surround j-p-t's output with a `{::nomarkdown}..{:/nomarkdown}` block when called
   from within a markdown file. 
 
-  This setting is overridden by the same setting in a preset. See [this wiki page](https://github.com/rbuchberger/jekyll_picture_tag/wiki/Extra-%7B::nomarkdown%7D-tags-or-mangled-html%3F) for more detailed information. 
+  This setting is overridden by the same setting in a preset. See [the notes]({{ site.baseurl
+  }}/notes) for more detailed information. 
+
+* **Fast Build**
+
+  *Format:* `fast_build: (true|false|environment|array of environments)`
+
+  *Examples:* 
+
+    - `fast_build: true`
+
+    - `fast_build: development`
+
+    - `fast_build: [development, staging]`
+
+  *Default:* `false`
+
+  Makes a tradeoff: Speeds repeated build times for sites with many images, by assuming that the
+  filename alone is enough to uniquely identify a source image. This doesn't speed up image
+  generation, just detection of whether or not it's necessary.
+
+  Ordinarily, JPT generates an MD5 hash for every source image, every site build. This ensures that
+  if you replace one image with another, but keep the filename the same, JPT will correctly generate
+  images for the new file. If you have many large images and/or limited hardware, this can take some
+  time and make the development process painful. Enable this setting to skip MD5 hash checking on
+  existing generated images (most of the time), and just assume that if the filename, format, and
+  width match then it's the right one. If there are multiple possible matches (resulting from
+  leftover generated images from previous filename replacements), it'll compute a hash instead of
+  guessing randomly.
+
+* **Disable Jekyll Picture Tag**
+
+  *Format:* `disabled: (true|false|environment|array of environments)`
+
+  *Examples:* 
+
+    - `disabled: true`
+
+    - `disabled: development`
+
+    - `disabled: [development, staging]`
+
+  *Default:* `false`
+
+  Disable image and markup generation entirely. Useful for debugging, or to speed up site builds
+  when you're working on something else.
+
+  Hint: If you're going to toggle this on and off frequently, you might just use an environment
+  variable. Set this to something like `nopics`, and then start the Jekyll server with something
+  like `JEKYLL_ENV=nopics bundle exec jekyll serve` when you don't want image generation.

data/docs/index.md

@@ -0,0 +1,114 @@
+---
+id: quickstart
+---
+
+# Quick start / Demo
+
+**All configuration is optional.** Here's the simplest possible use case:
+
+1. [Install]({{ site.baseurl }}/installation)
+
+2. Write this: {% raw %} `{% picture test.jpg %}` {% endraw %}
+
+3. Get this:
+
+```html
+<!-- Formatted for readability -->
+
+<img src="/generated/test-800-195f7d.jpg"
+  srcset="
+    /generated/test-400-195f7d.jpg   400w,
+    /generated/test-600-195f7d.jpg   600w,
+    /generated/test-800-195f7d.jpg   800w,
+    /generated/test-1000-195f7d.jpg 1000w
+    ">
+```
+
+(Along with the appropriate images, obviously.)
+
+### "That's cool, but I just want webp."
+
+Create `_data/picture.yml`, add the following:
+
+```yml
+markup_presets:
+  default:
+    formats: [webp, original]
+```
+
+
+### Here's a more complete demonstration:
+
+[Presets]({{ site.baseurl }}/presets) are named collections of settings, and come in 2 kinds: Media
+Presets are named CSS media queries, and Markup Presets determine the output text and images. You
+choose one with the second [tag parameter]({{ site.baseurl }}/usage), or omit for the `default` (as
+in these examples).  They are located in `_data/picture.yml`. Here's an example:
+
+```yml
+media_presets:
+  mobile: 'max-width: 600px'
+
+markup_presets:
+  default:
+    widths: [600, 900, 1200]
+    formats: [webp, original]
+    sizes:
+      mobile: 80vw
+    size: 500px
+```
+
+Imagemagick can easily crop images to an aspect ratio, though you should **read the whole
+installation guide before using this feature**. With the above preset, if you write this:
+
+
+{% raw %}
+`{% picture test.jpg 3:2 mobile: test2.jpg 1:1 --alt Alternate Text %}`
+{% endraw %}
+
+You'll get something like this:
+
+```html
+<!-- Formatted for readability -->
+
+<picture>
+  <source
+    sizes="(max-width: 600px) 80vw, 600px"
+    media="(max-width: 600px)"
+    srcset="
+      /generated/test2-600-21bb6fGUW.webp   600w,
+      /generated/test2-900-21bb6fGUW.webp   900w,
+      /generated/test2-1200-21bb6fGUW.webp 1200w
+    "
+    type="image/webp">
+  <source
+    sizes="(max-width: 600px) 80vw, 600px"
+    srcset="
+      /generated/test-600-195f7d192.webp   600w,
+      /generated/test-900-195f7d192.webp   900w,
+      /generated/test-1200-195f7d192.webp 1200w
+    "
+    type="image/webp">
+  <source
+    sizes="(max-width: 600px) 80vw, 600px"
+    media="(max-width: 600px)"
+    srcset="
+      /generated/test2-600-21bb6fGUW.jpg   600w,
+      /generated/test2-900-21bb6fGUW.jpg   900w,
+      /generated/test2-1200-21bb6fGUW.jpg 1200w
+    "
+    type="image/jpeg">
+  <source
+    sizes="(max-width: 600px) 80vw, 600px"
+    srcset="
+      /generated/test-600-195f7d192.jpg   600w,
+      /generated/test-900-195f7d192.jpg   900w,
+      /generated/test-1200-195f7d192.jpg 1200w
+    "
+    type="image/jpeg">
+  <img src="/generated/test-800-195f7dGUW.jpg" alt="Alternate Text">
+</picture>
+```
+
+In other words, you have the art direction, format switching, and resolution switching problems
+*solved*, with a one-liner and a nicely readable config file that is 1/3 as long as the output
+markup. Lighthouse is happy, and you don't even need to crop things yourself.

data/docs/installation.md

@@ -1,30 +1,45 @@
+---
+---
+
 # Installation
 
-1. Add `jekyll_picture_tag` to your Gemfile in the `:jekyll_plugins` group:
+- Add `jekyll_picture_tag` to your Gemfile in the `:jekyll_plugins` group:
+
+  ```ruby
+  group :jekyll_plugins do
+    gem 'jekyll_picture_tag'
+  end
+  ```
+
+- Run `$ bundle install`
+
+- See if you have ImageMagick with `$ convert --version`. You should see something like this:
 
-```ruby
-group :jekyll_plugins do
-  gem 'jekyll_picture_tag'
-end
-```
+  ```
+  ~ $ convert --version
+  Version: ImageMagick 7.0.8-14 Q16 x86_64 2018-10-31 https://imagemagick.org
+  Copyright: © 1999-2018 ImageMagick Studio LLC License: https://imagemagick.org/script/license.php
+  Features: Cipher DPC HDRI OpenMP Delegates (built-in): bzlib fontconfig freetype jng jp2 jpeg lcms
+  lzma pangocairo png tiff webp xml zlib
+  ```
 
-2. `bundle install`
+  If you get a 'command not found' error, you'll need to install it. Most package managers know about
+  ImageMagick, otherwise it can be found [here](https://imagemagick.org/script/download.php).
 
-3. Verify you have ImageMagick (Good chance you do) by entering the following into a terminal:
+- **Note webp under delegates.** This is required if you want to generate webp files. Any image format
+  you want to handle will require an appropriate delegate; You may have to install additional packages
+  to accomplish this.
 
-```
-$ convert --version
-```
-You should see something like this:
+## Cropping and Imagemagick
 
-    chronos@localhost ~ $ convert --version
-    Version: ImageMagick 7.0.8-14 Q16 x86_64 2018-10-31 https://imagemagick.org
-    Copyright: © 1999-2018 ImageMagick Studio LLC
-    License: https://imagemagick.org/script/license.php
-    Features: Cipher DPC HDRI OpenMP
-    Delegates (built-in): bzlib fontconfig freetype jng jp2 jpeg lcms lzma pangocairo png tiff webp xml zlib
+Cropping to an aspect ratio depends on ImageMagick 7+. Ubuntu, somewhat annoyingly, only offers
+version 6 in its official repositories. This matters even if you don't run Ubuntu, because many
+build & deployment services you might use (including Netlify and Travis CI) do.
 
-**Note webp under delegates.** This is required if you want to generate webp files.
+If you'd like to use both the cropping feature and such a service, or it's inconvenient to install
+version 7 in your development environment, you will likely want to build your site in a docker
+container. The Alpine Linux repos include version 7, so you'll want an Alpine Linux based image
+rather than an Ubuntu based one. Conveniently this includes the [offical Jekyll
+image](https://hub.docker.com/r/jekyll/jekyll).
 
-If you get a 'command not found' error, you'll need to install it. Most package managers
-know about it, otherwise it can be downloaded [here](https://imagemagick.org/script/download.php).
+Once I work out how to actually do that, I'll add some guidance here.

data/docs/migration.md

@@ -1,3 +1,5 @@
+---
+---
 # Migrating from versions < 1.0
 
 This document details the changes from previous versions (Everything before 1.0), and how to migrate
@@ -37,7 +39,9 @@ describes how to get your site working with the new version.
 Previous tag syntax has been extended, but backwards compatibility (and behaviour of previous
 versions) is maintained. 
 
+{% raw %}
 `{% picture img.jpg (implicit attributes) --(argument) (explicit attributes) %}`
+{% endraw %}
 
 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

data/docs/notes.md

@@ -1,85 +1,91 @@
+---
+---
 # Notes and FAQ
 
-## Extra {::nomarkdown} tags or mangled HTML?
+* #### Github Pages?
 
-**TLDR up front:** There's a bug involving `<picture>` tags wrapped in `<a>` tags which is not in my
-power to fix.
+  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.
 
-* 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`. 
+* #### HTML attributes
 
-* 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:
+  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).
+
+* ### Input checking
 
-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 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.
 
-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.) 
+* ### Git LFS
 
-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. 
+  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.
 
-#### 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. 
+* #### Extra {::nomarkdown} tags or mangled HTML?
 
-You can disable nomarkdown tags globally by setting `nomarkdown: false` under the `picture:` key in
-`_config.yml`.
+  **TLDR up front:** There's a bug involving `<picture>` tags wrapped in `<a>` tags which is not in my
+  power to fix.
 
-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.**
+  * 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`. 
 
-## Input checking
+  * 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:**
 
-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.
+  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.
 
-## Git LFS
+  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.) 
 
-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.
+  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. 
 
-## Lazy Loading, and other javascript related tomfoolery
+  **The fix:**
 
-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.
+  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. 
 
-## PictureFill
+  You can disable nomarkdown tags globally by setting `nomarkdown: false` under the `picture:` key in
+  `_config.yml`.
 
-[Picturefill](http://scottjehl.github.io/picturefill/) version 3 no longer requires special markup.
-Standard outputs should be compatible.
+  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.**
 
-## Managing Generated Images
+* ### 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:
+  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)`
+  `(original name without extension)-(width)-(source hash).(filetype)`
 
-Source hash is the first 5 characters of an md5 checksum of the source image.
+  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.
+  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!)
+  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. 
+  The `output` directory is never deleted by Jekyll. You may want to empty it once in awhile, to
+  clear out unused images.