jekyll_picture_tag 1.11.0 → 2.0.0

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

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

data/docs/users/installation.md

@@ -0,0 +1,32 @@
+---
+sort: 1
+---
+
+# Installation
+
+1. Add `jekyll_picture_tag` to your Gemfile in the `:jekyll_plugins` group.
+
+    ```note
+    It's NOT `jekyll-picture-tag`.
+    ```
+
+    ```ruby
+    # Gemfile
+
+    gem 'jekyll', ~> '4.0'
+
+    group :jekyll_plugins do
+      # (other jekyll plugins)
+      gem 'jekyll_picture_tag', ~> '2.0'
+    end
+    ```
+
+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/alternate_images.md

@@ -0,0 +1,18 @@
+---
+sort: 4
+---
+
+# Alternate images
+
+  _Format:_ `(media_query): (filename) [crop] [gravity] (...)`
+
+  _Example:_ `tablet: img_cropped.jpg mobile: img_cropped_more.jpg`
+
+Optionally specify any number of alternate base images for given
+[media_queries]({{ site.baseurl }}/users/presets/media_queries). This is called
+[art direction](http://usecases.responsiveimages.org/#art-direction), and is one
+of JPT's strongest features.
+
+Give your images in order of ascending specificity (The first image is the
+most general). They will be provided to the browser in reverse order, and it
+will select the first one with an applicable media query.

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

@@ -0,0 +1,42 @@
+---
+sort: 6
+---
+
+# Attributes
+
+Optionally specify any number of HTML attributes. These will be combined with
+any which you've set in a preset.
+
+All arguments which begin with `--` (including `--link`) must be at the end of
+the liquid tag, but they can be given in any order.
+
+- **`--alt`**
+
+  _Format:_ `--alt (alt text)`
+
+  _Example:_ `--alt Here is my alt text!`
+
+  Convenience shortcut for `--img alt="..."`
+
+- **`--(element)`**
+
+  _Format:_ `--(picture|img|source|a|parent) (Standard HTML attributes)`
+
+  _Example:_ `--img class="awesome-fade-in" id="coolio" --a data-awesomeness="11"`
+
+  Apply attributes to a given HTML element. Your options are:
+
+  - `--picture`
+  - `--img`
+  - `--source`
+  - `--a` (anchor tag)
+  - `--parent`
+
+`--parent` will be applied to the `<picture>` if present, otherwise the
+`<img>`; useful when using an `auto` output format.
+
+```note
+Attributes that are set here for elements which don't occur in the selected
+markup format will be ignored (e.g. adding `--picture class="cool-css"` with a
+preset that does not use a `<picture>` tag).
+```

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

@@ -0,0 +1,12 @@
+---
+sort: 2
+---
+
+# Base Image (Required)
+
+Can be any raster image (as long as you have the required ImageMagick delegate).
+Relative to Jekyll's root directory, or the `source` [setting]({{ site.baseurl
+}}/users/configuration/directories) if you've configured it.
+
+For filenames with spaces, either use double quotes (`"my image.jpg"`) or a
+backslash (`my\ image.jpg`).

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

@@ -0,0 +1,33 @@
+---
+sort: 3
+---
+
+# Crop
+
+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` is given as an aspect ratio in the `width:height` format.
+
+`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:
+
+* `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
+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`