jekyll_picture_tag 1.11.0 → 1.12.0

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.

data/docs/users/configuration/ignore_missing.md

@@ -0,0 +1,23 @@
+---
+sort: 3
+---
+
+# 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: 8
+---
+
+# 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/relative_urls.md

@@ -0,0 +1,15 @@
+---
+sort: 6
+---
+
+# Use Relative Urls
+
+*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.

data/docs/users/configuration/suppress_warnings.md

@@ -0,0 +1,16 @@
+---
+sort: 2
+---
+
+# 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/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.

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,48 @@
+---
+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 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.
+
+## Examples
+
+- `16:9`
+- `1:1 west`
+- `3:2+20+50 northeast`
+
+```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.
+```

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

@@ -0,0 +1,16 @@
+---
+sort: 5
+---
+
+# Link
+
+_Format:_ `--link (some url)`
+
+_Examples_: `--link https://example.com`, `--link /blog/some_post/`
+
+Wrap the image in an anchor tag, with the `href` attribute set to whatever
+value you give it. This will override automatic source image linking, if you
+have enabled it.
+
+**Note**: If you get either mangled HTML or extra {::nomarkdown} tags when
+using this, read [here]({{ site.baseurl }}/users/notes/kramdown_bug).

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

@@ -0,0 +1,17 @@
+---
+sort: 1
+---
+
+# Preset
+
+Select a [preset]({{ site.baseurl }}/users/presets), or omit to
+use the `default` preset. A preset is a collection of settings which determines
+nearly everything about JPT's output, from the image formats used to the exact
+format your final HTML will take. Think of it like a recipe or a blueprint; JPT
+will take the information provided in the liquid tag, combine it with the
+settings written in the preset, and use it to craft your images and markup.
+
+If the `preset` is omitted then default settings will be used, in the simplest
+case resulting in an `<img>` tag containing a srcset pointing to your newly
+generated images. You are free to override the `default` preset and define
+your own settings, giving full flexibility in what JPT will create.