jekyll_picture_tag 1.14.0 → 2.0.0pre1

data/docs/users/getting_started.md

@@ -0,0 +1,55 @@
+---
+sort: 2
+---
+
+# Getting started
+
+Firstly, let me warn you that responsive images are somewhat complicated, and fall squarely into
+"proper web development" territory. To do this well, you will need to do some learning. The default
+settings are a starting point, meant to get you up and running with something reasonable while
+minimizing unexpected behavior.
+
+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/)
+
+## Step 1: Customize global settings
+
+JPT's [global configuration](configuration) happens under the `picture:` key in `_config.yml`. The
+defaults are probably fine, though you may want to configure the input and output
+[directories](configuration/directories).
+
+## Step 2: Test & Learn
+
+- If you're not already familiar, there's a short [tutorial](tutorial) to get you started with the basics.
+- Look over the [example presets](presets/examples)
+- Look over the [example liquid tags](liquid_tag/examples) and [instructions](liquid_tag).
+
+## Step 3: Add breakpoints
+
+Once you have a feel for how this plugin works, it's time to adapt it to your particular site. The
+built-in `jpt-` media queries probably don't quite fit your layout; Find whatever breakpoints your
+css uses, and tell JPT about them:
+
+1. Create `_data/picture.yml`
+2. List them under the `media_queries:` key. Give them easy-to-remember names, and wrap them in
+   single quotes.
+
+```yaml
+# _data/picture.yml
+
+media_queries:
+  (name): '(media query)'
+  (...)
+
+```
+
+If you're using bootstrap or something, you don't need to plug in every single breakpoint they have,
+just a handful that you'll actually use.
+
+## Step 4: Write presets
+
+From there, it's time to [write your own presets](presets). Start with the `default`, and then move
+on to cover all the different ways you use images in your site.

data/docs/users/installation.md

@@ -1,52 +1,31 @@
 ---
+sort: 1
 ---
 
 # Installation
 
 1. Add `jekyll_picture_tag` to your Gemfile in the `:jekyll_plugins` group.
