jekyll_picture_tag 1.8.0 → 1.11.0

data/docs/example_presets.md

@@ -75,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,

data/docs/global_configuration.md

@@ -65,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**
 
@@ -111,10 +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 [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

@@ -35,14 +35,14 @@ markup_presets:
   default:
     formats: [webp, original]
 ```
-
+**Note:** Order matters! `[webp, jpg]` will offer the browser webp-images first. The browser will pick the *first* format it can work with. So if the order is reversed `[jpg, webp]` it will use the jpg image before the webp.
 
 ### Here's a more complete demonstration:
 
-[Presets]({{ site.baseurl }}/presets) are named collections of settings that tell JPT what you want it to give you.
-Media presets are just 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:
+[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:
@@ -57,13 +57,15 @@ markup_presets:
     size: 500px
 ```
 
-Write this:
+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 mobile: test2.jpg --alt Alternate Text %}`
+`{% picture test.jpg 3:2 mobile: test2.jpg 1:1 --alt Alternate Text %}`
 {% endraw %}
 
-Get this:
+You'll get something like this:
 
 ```html
 <!-- Formatted for readability -->
@@ -73,36 +75,40 @@ Get this:
     sizes="(max-width: 600px) 80vw, 600px"
     media="(max-width: 600px)"
     srcset="
-      /generated/test2-600-21bb6f.webp   600w,
-      /generated/test2-900-21bb6f.webp   900w,
-      /generated/test2-1200-21bb6f.webp 1200w
+      /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-195f7d.webp   600w,
-      /generated/test-900-195f7d.webp   900w,
-      /generated/test-1200-195f7d.webp 1200w
+      /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-21bb6f.jpg   600w,
-      /generated/test2-900-21bb6f.jpg   900w,
-      /generated/test2-1200-21bb6f.jpg 1200w
+      /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-195f7d.jpg   600w,
-      /generated/test-900-195f7d.jpg   900w,
-      /generated/test-1200-195f7d.jpg 1200w
+      /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-195f7d.jpg" alt="Alternate Text">
+  <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,8 +1,9 @@
 ---
 ---
+
 # Installation
 
-* 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
@@ -10,21 +11,35 @@
   end
   ```
 
-* Run `$ bundle install`
+- Run `$ bundle install`
 
-* See if you have ImageMagick with `$ convert --version`. You should see something like this:
+- See if you have ImageMagick with `$ convert --version`. You should see something like this:
 
   ```
-  ~ $ convert --version 
+  ~ $ 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
   ```
+
   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).
 
-* **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.
+- **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.
+
+## Cropping and Imagemagick
+
+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.
+
+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).
 
+Once I work out how to actually do that, I'll add some guidance here.

data/docs/presets.md

@@ -22,7 +22,7 @@ browser widths until you understand it.
 
 ## Media Presets
 
-*Format:*
+_Format:_
 
 ```yml
 media_presets:
@@ -32,11 +32,11 @@ media_presets:
 
 ```
 
-*Example:*
+_Example:_
 
 ```yml
 media_presets:
-  desktop: 'min-width: 1200px'
+  desktop: "min-width: 1200px"
 ```
 
 These are named media queries for use in a few different places: specifying alternate source images
@@ -45,7 +45,7 @@ settings. Quotes are recommended around the media queries, because yml gets conf
 
 ## Markup Presets
 
-*Format:*
+_Format:_
 
 ```yml
 markup_presets:
@@ -56,7 +56,7 @@ markup_presets:
   (...)
 ```
 
-*Example:*
+_Example:_
 
 ```yml
 markup_presets:
