jekyll_picture_tag 1.14.0 → 2.0.0pre1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. checksums.yaml +4 -4
  2. data/.envrc +2 -0
  3. data/.github/workflows/code-checks.yml +2 -12
  4. data/.rubocop.yml +2 -0
  5. data/.ruby-version +1 -1
  6. data/docs/devs/contributing/code.md +11 -3
  7. data/docs/devs/contributing/testing.md +0 -11
  8. data/docs/devs/releases.md +20 -0
  9. data/docs/index.md +32 -17
  10. data/docs/logo.png +0 -0
  11. data/docs/logo.svg +880 -0
  12. data/docs/users/getting_started.md +55 -0
  13. data/docs/users/installation.md +17 -38
  14. data/docs/users/liquid_tag/argument_reference/crop.md +21 -36
  15. data/docs/users/liquid_tag/examples.md +13 -25
  16. data/docs/users/liquid_tag/index.md +1 -1
  17. data/docs/users/notes/{migration.md → migration_1.md} +1 -1
  18. data/docs/users/notes/migration_2.md +99 -0
  19. data/docs/users/presets/cropping.md +21 -22
  20. data/docs/users/presets/default.md +11 -3
  21. data/docs/users/presets/examples.md +77 -45
  22. data/docs/users/presets/fallback_image.md +1 -1
  23. data/docs/users/presets/html_attributes.md +1 -1
  24. data/docs/users/presets/image_formats.md +3 -3
  25. data/docs/users/presets/image_quality.md +70 -55
  26. data/docs/users/presets/index.md +78 -42
  27. data/docs/users/presets/link_source.md +1 -1
  28. data/docs/users/presets/media_queries.md +1 -1
  29. data/docs/users/presets/nomarkdown_override.md +1 -1
  30. data/docs/users/presets/pixel_ratio_srcsets.md +1 -1
  31. data/docs/users/presets/width_height_attributes.md +1 -1
  32. data/docs/users/presets/width_srcsets.md +61 -23
  33. data/docs/users/tutorial.md +97 -0
  34. data/jekyll_picture_tag.gemspec +33 -23
  35. data/lib/jekyll_picture_tag.rb +8 -6
  36. data/lib/jekyll_picture_tag/cache.rb +64 -3
  37. data/lib/jekyll_picture_tag/defaults/global.rb +18 -0
  38. data/lib/jekyll_picture_tag/defaults/presets.rb +57 -0
  39. data/lib/jekyll_picture_tag/images.rb +1 -0
  40. data/lib/jekyll_picture_tag/images/generated_image.rb +25 -63
  41. data/lib/jekyll_picture_tag/images/image_file.rb +90 -0
  42. data/lib/jekyll_picture_tag/images/img_uri.rb +3 -12
  43. data/lib/jekyll_picture_tag/images/source_image.rb +44 -9
  44. data/lib/jekyll_picture_tag/instructions.rb +70 -6
  45. data/lib/jekyll_picture_tag/instructions/children/config.rb +128 -0
  46. data/lib/jekyll_picture_tag/instructions/children/context.rb +24 -0
  47. data/lib/jekyll_picture_tag/instructions/children/params.rb +90 -0
  48. data/lib/jekyll_picture_tag/instructions/children/parsers.rb +41 -0
  49. data/lib/jekyll_picture_tag/instructions/children/preset.rb +182 -0
  50. data/lib/jekyll_picture_tag/instructions/parents/conditional_instruction.rb +69 -0
  51. data/lib/jekyll_picture_tag/instructions/parents/env_instruction.rb +29 -0
  52. data/lib/jekyll_picture_tag/output_formats/basic.rb +5 -17
  53. data/lib/jekyll_picture_tag/parsers.rb +5 -0
  54. data/lib/jekyll_picture_tag/{instructions → parsers}/arg_splitter.rb +1 -1
  55. data/lib/jekyll_picture_tag/parsers/configuration.rb +28 -0
  56. data/lib/jekyll_picture_tag/{instructions → parsers}/html_attributes.rb +1 -1
  57. data/lib/jekyll_picture_tag/parsers/preset.rb +43 -0
  58. data/lib/jekyll_picture_tag/{instructions → parsers}/tag_parser.rb +15 -12
  59. data/lib/jekyll_picture_tag/router.rb +35 -93
  60. data/lib/jekyll_picture_tag/srcsets/basic.rb +4 -10
  61. data/lib/jekyll_picture_tag/utils.rb +10 -20
  62. data/lib/jekyll_picture_tag/version.rb +1 -1
  63. data/readme.md +2 -0
  64. metadata +124 -106
  65. data/Dockerfile +0 -9
  66. data/docs/users/notes/input_checking.md +0 -6
  67. data/docs/users/presets/strip_metadata.md +0 -13
  68. data/install_imagemagick.sh +0 -23
  69. data/jekyll-picture-tag.gemspec +0 -52
  70. data/lib/jekyll-picture-tag.rb +0 -25
  71. data/lib/jekyll_picture_tag/cache/base.rb +0 -61
  72. data/lib/jekyll_picture_tag/cache/generated.rb +0 -20
  73. data/lib/jekyll_picture_tag/cache/source.rb +0 -19
  74. data/lib/jekyll_picture_tag/defaults/global.yml +0 -13
  75. data/lib/jekyll_picture_tag/defaults/presets.yml +0 -12
  76. data/lib/jekyll_picture_tag/instructions/configuration.rb +0 -121
  77. data/lib/jekyll_picture_tag/instructions/preset.rb +0 -122
  78. data/lib/jekyll_picture_tag/instructions/set.rb +0 -75
