jekyll_picture_tag 1.13.0 → 2.0.2

data/docs/users/configuration/disable.md

@@ -1,5 +1,5 @@
 ---
-sort: 7
+sort: 5
 ---
 
 # Disable Jekyll Picture Tag

data/docs/users/configuration/ignore_missing.md

@@ -1,5 +1,5 @@
 ---
-sort: 3
+sort: 4
 ---
 
 # Ignore Missing Source Images

data/docs/users/configuration/kramdown_fix.md

@@ -1,5 +1,5 @@
 ---
-sort: 8
+sort: 6
 ---
 
 # Kramdown Fix

data/docs/users/configuration/suppress_warnings.md

@@ -1,5 +1,5 @@
 ---
-sort: 2
+sort: 3
 ---
 
 # Suppress Warnings

data/docs/users/configuration/urls.md

@@ -0,0 +1,69 @@
+---
+sort: 2
+---
+
+# URLs
+
+## Relative or Absolute
+
+*Format:* `relative_url: (true|false)`
+
+*Example:* `relative_url: false`
+
+*Default*: `true`
+
+Whether to use relative (`/generated/test(...).jpg`) or absolute
+(`https://example.com/generated/test(...).jpg`) urls in your src and srcset attributes.
+
+## Baseurl Key
+
+*Format:* `baseurl_key: (string)`
+
+*Example:* `baseurl_key: baseurl_root`
+
+*Default*: `baseurl`
+
+Some plugins, such as
+[jekyll-multiple-languages-plugin](https://github.com/kurtsson/jekyll-multiple-languages-plugin),
+work by modifying the standard `baseurl` setting, which can break JPT's images. It offers a new
+setting, `baseurl_root`, which serves as the original `baseurl` setting without a language prefix.
+Using `baseurl_key`, you can direct JPT to use that setting instead.
+
+## Ignore Baseurl
+
+*Format:* `ignore_baseurl: (true|false)`
+
+*Example:* `ignore_baseurl: true`
+
+*Default*: `false`
+
+Depending on your other plugins and configuration, it may be useful for JPT to ignore the baseurl
+setting entirely.
+
+## CDN URL
+
+Use for images that are hosted at a different domain or subdomain than the Jekyll site root.
+Overrides `relative_url`. 
+
+*Format:* `cdn_url: (url)`
+
+*Example:* `cdn_url: https://cdn.example.com`
+
+*Default*: none
+
+## CDN Environments
+
+It's likely that if you're using a CDN, you may not want to use it in your local development
+environment. This allows you to build a site with local images while in development, and still push
+to a CDN when you build for production by specifying a different
+[environment](https://jekyllrb.com/docs/configuration/environments/). 
+
+*Format:* `cdn_environments: (array of strings)`
+
+*Example:* `cdn_environments: ['production', 'staging']`
+
+*Default*: `['production']`
+
+**Note that the default jekyll environment is `development`**, meaning that if you only set
+`cdn_url` and run `jekyll serve` or `jekyll build`, nothing will change. Either run
+`JEKYLL_ENV=production bundle exec jekyll build`, or add `development` to this setting.

data/docs/users/deployment.md

@@ -0,0 +1,49 @@
+---
+sort: 4
+---
+
+# Deployment
+
+Deploying a site with JPT is surprisingly tricky. This is because we depend on system libraries
+(libvips and its dependencies) to generate images, but build environments have huge variation in
+what is actually present. Just because a site build works on your local machine, doesn't mean it
+will work when you try to deploy using a build service.
+
+Generally, anything which involves building locally and uploading the generated site somewhere, will
+work. Anything which pulls down a git repository and builds it in some container somewhere needs
+extra verification. Often some image formats will be supported, while others will not without
+installing additional packages.
+
+## Help Wanted
+
+We could really use help improving this page's guidance. I've created
+[this](https://github.com/rbuchberger/jekyll_picture_tag/issues/240) issue for feedback; I want to
+hear how you're deploying with JPT. I want to hear what worked well for you, and what did not. If
+you're extra motivated and cool, you could make a pull request adding that information to this page.
+
+## Netlify
+
+As of March 26, 2021, with version 2.0.0, Netlify is mostly broken. It only supports jpg. I want to
+support netlify as much as reasonably possible, so if a solution isn't found I'll re-add imagemagick
+as an alternate backend and offer it as a configurable setting. Until then, stick with version 1.14.
+
+## AWS S3
+
+This method has a somewhat difficult setup, but once configured it works _very_ well. Since you
+build the site locally, if your development build works then your production build will work.
+
+[This](https://aws.amazon.com/premiumsupport/knowledge-center/cloudfront-serve-static-website/) is
+the guide you want; **specifically the second option** (Using a website endpoint as the origin, with
+anonymous (public) access allowed). This allows you to have https and excellent performance.
+
+For deployment, you'll want to put together either some rake tasks or shell commands to do the
+following:
+
+* build: `JEKYLL_ENV=production bundle exec jekyll build`
+* push: `aws s3 sync _site s3://(your bucket here)`
+* invalidate: `aws cloudfront create-invalidation --distribution-id (your distribution id here) --paths '/*'`
+  * Cloudfront caches assets for 24 hours. This command invalidates that cache, so your changes go
+    live immediately.
+* deploy: `build && push && invalidate`
+
+(All of these depend on having the aws cli installed, with proper credentials configured.)

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,32 @@
 ---
+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). Note that if you use a deployment or CI service, these
+   dependencies will be required there as well.
+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 stop having an effect for webp, avif, and jp2
+  images. 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.