jekyll_picture_tag 1.10.1 → 1.14.0

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, 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:
+[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,9 +67,9 @@ markup_presets:
     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:
-
+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 %}`
@@ -72,43 +82,49 @@ You'll get something like this:
 
 <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-21bb6fGUW.webp   600w,
       /generated/test2-900-21bb6fGUW.webp   900w,
       /generated/test2-1200-21bb6fGUW.webp 1200w
-    "
-    type="image/webp">
+    ">
   <source
+    type="image/webp"
     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"
+    type="image/jpeg"
     media="(max-width: 600px)"
+    sizes="(max-width: 600px) 80vw, 600px"
     srcset="
       /generated/test2-600-21bb6fGUW.jpg   600w,
       /generated/test2-900-21bb6fGUW.jpg   900w,
       /generated/test2-1200-21bb6fGUW.jpg 1200w
-    "
-    type="image/jpeg">
+    ">
   <source
+    type="image/jpeg"
     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.
+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/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: 5
+---
+
+# 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.

data/docs/users/configuration/ignore_missing.md

@@ -0,0 +1,23 @@
+---
+sort: 4
+---
+
+# Ignore Missing Source Images
+
+*Format:* `ignore_missing_images: (boolean|environment|environments)`
+
+*Examples:* 
+  - `ignore_missing_images: true`
+  - `ignore_missing_images: development`
+  - `ignore_missing_images: [development, testing]`
+
+*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. You can read more about Jekyll environments
+[here](https://jekyllrb.com/docs/configuration/environments/).

data/docs/users/configuration/index.md

@@ -0,0 +1,29 @@
+---
+sort: 1
+---
+# Global Configuration
+
+**All configuration is optional**. If you are happy with the defaults, you don't
+have to touch a single yml file.
+
+Global settings are stored under the `picture:` key in `/_config.yml`.
+
+**Example:**
+
+```yml
+# _config.yml
+
+(...)
+
+picture:
+  source: "assets/images/fullsize"
+  output: "assets/images/generated"
+  suppress_warnings: true
+  (...)
+
+(...)
+```
+
+## Reference
+
+{% include list.liquid %}

data/docs/users/configuration/kramdown_fix.md

@@ -0,0 +1,20 @@
+---
+sort: 6
+---
+
+# Kramdown Fix
+
+*Format:* `nomarkdown: (true|false)`
+
+*Example:* `nomarkdown: false`
+
+*Default:* `true`
+
+Whether or not to surround j-p-t's output with a
+`{::nomarkdown}..{:/nomarkdown}` block when called from within a markdown file.
+When false, JPT will never add the wrapper. When true, JPT will add it only when
+it believes it's necessary, though it's not 100% accurate at making this
+determination.
+
+This setting is overridden by the same setting in a preset. See [this note]({{
+site.baseurl }}/users/notes/kramdown_bug) for more detailed information. 

data/docs/users/configuration/suppress_warnings.md

@@ -0,0 +1,16 @@
+---
+sort: 3
+---
+
+# Suppress Warnings
+
+*Format:* `suppress_warnings: (true|false)`
+
+*Example:* `suppress_warnings: true`
+
+*Default*: `false`
+
+Jekyll Picture Tag will warn you in a few different scenarios, such as when your
+base image is smaller than one of the sizes in your preset. (Note that Jekyll
+Picture Tag will never resize an image to be larger than its source). Set this
+value to `true`, and these warnings will not be shown.

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/index.md

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

data/docs/users/installation.md

@@ -0,0 +1,52 @@
+---
+---
+
+# Installation
+
+1. Add `jekyll_picture_tag` to your Gemfile in the `:jekyll_plugins` group.
+  (Note that it's NOT `jekyll-picture-tag`):
+    ```ruby
+    # Gemfile
+
+    gem 'jekyll'
+
+    group :jekyll_plugins do
+      gem 'jekyll_picture_tag', ~> '1'
+    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.