@@ -84,29 +84,28 @@ The `default` preset will be used if none is specified. A preset name can't cont
 
 For images that are different sizes on different screens (most images), use a width-based srcset
 (which is the default). Specify a `widths` setting (or don't, for the default set), and optionally
-the `sizes` and `size` settings. 
+the `sizes` and `size` settings.
 
 Use a multiplier-based srcset when the image will always be the same size, regardless of screen
 width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratios` and `base_width`.
 
 ### Settings reference
 
-* **Markup format**
+- **Markup format**
 
-  *Format:* `markup: (setting)`
+  _Format:_ `markup: (setting)`
 
-  *Default*: `auto`
+  _Default_: `auto`
 
   Defines what format the generated text will take. They are documented [here]({{ site.baseurl }}/output).
 
- 
 * **Image Formats**
 
-  *Format:* `format: [format1, format2, (...)]`  
+  _Format:_ `format: [format1, format2, (...)]`
 
-  *Example:* `format: [webp, original]`
+  _Example:_ `format: [webp, original]`
 
-  *Default*: `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
@@ -114,37 +113,37 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
   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`*
+  _Supported formats are anything which imagemagick supports, and has an installed delegate. See a
+  list by running `$ convert --version`_
 
 * **Widths**
 
-  *Format:* `widths: [integer, integer, (...)]`
+  _Format:_ `widths: [integer, integer, (...)]`
 
-  *Example:* `widths: [600, 800, 1200]`
+  _Example:_ `widths: [600, 800, 1200]`
 
-  *Default*: `[400, 600, 800, 1000]`
+  _Default_: `[400, 600, 800, 1000]`
 
   Array of image widths to generate, in pixels. For use when you want a width-based srcset
   (`srcset="img.jpg 800w, img2.jpg 1600w"`).
 
 * **Media_widths**
 
-    *Format:*
+  _Format:_
 
   ```yml
   media_widths:
     (media preset name): [integer, integer, (...)]
   ```
 
-    *Example:*
+  _Example:_
 
   ```yml
   media_widths:
     mobile: [400, 600, 800]
   ```
 
-    *Default:* Widths setting
+  _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,
@@ -152,7 +151,7 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
 
 * **Sizes**
 
-    *Format:*
+  _Format:_
 
   ```yml
   sizes:
@@ -160,7 +159,7 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
     (...)
   ```
 
-    *Example:*
+  _Example:_
 
   ```yml
   sizes:
@@ -173,7 +172,7 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
   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 
+  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
@@ -181,17 +180,17 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
 
 * **Size**
 
-  *Format:* `size: (CSS Dimension)`
+  _Format:_ `size: (CSS Dimension)`
 
-  *Example:* `size: 80vw`
+  _Example:_ `size: 80vw`
 
   Unconditional `sizes` setting, to be supplied either alone or after all conditional sizes.
 
 * **Pixel Ratios**
 
-  *Format:* `pixel_ratios: [number, number, number (...)]`
+  _Format:_ `pixel_ratios: [number, number, number (...)]`
 
-  *Example:* `pixel_ratios: [1, 1.5, 2]`
+  _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`.
@@ -200,26 +199,79 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
 
 * **Base Width**
 
-  *Format:* `base_width: integer`
+  _Format:_ `base_width: integer`
 
-  *Example:* `base_width: 100`
+  _Example:_ `base_width: 100`
 
   When using pixel ratios, you must supply a base width. This sets how wide the 1x image should be.
 
+* **Crop & Media Crop**
+
+  _Format:_
+
+  ```yml
+    crop: (geometery)
+    media_crop:
+    (media_preset): (geometry)
+    (media_preset): (geometry)
+    (...)
+  ```
+
+  _Example:_
+
+  ```yml
+  crop: 16:9
+  media_crop:
+    tablet: 3:2
+    mobile: 1:1
+  ```
+
+  **Check the [ installation guide ](installation) before using this feature.**
+
+  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](usage).
+
+
+* **Gravity & Media_gravity**
+
+  ```yml
+    crop: (gravity)
+    media_crop:
+    (media_preset): (gravity)
+    (media_preset): (gravity)
+    (...)
+  ```
+
+  _Example:_
+
+  ```yml
+  crop: north
+  media_crop:
+    tablet: east
+    mobile: southwest
+  ```
+
+  Crop gravity, given either generally or for specific media presets. The hierarchy is:
+  `tag argument` > `media_crop:` > `crop:` > `center` (default).
+
+  This setting accepts the same arguments as the `crop gravity` [tag parameter](usage).
+
 * **Quality**
 
-  *Format:* `quality: 0 <= integer <= 100`
+  _Format:_ `quality: 0 <= integer <= 100`
 
-  *Example:* `quality: 80`
+  _Example:_ `quality: 80`
 
-  *Default:* `75`
+  _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:* 
+  _Format:_
 
   ```yml
   format_quality:
@@ -227,7 +279,7 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
     (...)
   ```
 
-  *Example:*
+  _Example:_
 
   ```
   format_quality:
@@ -236,16 +288,46 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
     webp: 55
   ```
 
-  *Default:* quality setting (above)
+  _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.
+  above, and if you don't set _that_ it'll default to 75.
 
-* **HTML Attributes**
+* **Width & Height attributes (Anti-Loading-Jank)**
 
-  *Format:*
+  _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 `width: 100%;` and `height: auto;` (or vice versa) set in CSS on the `<img>`
+      tags, or they will be stretched weirdly.
+    * 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.
+
+* **Arbitrary HTML Attributes**
+
+  _Format:_
 
   ```yml
   attributes:
@@ -253,7 +335,7 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
     (...)
   ```
 
-  *Example:*
+  _Example:_
 
   ```yml
   attributes:
@@ -261,49 +343,49 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
     picture: 'class="even-cooler"'
   ```
 
-  HTML attributes you would like to add.  The same arguments are available here as in the liquid
+  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.
 
 * **Fallback Width**
 
-    *Format:* `fallback_width: (integer)`             
+  _Format:_ `fallback_width: (integer)`
 
-    *Example:* `fallback_width: 800`
+  _Example:_ `fallback_width: 800`
 
-    *Default*: `800`
+  _Default_: `800`
 
   Width of the fallback image.
 
 * **Fallback Format**
 
-    *Format:*  `fallback_format: (format)`
+  _Format:_ `fallback_format: (format)`
 
-    *Example:* `fallback_format: jpg`
+  _Example:_ `fallback_format: jpg`
 
-    *Default*: `original`
+  _Default_: `original`
 
   Format of the fallback image
 
 * **Source Image Link**
 
-    *Format:* `link_source: (true|false)`
+  _Format:_ `link_source: (true|false)`
 
-    *Example:* `link_source: true`
+  _Example:_ `link_source: true`
 
-    *Default:* `false`
+  _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).
 
 * **Nomarkdown override**
-   
-    *Format:* `nomarkdown: (true|false)`
 
-    *Example:* `nomarkdown: false`
+  _Format:_ `nomarkdown: (true|false)`
+
+  _Example:_ `nomarkdown: false`
 
-    *Default:* `nil`
+  _Default:_ `nil`
 
   Hard setting for `{::nomarkdown}` tags, overrides both autodetection and the global setting in
-  `_config.yml`. See the [notes]({{ site.baseurl }}/notes) for a detailed explanation. 
+  `_config.yml`. See the [notes]({{ site.baseurl }}/notes) for a detailed explanation.