jekyll_picture_tag 1.9.0 → 1.12.0

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.

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

@@ -0,0 +1,9 @@
+---
+sort: 3
+---
+
+# Argument Reference
+
+Given in order:
+
+{% include list.liquid %}

data/docs/users/liquid_tag/examples.md

@@ -0,0 +1,81 @@
+---
+---
+# Examples
+
+{% raw %}
+
+  * Basic form, will use the preset named 'default': 
+  ```
+  {% picture example.jpg %}
+  ```
+
+  * Include alt text:
+  ```
+  {% picture example.jpg --alt Alt Text %}
+  ```
+
+  * Select a `preset` (defined in `_data/picture.yml`:
+  ```
+  {% picture my_preset example.jpg %}
+  ```
+
+  * Show different images on different devices. (Note that `mobile` must be set
+  to some media query under `media_queries:` in `_data/picture.yml`.
+  ```
+  {% picture example.jpg mobile: example_cropped.jpg %}
+  ```
+
+  * Use liquid variables:
+  ```
+  {% 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 }} %}
+  ```
+
+  * 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:
+  ```
+  {% picture example.jpg 16:9 north %}
+  ```
+
+  * Crop to a 1:1 aspect ratio, keeping the middle, with alt text:
+  ```
+  {% picture thumbnail example.jpg 1:1 --alt Example Image %}
+  ```
+
+  * Crop the same image multiple times:
+  ```
+  {% picture example.jpg 16:9 tablet: example.jpg 4:3 mobile: example.jpg 1:1 %}
+  ```
+
+  * Use filenames with spaces:
+  ```
+  {% picture "some example.jpg" mobile: other\ example.jpg %}
+  ```
+
+  * Use line breaks to make a complicated tag manageable:
+  ```
+    {% 
+      picture
+      hero
+      example.jpg 16:9 east
+      tablet: example2.jpg 3:2 east
+      mobile: example3.jpg 1:1-50+0 east
+      --alt Happy Puppy
+      --picture class="hero"
+      --link /
+    %}
+  ```
+{% endraw %}

data/docs/users/liquid_tag/index.md

@@ -0,0 +1,31 @@
+---
+sort: 2
+---
+
+# Tag Usage
+
+This section describes how to use JPT's liquid tag ({% raw %} `{% picture (...)
+%}` {% endraw %}); what options it takes and what kind of information you can pass
+through it to influence the the final HTML and generated images.
+
+## Format
+
+{% raw %}
+`{% picture [preset] (image) [crop] [alternate images & crops] [attributes] %}`
+{% endraw %}
+
+The only required argument is the base image. Line breaks and extra spaces are
+fine, and you can use liquid variables anywhere.
+
+* `preset` - Select a recipe/blueprint from the ones you have defined in
+  `presets`. Will use `default` if not specified.
+
+* `(image)` - required.
+
+* `crop` - Geometry and gravity arguments, passed to imagemagick.
+
+* `alternate images & crops` - Art Direction; show different images on different
+  devices. Give in order of ascending specificity.
+
+* `attributes` - Add css classes, data-attributes, or wrap the whole thing in an
+  anchor tag.