@@ -0,0 +1,55 @@
1
+ ---
2
+ sort: 2
3
+ ---
4
+
5
+ # Getting started
6
+
7
+ Firstly, let me warn you that responsive images are somewhat complicated, and fall squarely into
8
+ "proper web development" territory. To do this well, you will need to do some learning. The default
9
+ settings are a starting point, meant to get you up and running with something reasonable while
10
+ minimizing unexpected behavior.
11
+
12
+ Here are some good guides:
13
+
14
+ * [MDN Responsive Images guide](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)
15
+ * [CSS Tricks Guide to Reponsive Images](https://css-tricks.com/a-guide-to-the-responsive-images-syntax-in-html/)
16
+ * [Cloud 4 - Responsive Images 101](https://cloudfour.com/thinks/responsive-images-101-definitions/)
17
+
18
+ ## Step 1: Customize global settings
19
+
20
+ JPT's [global configuration](configuration) happens under the `picture:` key in `_config.yml`. The
21
+ defaults are probably fine, though you may want to configure the input and output
22
+ [directories](configuration/directories).
23
+
24
+ ## Step 2: Test & Learn
25
+
26
+ - If you're not already familiar, there's a short [tutorial](tutorial) to get you started with the basics.
27
+ - Look over the [example presets](presets/examples)
28
+ - Look over the [example liquid tags](liquid_tag/examples) and [instructions](liquid_tag).
29
+
30
+ ## Step 3: Add breakpoints
31
+
32
+ Once you have a feel for how this plugin works, it's time to adapt it to your particular site. The
33
+ built-in `jpt-` media queries probably don't quite fit your layout; Find whatever breakpoints your
34
+ css uses, and tell JPT about them:
35
+
36
+ 1. Create `_data/picture.yml`
37
+ 2. List them under the `media_queries:` key. Give them easy-to-remember names, and wrap them in
38
+ single quotes.
39
+
40
+ ```yaml
41
+ # _data/picture.yml
42
+
43
+ media_queries:
44
+ (name): '(media query)'
45
+ (...)
46
+
47
+ ```
48
+
49
+ If you're using bootstrap or something, you don't need to plug in every single breakpoint they have,
50
+ just a handful that you'll actually use.
51
+
52
+ ## Step 4: Write presets
53
+
54
+ From there, it's time to [write your own presets](presets). Start with the `default`, and then move
55
+ on to cover all the different ways you use images in your site.
@@ -1,52 +1,31 @@
1
1
  ---
2
+ sort: 1
2
3
  ---
3
4
 
4
5
  # Installation
5
6
 
6
7
  1. Add `jekyll_picture_tag` to your Gemfile in the `:jekyll_plugins` group.
7
- (Note that it's NOT `jekyll-picture-tag`):
8
+
9
+ ```note
10
+ It's NOT `jekyll-picture-tag`.
11
+ ```
12
+
8
13
  ```ruby
9
14
  # Gemfile
10
15
 
11
- gem 'jekyll'
16
+ gem 'jekyll', ~> '4.0'
12
17
 
13
18
  group :jekyll_plugins do
14
- gem 'jekyll_picture_tag', ~> '1'
19
+ # (other jekyll plugins)
20
+ gem 'jekyll_picture_tag', ~> '2.0'
15
21
  end
16
22
  ```
17
- 2. Run `$ bundle install`
18
- 3. See if you have ImageMagick with `$ convert --version`. You should see
19
- something like this:
20
- ```bash
21
- ~ $ convert --version
22
- Version: ImageMagick 7.0.8-14 Q16 x86_64 2018-10-31 https://imagemagick.org
23
- Copyright: © 1999-2018 ImageMagick Studio LLC License: https://imagemagick.org/script/license.php
24
- Features: Cipher DPC HDRI OpenMP Delegates (built-in): bzlib fontconfig freetype jng jp2 jpeg lcms
25
- lzma pangocairo png tiff webp xml zlib
26
- ```
27
- If you get a 'command not found' error, you'll need to install it. Most
28
- package managers know about ImageMagick, otherwise it can be found
29
- [here](https://imagemagick.org/script/download.php).
30
23
 
31
- ```note
32
- You need a 'webp' delegate if you want to generate webp files. Any image
33
- format you want to handle will require an appropriate delegate; You may have
34
- to install additional packages to accomplish this. Usually it's just named
35
- 'webp'.
36
- ```
37
-
38
- ```warning
39
- Cropping to an aspect ratio depends on ImageMagick 7+. Ubuntu, somewhat
40
- annoyingly, only offers version 6 in its official repositories. This matters
41
- even if you don't run Ubuntu, because many build & deployment services you might
42
- use (including Netlify and Travis CI) do.
43
- ```
44
-
45
- If you'd like to use both the cropping feature and such a service, or it's
46
- inconvenient to install version 7 in your development environment, you will
47
- likely want to build your site in a docker container. The Alpine Linux repos
48
- include version 7, so you'll want an Alpine Linux based image rather than an
49
- Ubuntu based one. Conveniently this includes the [offical Jekyll
50
- image](https://hub.docker.com/r/jekyll/jekyll).
51
-
52
- Once I work out how to actually do that, I'll add some guidance here.
24
+ 2. Run `$ bundle install`
25
+ 3. Install `libvips`. Most package managers know about it, otherwise it can be found
26
+ [here](https://libvips.github.io/libvips/install.html).
27
+ 4. Install libvips dependencies for all image formats you will use, such as `libpng`, `libwebp`,
28
+ `libjpeg`, and `libheif` (for avif).
29
+ 5. Optional: Install `ImageMagick` for additional image formats. If vips runs into an image format
30
+ it can't handle (jp2 on my particular installation), JPT will instruct it to try ImageMagick
31
+ instead.
@@ -4,45 +4,30 @@ sort: 3
4
4
 
5
5
  # Crop
6
6
 
7
- ```warning
8
- Ensure that both your development and production build environments have
9
- ImageMagick 7+ installed before using this feature. Anything based on Ubuntu
10
- likely does not. The installation guide has more information.
11
- ```
7
+ Crop an image to a given aspect ratio. This argument is given as a `crop` and (optionally) a `keep`
8
+ setting. The values given here will override the preset settings (if present), can be given after
9
+ every image, and apply only to the preceding image.
12
10
 
13
- Crop an image to a given aspect ratio or size. This argument is given as a
14
- `geometry` and (optionally) a `gravity`, which can appear in either order and
15
- are thin wrappers around ImageMagick's
16
- [geometry](http://www.imagemagick.org/script/command-line-processing.php#geometry)
17
- and
18
- [gravity](http://www.imagemagick.org/script/command-line-options.php#gravity)
19
- settings. The values given here will override the preset settings (if present),
20
- can be given after every image, and apply only to the preceding image.
21
-
22
- Geometry can take many forms, but most likely you'll want to set an aspect
23
- ratio-- given in the standard `width:height` ratio such as `3:2`. Gravity sets
24
- which portion of the image to keep, and is given in compass directions (`north`,
25
- `southeast`, etc) or `center` (default). Cropping happens before resizing; the
26
- preset `widths` setting is a post-crop value.
27
-
28
- If you'd like more fine-grained control, this can be offset by appending `+|-x`
29
- and (optionally) `y` pixel values to the _geometry_ (not the gravity!). Example:
30
- `1:1+400 west` means "Crop to a 1:1 aspect ratio, starting 400 pixels from the
31
- left side.", and `north 3:2+0+100` means "Crop to 3:2, starting 100 pixels from
32
- the top." These can get a bit persnickety; there's nothing to stop you from
33
- running off the side of the image. Pay attention.
34
-
35
- For detailed documentation, see ImageMagick's
36
- [crop](http://www.imagemagick.org/script/command-line-options.php#crop) tool.
11
+ `crop` is given as an aspect ratio in the `width:height` format.
37
12
 
38
- ## Examples
13
+ `keep` sets which portion of the image to keep; it's the
14
+ ['interestingness'](https://libvips.github.io/libvips/API/current/libvips-conversion.html#VipsInteresting)
15
+ setting passed to the [libvips
16
+ smartcrop](https://libvips.github.io/libvips/API/current/libvips-conversion.html#vips-smartcrop)
17
+ function. Your options are:
39
18
 
40
- - `16:9`
41
- - `1:1 west`
42
- - `3:2+20+50 northeast`
19
+ * `attention` - automagically keep parts likely to draw human attention. **Default**
20
+ * `entropy` - Crop out the parts with the least variation.
21
+ * `center` or `centre` - Keep the middle part.
43
22
 
44
23
  ```note
45
- If you do a lot of trial and error with these, it's a good idea to manually
46
- delete your generated images folder more often as each change will build a new
47
- set of images without removing the old ones.
24
+ Cropping happens before resizing; the preset `widths` setting is a post-crop value.
48
25
  ```
26
+
27
+ More fine-grained control is beyond the scope of this plugin. I'm not writing an image editor here!
28
+
29
+ ## Examples
30
+
31
+ - `16:9`
32
+ - `1:1 entropy`
33
+ - `3:2 center`
@@ -27,44 +27,32 @@
27
27
 
28
28
  * Use liquid variables:
29
29
  ```
30
- {% picture {{ page.some_liquid_variable }} %}
30
+ {% picture "{{ page.some_liquid_variable }}" %}
31
31
  ```
32
32
 
33
33
  * Select the blog_index preset, use liquid variables, and wrap the image in an
34
34
  anchor tag (link):
35
35
  ```
36
- {% picture blog_index {{ post.image }} --link {{ post.url }} %}
37
- ```
38
- N.B. If the image path is coming from a liquid variable then you have two problems to guard against.
39
- * __Spaces__: you need to wrap the inner tag in "" to stop a path with spaces being interpretted as two or more arguments:
40
- ```
41
- {% picture blog_index "{{ post.image }}" %}
42
- ```
43
- * __Nulls & Blanks__: you need to wrap whole tag in a logic block to stop an uncaught Liquid exception:
44
- ```
45
- {% if post.image && post.image != "" %}
46
- {% picture blog_index "{{ post.image }}" %}
47
- {% endif %}
48
- ```
49
-
36
+ {% picture blog_index "{{ post.image }}" --link {{ post.url }} %}
37
+ ```
38
+
39
+ **Note:** If the image path is coming from a liquid variable then you should guard against spaces
40
+ by wrapping the inner tag in quotes, as in the previous examples.
50
41
 
51
42
  * Add arbitrary HTML attributes:
52
43
  ```
53
44
  {% picture example.jpg --picture class="some classes" --img id="example" %}
54
45
  ```
55
46
 
56
- ```warning
57
- Read the whole installation guide before using the crop feature.
58
- ```
59
-
60
- * Crop to a 16:9 aspect ratio, keeping the top:
47
+ * Crop to a 16:9 aspect ratio (Will keep the part of the image "most likely to
48
+ draw human attention"):
61
49
  ```
62
- {% picture example.jpg 16:9 north %}
50
+ {% picture example.jpg 16:9 %}
63
51
  ```
64
52
 
65
53
  * Crop to a 1:1 aspect ratio, keeping the middle, with alt text:
66
54
  ```
67
- {% picture thumbnail example.jpg 1:1 --alt Example Image %}
55
+ {% picture thumbnail example.jpg 1:1 center --alt Example Image %}
68
56
  ```
69
57
 
70
58
  * Crop the same image multiple times:
@@ -82,9 +70,9 @@
82
70
  {%
83
71
  picture
84
72
  hero
85
- example.jpg 16:9 east
86
- tablet: example2.jpg 3:2 east
87
- mobile: example3.jpg 1:1-50+0 east
73
+ example.jpg 16:9 entropy
74
+ tablet: example2.jpg 3:2
75
+ mobile: example3.jpg 1:1
88
76
  --alt Happy Puppy
89
77
  --picture class="hero"
90
78
  --link /
@@ -22,7 +22,7 @@ fine, and you can use liquid variables anywhere.
22
22
 
23
23
  * `(image)` - required.
24
24
 
25
- * `crop` - Geometry and gravity arguments, passed to imagemagick.
25
+ * `crop` - Aspect ratio & keep settings.
26
26
 
27
27
  * `alternate images & crops` - Art Direction; show different images on different
28
28
  devices. Give in order of ascending specificity.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  ---
3
- # Migrating from versions < 1.0
3
+ # Migrating from 0.x to 1.x
4
4
 
5
5
  This document details the changes from previous versions (Everything before 1.0), and how to migrate
6
6
  an existing site to the new version. It won't be updated to reflect new features -- it simply
@@ -0,0 +1,99 @@
1
+ ---
2
+ ---
3
+ # Migrating from 1.x to 2.x
4
+
5
+ There are a few breaking changes from 1.x versions, but they've been minimized and hopefully they
6
+ won't affect you too badly. This is a guide to transitioning an existing site; We don't go into all
7
+ the new features here, except where they replace or modify existing ones.
8
+
9
+ - For easy skimming, anything with a bullet point (like this line) is something you need to
10
+ check/do.
11
+
12
+ ## Libvips
13
+
14
+ - Install Libvips, both in development and production. Any reasonably recent version will do.
15
+
16
+ We still fall back to ImageMagick when Vips doesn't support a given image format, so there's no
17
+ reason to uninstall it. However, we no longer require version 7. Version 6+ is fine, which makes
18
+ deployments involving Ubuntu much easier.
19
+
20
+ ## Jekyll 4.0+
21
+
22
+ - Update to Jekyll 4.x
23
+
24
+ We're removing support for versions of Jekyll before 4.0. I did it inadvertently awhile ago with the
25
+ fast_build setting, now it's official. If this causes you a great deal of pain, speak up and we'll
26
+ look into supporting older versions.
27
+
28
+ ## Ruby 2.6+
29
+
30
+ - Ensure you're running Ruby 2.6 or later.
31
+
32
+ While Jekyll supports 2.4, it's officialy EOL and 2.5 (our previous target) is in security
33
+ maintenance only. Since I want major version releases to be as rare as possible, we're making this
34
+ move now. Again, speak up if this causes a great deal of pain.
35
+
36
+ ## Image quality & write options.
37
+
38
+ - If you have set `quality:` in a preset, it will likely stop having an effect. You need to set
39
+ `format_quality:` instead.
40
+
41
+ Previously, all image formats used a default quality of 75. We have now set a default quality for 3
42
+ formats:
43
+
44
+ ```yml
45
+ format_quality:
46
+ webp: 50
47
+ avif: 30
48
+ jp2: 30
49
+ ```
50
+
51
+ Since `format_quality` overrides `quality`, your `quality` setting won't affect those formats
52
+ anymore.
53
+
54
+ - Lossless webp or avif was previously accomplished by setting quality to 100. Now, that is
55
+ accomplished with an image option:
56
+
57
+ ```yml
58
+ #_data/picture.yml
59
+ presets:
60
+
61
+ my_preset:
62
+ image_options:
63
+ webp:
64
+ lossless: true
65
+ ```
66
+
67
+ ## Setting names changing
68
+
69
+ In `_data/picture.yml`,
70
+ - `markup_presets` is now `presets`
71
+ - `media_presets` is now `media_queries`.
72
+
73
+ Go check, especially if you've been using JPT for awhile. We renamed them several versions ago, but
74
+ the old names were still supported until now. If you get a bunch of 'preset not found' warnings,
75
+ this is probably why.
76
+
77
+
78
+ ## Crop changes
79
+
80
+ - Anywhere you've set a crop geometry in any format other than `w:h`, remove or change it. This
81
+ could be in both tags and presets.
82
+ - Anywhere you've set a crop gravity such as `north` or `southeast`, remove it. This could also be
83
+ in both tags and presets.
84
+ - Build the site, look through cropped images and decide if you like the results. Adjust the new
85
+ `keep` setting if desired.
86
+
87
+ We now use the Libvips smartcrop feature which does some magic to keep the most interesting part.
88
+ `gravity` is now `keep` (as in which part of the image to keep), and your options are `attention`,
89
+ `entropy`, or `centre`/`center`. The default is `attention`, and it works pretty well in my testing
90
+ so far.
91
+
92
+ If you can't get satisfactory results with those options, you'll have to use a proper editor. JPT is
93
+ not one, and the old crop feature went too far down the road of trying to be.
94
+
95
+ ## Naming of presets and media queries
96
+
97
+ - If you have any presets or media queries with names that start with `jpt-`, change them.
98
+
99
+ We're cordoning off a namespace for built-in ones.
@@ -1,22 +1,18 @@
1
1
  ---
2
- sort: 5
2
+ sort: 6
3
3
  ---
4
4
 
5
5
  # Cropping
6
6
 
7
- **Check the warning in the
8
- [installation guide]({{ site.baseurl }}/users/installation)
9
- before using this feature.**
10
-
11
7
  ## Crop & Media Crop
12
8
 
13
9
  _Format:_
14
10
 
15
11
  ```yaml
16
- crop: (geometery)
12
+ crop: (aspect ratio)
17
13
  media_crop:
18
- (media_preset): (geometry)
19
- (media_preset): (geometry)
14
+ (media_preset): (aspect ratio)
15
+ (media_preset): (aspect ratio)
20
16
  (...)
21
17
  ```
22
18
 
@@ -29,33 +25,36 @@ _Example:_
29
25
  mobile: '1:1'
30
26
  ```
31
27
 
32
- Crop geometry, given either generally or for specific media presets. The
28
+ Crop aspect ratio, given either generally or for specific media presets. The
33
29
  hierarchy is: `tag argument` > `media_crop:` > `crop:`.
34
30
 
35
- This setting accepts the same arguments as the `crop geometry`
31
+ This setting accepts the same arguments as the `crop`
36
32
  [tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop).
37
33
 
38
- ## Gravity & Media Gravity
34
+ ## Keep & Media Keep
39
35
 
40
36
  ```yaml
41
- gravity: (gravity)
42
- media_gravity:
43
- (media_preset): (gravity)
44
- (media_preset): (gravity)
37
+ keep: (measure)
38
+ media_keep:
39
+ (media_preset): (measure)
40
+ (media_preset): (measure)
45
41
  (...)
46
42
  ```
47
43
 
48
44
  _Example:_
49
45
 
50
46
  ```yaml
51
- gravity: north
47
+ keep: attention
52
48
  media_gravity:
53
- tablet: east
54
- mobile: southwest
49
+ tablet: entropy
50
+ mobile: center
55
51
  ```
56
52
 
57
- Crop gravity, given either generally or for specific media presets. The hierarchy is:
58
- `tag argument` > `media_gravity:` > `gravity:` > `center` (default).
53
+ Which part of the image to keep when cropping, given either generally or for specific media presets.
54
+ The hierarchy is: `tag argument` > `media_keep:` > `keep:` > `attention` (default).
59
55
 
60
- This setting accepts the same arguments as the `crop gravity`
61
- [tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop).
56
+ This setting accepts the same arguments as the `keep` [tag parameter]({{ site.baseurl
57
+ }}/users/liquid_tag/argument_reference/crop):
58
+ * `center` or `centre`
59
+ * `attention`
60
+ * `entropy`