jekyll_picture_tag 1.10.0 → 1.13.0

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,93 @@
+---
+---
+# 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 }} %}
+  ```
+    N.B. If the image path is coming from a liquid variable then you have two problems to guard against.
+    * __Spaces__: you need to wrap the inner tag in "" to stop a path with spaces being interpretted as two or more arguments:
+    ```
+    {% picture blog_index "{{ post.image }}" %}
+    ```
+    * __Nulls & Blanks__: you need to wrap whole tag in a logic block to stop an uncaught Liquid exception:
+    ```
+    {% if post.image && post.image != "" %} 
+      {% picture blog_index "{{ post.image }}" %}
+    {% endif %}
+    ```
+  
+
+  * 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.

data/docs/users/notes/git_lfs.md

@@ -0,0 +1,7 @@
+# Git LFS
+
+  I'm Putting this here because it bit me: If you want to use git LFS, make sure that your hosting
+  provider makes those images available during the build process.  Netlify, for example, does not.
+  You won't find this out until you have gone through the entire migration process and try to deploy
+  for the first time.
+

data/docs/users/notes/github_pages.md

@@ -0,0 +1,5 @@
+# Github Pages?
+
+  Github Pages only allows a very short whitelist of plugins, which sadly does not include JPT. You
+  can either run it locally, then commit and push the generated files (rather than the source
+  files), or just host it some other way. I recommend Netlify.

data/docs/users/notes/html_attributes.md

@@ -0,0 +1,5 @@
+# HTML attributes
+
+  Jekyll Picture Tag has comprehensive attribute support for all generated HTML. You can add
+  attributes both through the [liquid tag]({{ site.baseurl }}/usage), and the [preset]({{
+  site.baseurl }}/presets) (scroll down a bit).

data/docs/users/notes/index.md

@@ -0,0 +1,6 @@
+---
+sort: 5
+---
+# Notes and FAQ
+
+{% include list.liquid %}

data/docs/users/notes/input_checking.md

@@ -0,0 +1,6 @@
+# Getting cryptic build errors?
+
+  Jekyll Picture Tag is very trusting. It doesn't do much checking of your inputs, and it does not
+  fail gracefully if you for example pass it a string when it expects an array. It's on the to-do
+  list, but for now if you get cryptic errors then double-check your settings and tag arguments.
+

data/docs/users/notes/kramdown_bug.md

@@ -0,0 +1,41 @@
+# Extra {::nomarkdown} tags or mangled HTML?
+
+## TLDR up front 
+
+There's a bug involving `<picture>` tags wrapped in `<a>` tags which is not in
+my power to fix.
+
+* If you're getting extra `{::nomarkdown}` tags floating around your images, add `nomarkdown:
+  false` to either the relevant preset or under `picture` in `_config.yml`. 
+
+* If you're getting mangled HTML when trying to wrap images with anchor tags, add `nomarkdown:
+  true` to the preset. 
+
+## What's going on here:
+
+Kramdown is Jekyll's default markdown parser. Kramdown gets grumpy when you give it a block level
+element (such as a `<picture>`) surrounded by a span level element (such as an `<a>`), and horribly
+mangles it. The fix for this is to tell Kramdown to chill with a `{::nomarkdown}..{:/nomarkdown}`
+wrapper.
+
+Jekyll Picture Tag can be called from many different places: a markdown file, an HTML file, an HTML
+layout for a markdown file, and an HTML include, to name a few. JPT tries its best to determine
+whether its output will be parsed by Kramdown or not, but Jekyll itself doesn't make this
+particularly easy which results in some false positives. (The one I'm most aware of is when a
+markdown file uses an HTML layout which includes a picture tag.) 
+
+Unfortunately, I don't see an easy way to fix this. We've gotten this far mostly by trial and error.
+I'll continue to work on improving the autodetection, but you can override this behavior explicitly. 
+
+## The fix:
+
+By default, JPT will add a `{::nomarkdown}` tag if all of the following are true:
+* It thinks it's called from a markdown page
+* The image will be wrapped in an anchor tag (i.e. `link_source_image:` or a `--link` parameter)
+* This behavior hasn't been explicitly disabled. 
+
+You can disable nomarkdown tags globally by setting `nomarkdown: false` under the `picture:` key in
+`_config.yml`.
+
+You can enable or disable markdown tags per preset by adding `nomarkdown: true|false` to them.
+**This setting overrides everything else, both JPT autodetection and the global setting.**

data/docs/users/notes/managing_images.md

@@ -0,0 +1,21 @@
+# Managing Generated Images
+
+Jekyll Picture Tag creates resized versions of your images when you build the
+site. It uses a caching system to speed up site compilation, and re-uses images
+as much as possible. Filenames take the following format:
+
+`(original name without extension)-(width)-(id-string).(filetype)`
+
+Try to use a base image that is larger than the largest resized image you need.
+Jekyll Picture Tag will warn you if a base image is too small, and won't upscale
+images.
+
+By specifying a `source` directory that is ignored by Jekyll you can prevent
+huge base images from being copied to the compiled site. For example, `source:
+assets/images/_fullsize` and `output: generated` will result in a compiled site
+that contains resized images but not the originals. Note that this will break
+source image linking, if you wish to enable it. (Can't link to images that
+aren't public!)
+
+The `output` directory is never deleted by Jekyll. You may want to empty it once
+in awhile, to clear out unused images.

data/docs/users/presets/cropping.md

@@ -0,0 +1,61 @@
+---
+sort: 5
+---
+
+# Cropping
+
+**Check the warning in the 
+[installation guide]({{ site.baseurl }}/users/installation) 
+before using this feature.**
+
+## Crop & Media Crop
+
+_Format:_
+
+```yaml
+    crop: (geometery)
+    media_crop:
+      (media_preset): (geometry)
+      (media_preset): (geometry)
+      (...)
+```
+
+_Example:_
+
+```yaml
+    crop: '16:9'
+    media_crop:
+      tablet: '3:2'
+      mobile: '1:1'
+```
+
+Crop geometry, given either generally or for specific media presets. The
+hierarchy is: `tag argument` > `media_crop:` > `crop:`.
+
+This setting accepts the same arguments as the `crop geometry` 
+[tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop).
+
+## Gravity & Media Gravity
+
+```yaml
+    gravity: (gravity)
+    media_gravity:
+      (media_preset): (gravity)
+      (media_preset): (gravity)
+      (...)
+```
+
+_Example:_
+
+```yaml
+    gravity: north
+    media_gravity:
+      tablet: east
+      mobile: southwest
+```
+
+Crop gravity, given either generally or for specific media presets. The hierarchy is:
+`tag argument` > `media_gravity:` > `gravity:` > `center` (default).
+
+This setting accepts the same arguments as the `crop gravity` 
+[tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop).