jekyll_picture_tag 1.11.0 → 1.12.0

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.

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).

data/docs/users/presets/default.md

@@ -0,0 +1,23 @@
+---
+sort: 13
+---
+
+# Default preset
+
+Here are the default preset settings:
+
+```yml
+presets:
+  default:
+    markup: auto
+    formats: [original]
+    widths: [400, 600, 800, 1000]
+    fallback_width: 800
+    fallback_format: original
+    noscript: false
+    link_source: false
+    quality: 75
+    data_sizes: true
+    gravity: center
+    dimension_attributes: false
+```

data/docs/users/presets/examples.md

@@ -0,0 +1,79 @@
+---
+sort: 12
+---
+# Example _data/picture.yml
+
+These are example settings- I mostly made them up off the top of my head. You
+probably don't want to just copy-paste them.
+
+```yaml
+# _data/picture.yml
+
+media_queries:
+  wide_desktop: 'min-width: 1801px'
+  desktop: 'max-width: 1800px'
+  wide_tablet: 'max-width: 1200px'
+  tablet: 'max-width: 900px'
+  mobile: 'max-width: 600px'
+
+presets:
+  default:
+    markup: auto
+    link_source: true # wrap images in a link to the original source image.
+    dimension_attributes: true # Page reflow begone!
+
+    formats: [webp, original] # Must be an array, and order matters.
+
+    widths: [200, 400, 800, 1600] # Must be an array.
+    media_widths: # Because a cell phone doesn't want 1600 pixels.
+      mobile: [200, 400, 600] 
+      tablet: [400, 600, 800]
+
+    sizes: 
+      mobile: 100vw
+      tablet: 80vw
+    size: 800px
+
+    fallback_width: 800
+    fallback_format: original
+
+    attributes:
+      parent: 'data-downloadable="true"'
+      picture: 'class="awesome" data-volume="11"'
+      img: 'class="some-other-class"'
+      a: 'class="image-link"'
+
+  # This is an example of how you would create a 'multiplier' based srcset;
+  # useful when an image will always be the same size on all screens (icons,
+  # graphics, thumbnails, etc), but you'd like to supply higher resolution
+  # images to devices with higher pixel ratios.
+  icon:
+    base_width: 20 # How wide the 1x image should be.
+    pixel_ratios: [1, 1.5, 2]
+    fallback_width: 20
+    attributes:
+      img: 'class="icon"'
+
+  # Here's an example of how you'd configure jekyll-picture-tag to work with
+  # something like lazyload: https://github.com/verlok/lazyload
+  lazy:
+    markup: data_auto
+    formats: [webp, original]
+    widths: [200, 400, 600, 800]
+    noscript: true # add a fallback image inside a <noscript> tag.
+    attributes: 
+      img: class="lazy"
+
+  # This is an example of how you'd get generated image and a URL, and nothing
+  # else.
+  direct:
+    markup: direct_url
+    fallback_format: webp
+    fallback_width: 600
+
+  # Here's a naked srcset. Doesn't even give you the surrounding quotes.
+  srcset:
+    markup: naked_srcset
+    formats: [webp] # must be an array, even if it only has one item
+
+```

data/docs/users/presets/fallback_image.md

@@ -0,0 +1,28 @@
+---
+sort: 9
+---
+
+# Fallback Image
+
+A valid `<picture>` tag must contain an `<img>` tag, and a valid `<img>` tag
+must contain a `src` with a single image. We call this the 'fallback' image.
+
+## Fallback Width
+
+_Format:_ `fallback_width: (integer)`
+
+_Example:_ `fallback_width: 800`
+
+_Default_: `800`
+
+Width of the fallback image.
+
+## Fallback Format
+
+_Format:_ `fallback_format: (format)`
+
+_Example:_ `fallback_format: jpg`
+
+_Default_: `original`
+
+Format of the fallback image.

data/docs/users/presets/html_attributes.md

@@ -0,0 +1,26 @@
+---
+sort: 8
+---
+
+# Arbitrary HTML Attributes
+
+_Format:_
+
+```yaml
+attributes:
+  (element): '(attributes)'
+  (...)
+```
+
+_Example:_
+
+```yaml
+attributes:
+  img: 'class="soopercool" data-awesomeness="11"'
+  picture: 'class="even-cooler"'
+```
+
+HTML attributes you would like to add. The same arguments are available here as
+in the liquid tag: HTML element names, `alt:`, `link:`, and `parent:`. Unescaped
+double quotes cause problems with yml, so it's recommended to surround them with
+single quotes.