jekyll_picture_tag 1.9.0 → 1.12.0

data/docs/devs/contributing/docs.md

@@ -0,0 +1,13 @@
+---
+sort: 2
+---
+
+# Docs
+
+They run on github pages, which is based on jekyll. You can preview as you edit:
+
+0. Follow the [setup instructions](setup)
+1. `$ cd docs`
+2. `$ bundle install`
+3. `$ bundle exec jekyll serve`
+4. In a web browser, navigate to `localhost:4000/jekyll_picture_tag/`

data/docs/devs/contributing/index.md

@@ -0,0 +1,15 @@
+---
+---
+# Contributing
+
+Bug reports, feature requests, and feedback are very welcome, either through
+github issues or via email: robert@buchberger.cc 
+
+Pull requests are encouraged! I'm happy to answer questions and provide
+assistance along the way.  Don't let any of the recommendations/requests in this
+guide stop you from submitting one.
+
+I think one of the biggest opportunities for improvement in this plugin is its
+documentation. I'd really love help here, and all you need to know is markdown.
+
+{% include list.liquid %}

data/docs/devs/contributing/setup.md

@@ -0,0 +1,13 @@
+---
+sort: 1
+---
+
+## Setup
+
+It's pretty standard:
+
+```
+$ git clone git@github.com:rbuchberger/jekyll_picture_tag.git
+$ cd jekyll_picture_tag
+$ bundle install
+```

data/docs/devs/contributing/testing.md

@@ -0,0 +1,41 @@
+---
+sort: 3
+---
+
+## How to run the tests
+
+You probably only need to use docker if it's inconvenient to install ImageMagick 7.
+
+### Bare Metal
+
+```note
+Depending on your environment, you may need to prefix all rake commands with
+`bundle exec`.
+```
+
+`rake test` runs the test suite (both unit tests and integration tests). Ignore the mini_magick
+`method redefined` warnings (unless you know how to fix them?) 
+
+`rake unit` runs just the unit tests, while `rake integration` runs the integration tests. The unit
+test coverage isn't stellar, but both unit and integration tests together hit 100%.
+
+Speaking of coverage, simplecov is set up -- you'll get a measurement of coverage in the test output
+and a nice report in the `coverage` directory. I'd like to move to mutation based coverage testing,
+but that's a project for another day.
+
+The tests do output a few images to the `/tmp/` directory, which I'm pretty sure means it won't work
+on Windows. This is fixable if there is a need, so if that gets in your way just ask.
+
+`rake rubocop` checks code formatting, `rake rubocop:auto_correct` will try to fix any rubocop
+issues, if possible.
+
+`rake` will run all tests and rubocop.
+
+### Docker
+
+The following commands will build and run the tests inside a docker image.
+
+```bash
+$ docker build . -t jpt
+$ docker run -t jpt
+```

data/docs/devs/index.md

@@ -0,0 +1,7 @@
+---
+sort: 2
+---
+
+# Development
+
+{% include list.liquid %}

data/docs/{releases.md → devs/releases.md}

@@ -1,27 +1,47 @@
 ---
 ---
 # Release History
-
+* 1.12.0 July 30, 2020
+  * Documentation overhaul. Now with 87% less scrolling!
+  * Rename `markup_presets` and `media_presets` to `presets` and
+    `media_queries`. The old names were bad and caused confusion. The old names
+    will continue to work until the next major version is released.
+* 1.11.0 July 27, 2020
+  * **Width and height attribute support!** Begone, page reflow.
+  * Cache image information between builds
+  * Change image naming format. This update will trigger all images to be
+    regenerated, so you may want to delete your generated images folder
+    beforehand.
+* 1.10.2 July 6, 2020
+  * Bugfix for fallback image files not actually getting generated
+* 1.10.1 July 2, 2020
+  * Bugfix for erroneously regenerated images
+* 1.10.0 May 11, 2020
+  * **Image Cropping support!** access the power of ImageMagick's `crop` function.
+  * Don't issue a warning when `default` preset is not found.
+  * Documentation improvements
 * 1.9.0 Feb 2, 2020
   * Add `fast_build` global setting
   * Add `disabled` global setting
