jekyll_picture_tag 1.10.2 → 2.0.0pre1

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 }} %}
+  ```
+
+   **Note:** If the image path is coming from a liquid variable then you should guard against spaces
+   by wrapping the inner tag in quotes, as in the previous examples.
+
+  * Add arbitrary HTML attributes:
+  ```
+  {% picture example.jpg --picture class="some classes" --img id="example" %}
+  ```
+
+  * Crop to a 16:9 aspect ratio (Will keep the part of the image "most likely to
+    draw human attention"):
+  ```
+  {% picture example.jpg 16:9 %}
+  ```
+
+  * Crop to a 1:1 aspect ratio, keeping the middle, with alt text:
+  ```
+  {% picture thumbnail example.jpg 1:1 center --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 entropy
+      tablet: example2.jpg 3:2
+      mobile: example3.jpg 1:1
+      --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` - Aspect ratio & keep settings.
+
+* `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/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/{migration.md → users/notes/migration_1.md}

@@ -1,6 +1,6 @@
 ---
 ---
-# Migrating from versions < 1.0
+# Migrating from 0.x to 1.x
 
 This document details the changes from previous versions (Everything before 1.0), and how to migrate
 an existing site to the new version. It won't be updated to reflect new features -- it simply

data/docs/users/notes/migration_2.md

@@ -0,0 +1,99 @@
+---
+---
+# Migrating from 1.x to 2.x
+
+There are a few breaking changes from 1.x versions, but they've been minimized and hopefully they
+won't affect you too badly. This is a guide to transitioning an existing site; We don't go into all
+the new features here, except where they replace or modify existing ones.
+
+- For easy skimming, anything with a bullet point (like this line) is something you need to
+  check/do.
+
+## Libvips
+
+- Install Libvips, both in development and production. Any reasonably recent version will do.
+
+We still fall back to ImageMagick when Vips doesn't support a given image format, so there's no
+reason to uninstall it. However, we no longer require version 7. Version 6+ is fine, which makes
+deployments involving Ubuntu much easier.
+
+## Jekyll 4.0+
+
+- Update to Jekyll 4.x
+
+We're removing support for versions of Jekyll before 4.0. I did it inadvertently awhile ago with the
+fast_build setting, now it's official. If this causes you a great deal of pain, speak up and we'll
+look into supporting older versions.
+
+## Ruby 2.6+
+
+- Ensure you're running Ruby 2.6 or later.
+
+While Jekyll supports 2.4, it's officialy EOL and 2.5 (our previous target) is in security
+maintenance only. Since I want major version releases to be as rare as possible, we're making this
+move now. Again, speak up if this causes a great deal of pain.
+
+## Image quality & write options.
+
+- If you have set `quality:` in a preset, it will likely stop having an effect. You need to set
+  `format_quality:` instead.
+
+Previously, all image formats used a default quality of 75. We have now set a default quality for 3
+formats:
+
+```yml
+format_quality:
+  webp: 50
+  avif: 30
+  jp2: 30
+```
+
+Since `format_quality` overrides `quality`, your `quality` setting won't affect those formats
+anymore.
+
+- Lossless webp or avif was previously accomplished by setting quality to 100. Now, that is
+accomplished with an image option:
+
+```yml
+#_data/picture.yml
+presets:
+
+  my_preset:
+    image_options:
+      webp:
+        lossless: true
+```
+
+## Setting names changing
+
+In `_data/picture.yml`,
+- `markup_presets` is now `presets`
+- `media_presets` is now `media_queries`.
+
+Go check, especially if you've been using JPT for awhile. We renamed them several versions ago, but
+the old names were still supported until now. If you get a bunch of 'preset not found' warnings,
+this is probably why.
+
+
+## Crop changes
+
+- Anywhere you've set a crop geometry in any format other than `w:h`, remove or change it. This
+  could be in both tags and presets.
+- Anywhere you've set a crop gravity such as `north` or `southeast`, remove it. This could also be
+  in both tags and presets.
+- Build the site, look through cropped images and decide if you like the results. Adjust the new
+  `keep` setting if desired.
+
+We now use the Libvips smartcrop feature which does some magic to keep the most interesting part.
+`gravity` is now `keep` (as in which part of the image to keep), and your options are `attention`,
+`entropy`, or `centre`/`center`. The default is `attention`, and it works pretty well in my testing
+so far.
+
+If you can't get satisfactory results with those options, you'll have to use a proper editor. JPT is
+not one, and the old crop feature went too far down the road of trying to be.
+
+## Naming of presets and media queries
+
+- If you have any presets or media queries with names that start with `jpt-`, change them.
+
+We're cordoning off a namespace for built-in ones.

data/docs/users/presets/cropping.md

@@ -0,0 +1,60 @@
+---
+sort: 6
+---
+
+# Cropping
+
+## Crop & Media Crop
+
+_Format:_
+
+```yaml
+    crop: (aspect ratio)
+    media_crop:
+      (media_preset): (aspect ratio)
+      (media_preset): (aspect ratio)
+      (...)
+```
+
+_Example:_
+
+```yaml
+    crop: '16:9'
+    media_crop:
+      tablet: '3:2'
+      mobile: '1:1'
+```
+
+Crop aspect ratio, 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` 
+[tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop).
+
+## Keep & Media Keep
+
+```yaml
+    keep: (measure)
+    media_keep:
+      (media_preset): (measure)
+      (media_preset): (measure)
+      (...)
+```
+
+_Example:_
+
+```yaml
+    keep: attention
+    media_gravity:
+      tablet: entropy
+      mobile: center
+```
+
+Which part of the image to keep when cropping, given either generally or for specific media presets.
+The hierarchy is: `tag argument` > `media_keep:` > `keep:` > `attention` (default).
+
+This setting accepts the same arguments as the `keep` [tag parameter]({{ site.baseurl
+}}/users/liquid_tag/argument_reference/crop):
+* `center` or `centre`
+* `attention`
+* `entropy`

data/docs/users/presets/default.md

@@ -0,0 +1,32 @@
+---
+sort: 12
+---
+
+# 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
+    format_quality:
+      webp: 50
+      avif: 30
+      jp2: 30
+    strip_metadata: true
+    image_options:
+      avif:
+        compression: av1
+        speed: 8
+    data_sizes: true
+    keep: attention
+    dimension_attributes: false
+```