-  (Note that it's NOT `jekyll-picture-tag`):
+
+    ```note
+    It's NOT `jekyll-picture-tag`.
+    ```
+
     ```ruby
     # Gemfile
 
-    gem 'jekyll'
+    gem 'jekyll', ~> '4.0'
 
     group :jekyll_plugins do
-      gem 'jekyll_picture_tag', ~> '1'
+      # (other jekyll plugins)
+      gem 'jekyll_picture_tag', ~> '2.0'
     end
     ```
-2. Run `$ bundle install`
-3. See if you have ImageMagick with `$ convert --version`. You should see
-   something like this:
-  ```bash
-  ~ $ 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
-  You need a 'webp' delegate 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. Usually it's just named
-  'webp'.
-```
-
-```warning
-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.
+2. Run `$ bundle install`
+3. Install `libvips`. Most package managers know about it, otherwise it can be found
+   [here](https://libvips.github.io/libvips/install.html).
+4. Install libvips dependencies for all image formats you will use, such as `libpng`, `libwebp`,
+   `libjpeg`, and `libheif` (for avif).
+5. Optional: Install `ImageMagick` for additional image formats. If vips runs into an image format
+   it can't handle (jp2 on my particular installation), JPT will instruct it to try ImageMagick
+   instead.

data/docs/users/liquid_tag/argument_reference/crop.md

@@ -4,45 +4,30 @@ sort: 3
 
 # Crop
 
-```warning
-Ensure that both your development and production build environments have
-ImageMagick 7+ installed before using this feature. Anything based on Ubuntu
-likely does not. The installation guide has more information.
-```
+Crop an image to a given aspect ratio. This argument is given as a `crop` and (optionally) a `keep`
+setting. The values given here will override the preset settings (if present), can be given after
+every image, and apply only to the preceding image.
 
-Crop an image to a given aspect ratio or size. This argument is given as a
-`geometry` and (optionally) a `gravity`, which can appear in either order and
-are thin wrappers around ImageMagick's
-[geometry](http://www.imagemagick.org/script/command-line-processing.php#geometry)
-and
-[gravity](http://www.imagemagick.org/script/command-line-options.php#gravity)
-settings. The values given here will override the preset settings (if present),
-can be given after every image, and apply only to the preceding image.
-
-Geometry can take many forms, but most likely you'll want to set an aspect
-ratio-- given in the standard `width:height` ratio such as `3:2`. Gravity sets
-which portion of the image to keep, and is given in compass directions (`north`,
-`southeast`, etc) or `center` (default). Cropping happens before resizing; the
-preset `widths` setting is a post-crop value.
-
-If you'd like more fine-grained control, this can be offset by appending `+|-x`
-and (optionally) `y` pixel values to the _geometry_ (not the gravity!). Example:
-`1:1+400 west` means "Crop to a 1:1 aspect ratio, starting 400 pixels from the
-left side.", and `north 3:2+0+100` means "Crop to 3:2, starting 100 pixels from
-the top." These can get a bit persnickety; there's nothing to stop you from
-running off the side of the image. Pay attention.
-
-For detailed documentation, see ImageMagick's
-[crop](http://www.imagemagick.org/script/command-line-options.php#crop) tool.
+`crop` is given as an aspect ratio in the `width:height` format.
 
-## Examples
+`keep` sets which portion of the image to keep; it's the
+['interestingness'](https://libvips.github.io/libvips/API/current/libvips-conversion.html#VipsInteresting)
+setting passed to the [libvips
+smartcrop](https://libvips.github.io/libvips/API/current/libvips-conversion.html#vips-smartcrop)
+function. Your options are:
 
-- `16:9`
-- `1:1 west`
-- `3:2+20+50 northeast`
+* `attention` - automagically keep parts likely to draw human attention. **Default**
+* `entropy` - Crop out the parts with the least variation.
+* `center` or `centre` - Keep the middle part.
 
 ```note
-If you do a lot of trial and error with these, it's a good idea to manually
-delete your generated images folder more often as each change will build a new
-set of images without removing the old ones.
+Cropping happens before resizing; the preset `widths` setting is a post-crop value.
 ```
+
+More fine-grained control is beyond the scope of this plugin. I'm not writing an image editor here!
+
+## Examples
+
+- `16:9`
+- `1:1 entropy`
+- `3:2 center`

data/docs/users/liquid_tag/examples.md

@@ -27,44 +27,32 @@
 
   * Use liquid variables:
   ```
-  {% picture {{ page.some_liquid_variable }} %}
+  {% picture "{{ page.some_liquid_variable }}" %}
   ```
 
   * Select the blog_index preset, use liquid variables, and wrap the image in an
   anchor tag (link):
   ```
-  {% picture blog_index {{ post.image }} --link {{ post.url }} %}
-  ```
-    N.B. If the image path is coming from a liquid variable then you have two problems to guard against.
-    * __Spaces__: you need to wrap the inner tag in "" to stop a path with spaces being interpretted as two or more arguments:
-    ```
-    {% picture blog_index "{{ post.image }}" %}
-    ```
-    * __Nulls & Blanks__: you need to wrap whole tag in a logic block to stop an uncaught Liquid exception:
-    ```
-    {% if post.image && post.image != "" %} 
-      {% picture blog_index "{{ post.image }}" %}
-    {% endif %}
-    ```
-  
+  {% picture blog_index "{{ post.image }}" --link {{ post.url }} %}
+  ```
+
+   **Note:** If the image path is coming from a liquid variable then you should guard against spaces
+   by wrapping the inner tag in quotes, as in the previous examples.
 
   * Add arbitrary HTML attributes:
   ```
   {% picture example.jpg --picture class="some classes" --img id="example" %}
   ```
 
-  ```warning
-  Read the whole installation guide before using the crop feature.
-  ```
-
-  * Crop to a 16:9 aspect ratio, keeping the top:
+  * Crop to a 16:9 aspect ratio (Will keep the part of the image "most likely to
+    draw human attention"):
   ```
-  {% picture example.jpg 16:9 north %}
+  {% picture example.jpg 16:9 %}
   ```
 
   * Crop to a 1:1 aspect ratio, keeping the middle, with alt text:
   ```
-  {% picture thumbnail example.jpg 1:1 --alt Example Image %}
+  {% picture thumbnail example.jpg 1:1 center --alt Example Image %}
   ```
 
   * Crop the same image multiple times:
@@ -82,9 +70,9 @@
     {% 
       picture
       hero
-      example.jpg 16:9 east
-      tablet: example2.jpg 3:2 east
-      mobile: example3.jpg 1:1-50+0 east
+      example.jpg 16:9 entropy
+      tablet: example2.jpg 3:2
+      mobile: example3.jpg 1:1
       --alt Happy Puppy
       --picture class="hero"
       --link /

data/docs/users/liquid_tag/index.md

@@ -22,7 +22,7 @@ fine, and you can use liquid variables anywhere.
 
 * `(image)` - required.
 
-* `crop` - Geometry and gravity arguments, passed to imagemagick.
+* `crop` - Aspect ratio & keep settings.
 
 * `alternate images & crops` - Art Direction; show different images on different
   devices. Give in order of ascending specificity.

data/docs/users/notes/{migration.md → migration_1.md}

@@ -1,6 +1,6 @@
 ---
 ---
-# Migrating from versions < 1.0
+# Migrating from 0.x to 1.x
 
 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

data/docs/users/notes/migration_2.md

@@ -0,0 +1,99 @@
+---
+---
+# Migrating from 1.x to 2.x
+
+There are a few breaking changes from 1.x versions, but they've been minimized and hopefully they
+won't affect you too badly. This is a guide to transitioning an existing site; We don't go into all
+the new features here, except where they replace or modify existing ones.
+
+- For easy skimming, anything with a bullet point (like this line) is something you need to
+  check/do.
+
+## Libvips
+
+- Install Libvips, both in development and production. Any reasonably recent version will do.
+
+We still fall back to ImageMagick when Vips doesn't support a given image format, so there's no
+reason to uninstall it. However, we no longer require version 7. Version 6+ is fine, which makes
+deployments involving Ubuntu much easier.
+
+## Jekyll 4.0+
+
+- Update to Jekyll 4.x
+
+We're removing support for versions of Jekyll before 4.0. I did it inadvertently awhile ago with the
+fast_build setting, now it's official. If this causes you a great deal of pain, speak up and we'll
+look into supporting older versions.
+
+## Ruby 2.6+
+
+- Ensure you're running Ruby 2.6 or later.
+
+While Jekyll supports 2.4, it's officialy EOL and 2.5 (our previous target) is in security
+maintenance only. Since I want major version releases to be as rare as possible, we're making this
+move now. Again, speak up if this causes a great deal of pain.
+
+## Image quality & write options.
+
+- If you have set `quality:` in a preset, it will likely stop having an effect. You need to set
+  `format_quality:` instead.
+
+Previously, all image formats used a default quality of 75. We have now set a default quality for 3
+formats:
+
+```yml
+format_quality:
+  webp: 50
+  avif: 30
+  jp2: 30
+```
+
+Since `format_quality` overrides `quality`, your `quality` setting won't affect those formats
+anymore.
+
+- Lossless webp or avif was previously accomplished by setting quality to 100. Now, that is
+accomplished with an image option:
+
+```yml
+#_data/picture.yml
+presets:
+
+  my_preset:
+    image_options:
+      webp:
+        lossless: true
+```
+
+## Setting names changing
+
+In `_data/picture.yml`,
+- `markup_presets` is now `presets`
+- `media_presets` is now `media_queries`.
+
+Go check, especially if you've been using JPT for awhile. We renamed them several versions ago, but
+the old names were still supported until now. If you get a bunch of 'preset not found' warnings,
+this is probably why.
+
+
+## Crop changes
+
+- Anywhere you've set a crop geometry in any format other than `w:h`, remove or change it. This
+  could be in both tags and presets.
+- Anywhere you've set a crop gravity such as `north` or `southeast`, remove it. This could also be
+  in both tags and presets.
+- Build the site, look through cropped images and decide if you like the results. Adjust the new
+  `keep` setting if desired.
+
+We now use the Libvips smartcrop feature which does some magic to keep the most interesting part.
+`gravity` is now `keep` (as in which part of the image to keep), and your options are `attention`,
+`entropy`, or `centre`/`center`. The default is `attention`, and it works pretty well in my testing
+so far.
+
+If you can't get satisfactory results with those options, you'll have to use a proper editor. JPT is
+not one, and the old crop feature went too far down the road of trying to be.
+
+## Naming of presets and media queries
+
+- If you have any presets or media queries with names that start with `jpt-`, change them.
+
+We're cordoning off a namespace for built-in ones.

data/docs/users/presets/cropping.md

@@ -1,22 +1,18 @@
 ---
-sort: 5
+sort: 6
 ---
 
 # Cropping
 
-**Check the warning in the 
-[installation guide]({{ site.baseurl }}/users/installation) 
-before using this feature.**
-
 ## Crop & Media Crop
 
 _Format:_
 
 ```yaml
-    crop: (geometery)
+    crop: (aspect ratio)
     media_crop:
-      (media_preset): (geometry)
-      (media_preset): (geometry)
+      (media_preset): (aspect ratio)
+      (media_preset): (aspect ratio)
       (...)
 ```
 
@@ -29,33 +25,36 @@ _Example:_
       mobile: '1:1'
 ```
 
-Crop geometry, given either generally or for specific media presets. The
+Crop aspect ratio, 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` 
+This setting accepts the same arguments as the `crop` 
 [tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop).
 
-## Gravity & Media Gravity
+## Keep & Media Keep
 
 ```yaml
-    gravity: (gravity)
-    media_gravity:
-      (media_preset): (gravity)
-      (media_preset): (gravity)
+    keep: (measure)
+    media_keep:
+      (media_preset): (measure)
+      (media_preset): (measure)
       (...)
 ```
 
 _Example:_
 
 ```yaml
-    gravity: north
+    keep: attention
     media_gravity:
-      tablet: east
-      mobile: southwest
+      tablet: entropy
+      mobile: center
 ```
 
-Crop gravity, given either generally or for specific media presets. The hierarchy is:
-`tag argument` > `media_gravity:` > `gravity:` > `center` (default).
+Which part of the image to keep when cropping, given either generally or for specific media presets.
+The hierarchy is: `tag argument` > `media_keep:` > `keep:` > `attention` (default).
 
-This setting accepts the same arguments as the `crop gravity` 
-[tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop).
+This setting accepts the same arguments as the `keep` [tag parameter]({{ site.baseurl
+}}/users/liquid_tag/argument_reference/crop):
+* `center` or `centre`
+* `attention`
+* `entropy`