-  * Reduce unnecessary disk IO; sites with many source images should see build times improve when
-    no new images need to be generated.
-  * Add support for empty attributes; specifically so best-practice for decorative images (`alt=""`)
-    is possible.
+  * Reduce unnecessary disk IO; sites with many source images should see build
+  times improve when no new images need to be generated.
+  * Add support for empty attributes; specifically so best-practice for
+    decorative images (`alt=""`) is possible.
 * 1.8.0 Nov 25, 2019
   * Add `data_sizes` setting for the `data_` family of output formats.
 * 1.7.1 Nov 14, 2019
   * Fix some HTML attribute related bugs
   * Add a few items to the FAQ
 * 1.7.0 Aug 12, 2019
-  * Add support for setting generated image quality, either generally or specific to given
-    formats.
+  * Add support for setting generated image quality, either generally or
+    specific to given formats.
   * Add support for spaces and other url-encoded characters in filenames
-  * Documentation restructure - Moved it out of the wiki, into the `docs` folder.
+  * Documentation restructure - Moved it out of the wiki, into the `docs`
+    folder.
   * Bugfix: Fallback image width will now be checked against source image width.
   * Bugfix: Minor fix to nomarkdown wrapper output
-  * link_source will now target the base source image, rather than finding the biggest one.
+  * link_source will now target the base source image, rather than finding the
+    biggest one.
   * Remove fastimage dependency, add addressable dependency.
   * Moderately significant refactoring and code cleanup 
   * Decent set of tests added
@@ -32,14 +52,15 @@
   * better `{::nomarkdown}` necessity detection
   * allow user to override `{::nomarkdown}` autodetection
 * 1.4.0 Jun 26, 2019:
-  * Rename gem from `jekyll-picture-tag` to `jekyll_picture_tag`, allowing us to use rubygems again.
+  * Rename gem from `jekyll-picture-tag` to `jekyll_picture_tag`, allowing us to
+    use rubygems again.
   * Add new output format: `naked_srcset`.
 * 1.3.1 Jun 21, 2019: Bugfix
 * 1.3.0 Jun  7, 2019:
   * Initial compatibility with Jekyll 4.0
   * bugfixes
-  * change to generated image naming-- The first build after this update will be longer, and you
-    might want to clear out your generated images.
+  * change to generated image naming-- The first build after this update will be
+    longer, and you might want to clear out your generated images.
 * 1.2.0 Feb  9, 2019:
   * Add nomarkdown fix
   * noscript option
@@ -50,7 +71,8 @@
   * auto-orient images before stripping metadata
 * 1.0.2 Jan 18, 2019: Fix ruby version specification
 * 1.0.1 Jan 13, 2019: Added ruby version checking
-* **1.0.0** Nov 27, 2018: Rewrite from the ground up. See the [migration guide]({{ site.baseurl }}/migration).
+* **1.0.0** Nov 27, 2018: Rewrite from the ground up. See the 
+* [migration guide]({{ site.baseurl }}/users/notes/migration).
 * 0.2.2 Aug  2, 2013: Bugfixes
 * 0.2.1 Jul 17, 2013: Refactor again, add Liquid parsing.
 * 0.2.0 Jul 14, 2013: Rewrite code base, bring in line with Jekyll Image Tag.

data/docs/index.md

@@ -1,12 +1,15 @@
 ---
-id: quickstart
 ---
 
-# Quick start / Demo
+# Jekyll Picture Tag
+
+Responsive Images, Done Correctly.
+
+## Quick start / Demo
 
 **All configuration is optional.** Here's the simplest possible use case:
 
-1. [Install]({{ site.baseurl }}/installation)
+1. [Install]({{ site.baseurl }}/users/installation)
 
 2. Write this: {% raw %} `{% picture test.jpg %}` {% endraw %}
 
@@ -31,24 +34,31 @@ id: quickstart
 Create `_data/picture.yml`, add the following:
 
 ```yml
-markup_presets:
+presets:
   default:
     formats: [webp, original]
 ```
 
+**Note:** Order matters! `[webp, jpg]` will offer 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 }}/users/presets) are named collections of settings.
+You choose one with the second [tag
+parameter]({{site.baseurl}}/users/liquid_tag), or omit for the `default` (as in
+these examples). They are located in `_data/picture.yml`. Alongside `presets`,
+we also set named `media_queries` for easy reference. Here's an example:
+
 
 ```yml
-media_presets:
+# _data/picture.yml
+
+media_queries:
   mobile: 'max-width: 600px'
 
-markup_presets:
+presets:
   default:
     widths: [600, 900, 1200]
     formats: [webp, original]
@@ -57,52 +67,64 @@ 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 -->
 
 <picture>
   <source
-    sizes="(max-width: 600px) 80vw, 600px"
+    type="image/webp"
     media="(max-width: 600px)"
+    sizes="(max-width: 600px) 80vw, 600px"
     srcset="
-      /generated/test2-600-21bb6f.webp   600w,
-      /generated/test2-900-21bb6f.webp   900w,
-      /generated/test2-1200-21bb6f.webp 1200w
-    "
-    type="image/webp">
+      /generated/test2-600-21bb6fGUW.webp   600w,
+      /generated/test2-900-21bb6fGUW.webp   900w,
+      /generated/test2-1200-21bb6fGUW.webp 1200w
+    ">
   <source
+    type="image/webp"
     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
-    "
-    type="image/webp">
+      /generated/test-600-195f7d192.webp   600w,
+      /generated/test-900-195f7d192.webp   900w,
+      /generated/test-1200-195f7d192.webp 1200w
+    ">
   <source
-    sizes="(max-width: 600px) 80vw, 600px"
+    type="image/jpeg"
     media="(max-width: 600px)"
+    sizes="(max-width: 600px) 80vw, 600px"
     srcset="
-      /generated/test2-600-21bb6f.jpg   600w,
-      /generated/test2-900-21bb6f.jpg   900w,
-      /generated/test2-1200-21bb6f.jpg 1200w
-    "
-    type="image/jpeg">
+      /generated/test2-600-21bb6fGUW.jpg   600w,
+      /generated/test2-900-21bb6fGUW.jpg   900w,
+      /generated/test2-1200-21bb6fGUW.jpg 1200w
+    ">
   <source
+    type="image/jpeg"
     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
-    "
-    type="image/jpeg">
-  <img src="/generated/test-800-195f7d.jpg" alt="Alternate Text">
+      /generated/test-600-195f7d192.jpg   600w,
+      /generated/test-900-195f7d192.jpg   900w,
+      /generated/test-1200-195f7d192.jpg 1200w
+    ">
+  <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.
+
+That isn't a complete demonstration of Jekyll Picture Tag's feature set; it can
+(among other things) add width & height attributes to prevent page reflow, add a
+link to the source image (or anywhere else), and adjust image quality. See the
+docs for more.

data/docs/users/configuration/cdn.md

@@ -0,0 +1,35 @@
+---
+sort: 5
+---
+
+# CDN 
+
+Use for images that are hosted at a different domain or subdomain than the
+Jekyll site root. Overrides `relative_url`. 
+
+## URL
+
+*Format:* `cdn_url: (url)`
+
+*Example:* `cdn_url: https://cdn.example.com`
+
+*Default*: none
+
+## 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/configuration/directories.md

@@ -0,0 +1,34 @@
+---
+sort: 1
+---
+
+# Directories
+
+Define where JPT should look for source images, and where it should place
+generated images.
+
+## Source
+
+*Format:* `source: (directory)`
+
+*Example:* `source: images/`
+
+*Default:* Jekyll site root.
+
+Base directory for your source images, relative to the Jekyll site root. For
+example, if set to `images/_fullsize`:
+
+this tag: {% raw %} `{% picture enishte/portrait.jpg %}` {% endraw %} 
+will use this path: `images/_fullsize/enishte/portrait.jpg`.
+
+## Output
+
+*Format:* `output: (directory)`
+
+*Example:* `output: resized_images/`
+
+*Default*: `generated/`
+
+Save resized, reformatted images to this directory in your compiled site. The
+`source` directory structure is maintained. Relative to your compiled site
+directory, which means `_site/` unless you've changed it.

data/docs/users/configuration/disable.md

@@ -0,0 +1,24 @@
+---
+sort: 7
+---
+
+# 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 frequently, you might use a Jekyll
+Environment. Set this to something like `nopics`, and then start Jekyll with
+`JEKYLL_ENV=nopics bundle exec jekyll serve`.

data/docs/users/configuration/fast_build.md

@@ -0,0 +1,28 @@
+---
+sort: 4
+---
+
+# Fast Build
+
+*Format:* `fast_build: (boolean|environment|environments)`
+
+*Examples:* 
+
+  - `fast_build: true`
+
+  - `fast_build: development`
+
+  - `fast_build: [development, staging]`
+
+*Default:* `false`
+
+*Might* make your builds faster (depending on hardware and how many images you
+have) by making a tradeoff: 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 computes 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. Enable this
+setting to skip MD5 hash checking and just assume that if the filename, format,
+and width match then it's the right one.