jekyll_picture_tag 1.8.0 → 1.11.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (41) hide show
  1. checksums.yaml +4 -4
  2. data/.rubocop.yml +4 -0
  3. data/.travis.yml +4 -7
  4. data/Dockerfile +9 -0
  5. data/docs/Gemfile.lock +183 -88
  6. data/docs/contributing.md +50 -16
  7. data/docs/example_presets.md +1 -1
  8. data/docs/global_configuration.md +55 -2
  9. data/docs/index.md +27 -21
  10. data/docs/installation.md +22 -7
  11. data/docs/presets.md +137 -55
  12. data/docs/releases.md +20 -1
  13. data/docs/usage.md +83 -39
  14. data/jekyll_picture_tag.gemspec +1 -1
  15. data/lib/jekyll_picture_tag.rb +28 -10
  16. data/lib/jekyll_picture_tag/cache.rb +3 -0
  17. data/lib/jekyll_picture_tag/cache/base.rb +59 -0
  18. data/lib/jekyll_picture_tag/cache/generated.rb +20 -0
  19. data/lib/jekyll_picture_tag/cache/source.rb +19 -0
  20. data/lib/jekyll_picture_tag/defaults/global.yml +2 -0
  21. data/lib/jekyll_picture_tag/defaults/presets.yml +2 -0
  22. data/lib/jekyll_picture_tag/generated_image.rb +85 -20
  23. data/lib/jekyll_picture_tag/img_uri.rb +1 -0
  24. data/lib/jekyll_picture_tag/instructions.rb +1 -0
  25. data/lib/jekyll_picture_tag/instructions/arg_splitter.rb +69 -0
  26. data/lib/jekyll_picture_tag/instructions/configuration.rb +47 -11
  27. data/lib/jekyll_picture_tag/instructions/preset.rb +35 -14
  28. data/lib/jekyll_picture_tag/instructions/set.rb +18 -8
  29. data/lib/jekyll_picture_tag/instructions/tag_parser.rb +59 -69
  30. data/lib/jekyll_picture_tag/output_formats/basic.rb +42 -11
  31. data/lib/jekyll_picture_tag/output_formats/img.rb +11 -0
  32. data/lib/jekyll_picture_tag/output_formats/picture.rb +22 -0
  33. data/lib/jekyll_picture_tag/router.rb +17 -0
  34. data/lib/jekyll_picture_tag/source_image.rb +60 -39
  35. data/lib/jekyll_picture_tag/srcsets/basic.rb +54 -19
  36. data/lib/jekyll_picture_tag/srcsets/pixel_ratio.rb +1 -3
  37. data/lib/jekyll_picture_tag/srcsets/width.rb +1 -1
  38. data/lib/jekyll_picture_tag/utils.rb +18 -0
  39. data/lib/jekyll_picture_tag/version.rb +1 -1
  40. data/readme.md +40 -16
  41. metadata +14 -8
@@ -75,7 +75,7 @@ markup_presets:
75
75
  # your source images will need to be part of the deployed site for this to
76
76
  # work. If you have issues such as mangled HTML or extra {::nomarkdown}
77
77
  # tags floating around, see docs/notes.md
78
- link-source: true
78
+ link_source: true
79
79
 
80
80
  # This is an example of how you would create a 'multiplier' based srcset;
81
81
  # useful when an image will always be the same size on all screens (icons,
@@ -65,7 +65,12 @@ picture:
65
65
 
66
66
  *Default:* `false`
67
67
 
68
- 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 (publish a site with broken images). You can read more about Jekyll environments [here](https://jekyllrb.com/docs/configuration/environments/).
68
+ Normally, JPT will raise an error if a source image is missing, causing the entire site build to
69
+ fail. This setting allows you to bypass this behavior and continue the build, either for certain
70
+ build environments or all the time. I highly encourage you to set this to `development`, and set
71
+ the jekyll build environment to `production` when you build for production so you don't shoot
72
+ yourself in the foot (publish a site with broken images). You can read more about Jekyll
73
+ environments [here](https://jekyllrb.com/docs/configuration/environments/).
69
74
 
70
75
  * **Use Relative Urls**
71
76
 
@@ -111,10 +116,58 @@ picture:
111
116
 
112
117
  *Example:* `nomarkdown: false`
113
118
 
114
- *Default*: `true`
119
+ *Default:* `true`
115
120
 
116
121
  Whether or not to surround j-p-t's output with a `{::nomarkdown}..{:/nomarkdown}` block when called
117
122
  from within a markdown file.
118
123
 
119
124
  This setting is overridden by the same setting in a preset. See [the notes]({{ site.baseurl
120
125
  }}/notes) for more detailed information.
126
+
127
+ * **Fast Build**
128
+
129
+ *Format:* `fast_build: (true|false|environment|array of environments)`
130
+
131
+ *Examples:*
132
+
133
+ - `fast_build: true`
134
+
135
+ - `fast_build: development`
136
+
137
+ - `fast_build: [development, staging]`
138
+
139
+ *Default:* `false`
140
+
141
+ Makes a tradeoff: Speeds repeated build times for sites with many images, by assuming that the
142
+ filename alone is enough to uniquely identify a source image. This doesn't speed up image
143
+ generation, just detection of whether or not it's necessary.
144
+
145
+ Ordinarily, JPT generates an MD5 hash for every source image, every site build. This ensures that
146
+ if you replace one image with another, but keep the filename the same, JPT will correctly generate
147
+ images for the new file. If you have many large images and/or limited hardware, this can take some
148
+ time and make the development process painful. Enable this setting to skip MD5 hash checking on
149
+ existing generated images (most of the time), and just assume that if the filename, format, and
150
+ width match then it's the right one. If there are multiple possible matches (resulting from
151
+ leftover generated images from previous filename replacements), it'll compute a hash instead of
152
+ guessing randomly.
153
+
154
+ * **Disable Jekyll Picture Tag**
155
+
156
+ *Format:* `disabled: (true|false|environment|array of environments)`
157
+
158
+ *Examples:*
159
+
160
+ - `disabled: true`
161
+
162
+ - `disabled: development`
163
+
164
+ - `disabled: [development, staging]`
165
+
166
+ *Default:* `false`
167
+
168
+ Disable image and markup generation entirely. Useful for debugging, or to speed up site builds
169
+ when you're working on something else.
170
+
171
+ Hint: If you're going to toggle this on and off frequently, you might just use an environment
172
+ variable. Set this to something like `nopics`, and then start the Jekyll server with something
173
+ like `JEKYLL_ENV=nopics bundle exec jekyll serve` when you don't want image generation.
@@ -35,14 +35,14 @@ markup_presets:
35
35
  default:
36
36
  formats: [webp, original]
37
37
  ```
38
-
38
+ **Note:** Order matters! `[webp, jpg]` will offer the browser webp-images first. The browser will pick the *first* format it can work with. So if the order is reversed `[jpg, webp]` it will use the jpg image before the webp.
39
39
 
40
40
  ### Here's a more complete demonstration:
41
41
 
42
- [Presets]({{ site.baseurl }}/presets) are named collections of settings that tell JPT what you want it to give you.
43
- Media presets are just CSS media queries, and markup presets determine the output text and images.
44
- You choose one with the second [tag parameter]({{ site.baseurl }}/usage), or omit for the `default` (as in these
45
- examples). They are located in `_data/picture.yml`. Here's an example:
42
+ [Presets]({{ site.baseurl }}/presets) are named collections of settings, and come in 2 kinds: Media
43
+ Presets are named CSS media queries, and Markup Presets determine the output text and images. You
44
+ choose one with the second [tag parameter]({{ site.baseurl }}/usage), or omit for the `default` (as
45
+ in these examples). They are located in `_data/picture.yml`. Here's an example:
46
46
 
47
47
  ```yml
48
48
  media_presets:
@@ -57,13 +57,15 @@ markup_presets:
57
57
  size: 500px
58
58
  ```
59
59
 
60
- Write this:
60
+ Imagemagick can easily crop images to an aspect ratio, though you should **read the whole
61
+ installation guide before using this feature**. With the above preset, if you write this:
62
+
61
63
 
62
64
  {% raw %}
63
- `{% picture test.jpg mobile: test2.jpg --alt Alternate Text %}`
65
+ `{% picture test.jpg 3:2 mobile: test2.jpg 1:1 --alt Alternate Text %}`
64
66
  {% endraw %}
65
67
 
66
- Get this:
68
+ You'll get something like this:
67
69
 
68
70
  ```html
69
71
  <!-- Formatted for readability -->
@@ -73,36 +75,40 @@ Get this:
73
75
  sizes="(max-width: 600px) 80vw, 600px"
74
76
  media="(max-width: 600px)"
75
77
  srcset="
76
- /generated/test2-600-21bb6f.webp 600w,
77
- /generated/test2-900-21bb6f.webp 900w,
78
- /generated/test2-1200-21bb6f.webp 1200w
78
+ /generated/test2-600-21bb6fGUW.webp 600w,
79
+ /generated/test2-900-21bb6fGUW.webp 900w,
80
+ /generated/test2-1200-21bb6fGUW.webp 1200w
79
81
  "
80
82
  type="image/webp">
81
83
  <source
82
84
  sizes="(max-width: 600px) 80vw, 600px"
83
85
  srcset="
84
- /generated/test-600-195f7d.webp 600w,
85
- /generated/test-900-195f7d.webp 900w,
86
- /generated/test-1200-195f7d.webp 1200w
86
+ /generated/test-600-195f7d192.webp 600w,
87
+ /generated/test-900-195f7d192.webp 900w,
88
+ /generated/test-1200-195f7d192.webp 1200w
87
89
  "
88
90
  type="image/webp">
89
91
  <source
90
92
  sizes="(max-width: 600px) 80vw, 600px"
91
93
  media="(max-width: 600px)"
92
94
  srcset="
93
- /generated/test2-600-21bb6f.jpg 600w,
94
- /generated/test2-900-21bb6f.jpg 900w,
95
- /generated/test2-1200-21bb6f.jpg 1200w
95
+ /generated/test2-600-21bb6fGUW.jpg 600w,
96
+ /generated/test2-900-21bb6fGUW.jpg 900w,
97
+ /generated/test2-1200-21bb6fGUW.jpg 1200w
96
98
  "
97
99
  type="image/jpeg">
98
100
  <source
99
101
  sizes="(max-width: 600px) 80vw, 600px"
100
102
  srcset="
101
- /generated/test-600-195f7d.jpg 600w,
102
- /generated/test-900-195f7d.jpg 900w,
103
- /generated/test-1200-195f7d.jpg 1200w
103
+ /generated/test-600-195f7d192.jpg 600w,
104
+ /generated/test-900-195f7d192.jpg 900w,
105
+ /generated/test-1200-195f7d192.jpg 1200w
104
106
  "
105
107
  type="image/jpeg">
106
- <img src="/generated/test-800-195f7d.jpg" alt="Alternate Text">
108
+ <img src="/generated/test-800-195f7dGUW.jpg" alt="Alternate Text">
107
109
  </picture>
108
110
  ```
111
+
112
+ In other words, you have the art direction, format switching, and resolution switching problems
113
+ *solved*, with a one-liner and a nicely readable config file that is 1/3 as long as the output
114
+ markup. Lighthouse is happy, and you don't even need to crop things yourself.
@@ -1,8 +1,9 @@
1
1
  ---
2
2
  ---
3
+
3
4
  # Installation
4
5
 
5
- * Add `jekyll_picture_tag` to your Gemfile in the `:jekyll_plugins` group:
6
+ - Add `jekyll_picture_tag` to your Gemfile in the `:jekyll_plugins` group:
6
7
 
7
8
  ```ruby
8
9
  group :jekyll_plugins do
@@ -10,21 +11,35 @@
10
11
  end
11
12
  ```
12
13
 
13
- * Run `$ bundle install`
14
+ - Run `$ bundle install`
14
15
 
15
- * See if you have ImageMagick with `$ convert --version`. You should see something like this:
16
+ - See if you have ImageMagick with `$ convert --version`. You should see something like this:
16
17
 
17
18
  ```
18
- ~ $ convert --version
19
+ ~ $ convert --version
19
20
  Version: ImageMagick 7.0.8-14 Q16 x86_64 2018-10-31 https://imagemagick.org
20
21
  Copyright: © 1999-2018 ImageMagick Studio LLC License: https://imagemagick.org/script/license.php
21
22
  Features: Cipher DPC HDRI OpenMP Delegates (built-in): bzlib fontconfig freetype jng jp2 jpeg lcms
22
23
  lzma pangocairo png tiff webp xml zlib
23
24
  ```
25
+
24
26
  If you get a 'command not found' error, you'll need to install it. Most package managers know about
25
27
  ImageMagick, otherwise it can be found [here](https://imagemagick.org/script/download.php).
26
28
 
27
- * **Note webp under delegates.** This is required if you want to generate webp files. Any image format
28
- you want to handle will require an appropriate delegate; You may have to install additional packages
29
- to accomplish this.
29
+ - **Note webp under delegates.** This is required if you want to generate webp files. Any image format
30
+ you want to handle will require an appropriate delegate; You may have to install additional packages
31
+ to accomplish this.
32
+
33
+ ## Cropping and Imagemagick
34
+
35
+ Cropping to an aspect ratio depends on ImageMagick 7+. Ubuntu, somewhat annoyingly, only offers
36
+ version 6 in its official repositories. This matters even if you don't run Ubuntu, because many
37
+ build & deployment services you might use (including Netlify and Travis CI) do.
38
+
39
+ If you'd like to use both the cropping feature and such a service, or it's inconvenient to install
40
+ version 7 in your development environment, you will likely want to build your site in a docker
41
+ container. The Alpine Linux repos include version 7, so you'll want an Alpine Linux based image
42
+ rather than an Ubuntu based one. Conveniently this includes the [offical Jekyll
43
+ image](https://hub.docker.com/r/jekyll/jekyll).
30
44
 
45
+ Once I work out how to actually do that, I'll add some guidance here.
@@ -22,7 +22,7 @@ browser widths until you understand it.
22
22
 
23
23
  ## Media Presets
24
24
 
25
- *Format:*
25
+ _Format:_
26
26
 
27
27
  ```yml
28
28
  media_presets:
@@ -32,11 +32,11 @@ media_presets:
32
32
 
33
33
  ```
34
34
 
35
- *Example:*
35
+ _Example:_
36
36
 
37
37
  ```yml
38
38
  media_presets:
39
- desktop: 'min-width: 1200px'
39
+ desktop: "min-width: 1200px"
40
40
  ```
41
41
 
42
42
  These are named media queries for use in a few different places: specifying alternate source images
@@ -45,7 +45,7 @@ settings. Quotes are recommended around the media queries, because yml gets conf
45
45
 
46
46
  ## Markup Presets
47
47
 
48
- *Format:*
48
+ _Format:_
49
49
 
50
50
  ```yml
51
51
  markup_presets:
@@ -56,7 +56,7 @@ markup_presets:
56
56
  (...)
57
57
  ```
58
58
 
59
- *Example:*
59
+ _Example:_
60
60
 
61
61
  ```yml
62
62
  markup_presets:
@@ -84,29 +84,28 @@ The `default` preset will be used if none is specified. A preset name can't cont
84
84
 
85
85
  For images that are different sizes on different screens (most images), use a width-based srcset
86
86
  (which is the default). Specify a `widths` setting (or don't, for the default set), and optionally
87
- the `sizes` and `size` settings.
87
+ the `sizes` and `size` settings.
88
88
 
89
89
  Use a multiplier-based srcset when the image will always be the same size, regardless of screen
90
90
  width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratios` and `base_width`.
91
91
 
92
92
  ### Settings reference
93
93
 
94
- * **Markup format**
94
+ - **Markup format**
95
95
 
96
- *Format:* `markup: (setting)`
96
+ _Format:_ `markup: (setting)`
97
97
 
98
- *Default*: `auto`
98
+ _Default_: `auto`
99
99
 
100
100
  Defines what format the generated text will take. They are documented [here]({{ site.baseurl }}/output).
101
101
 
102
-
103
102
  * **Image Formats**
104
103
 
105
- *Format:* `format: [format1, format2, (...)]`
104
+ _Format:_ `format: [format1, format2, (...)]`
106
105
 
107
- *Example:* `format: [webp, original]`
106
+ _Example:_ `format: [webp, original]`
108
107
 
109
- *Default*: `original`
108
+ _Default_: `original`
110
109
 
111
110
  Array (yml sequence) of the image formats you'd like to generate, in decreasing order of
112
111
  preference. Browsers will render the first format they find and understand, so **If you put jpg
@@ -114,37 +113,37 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
114
113
  webp, you must have an imagemagick webp delegate installed. (Most package managers just name it
115
114
  'webp')
116
115
 
117
- *Supported formats are anything which imagemagick supports, and has an installed delegate. See a
118
- list by running `$ convert --version`*
116
+ _Supported formats are anything which imagemagick supports, and has an installed delegate. See a
117
+ list by running `$ convert --version`_
119
118
 
120
119
  * **Widths**
121
120
 
122
- *Format:* `widths: [integer, integer, (...)]`
121
+ _Format:_ `widths: [integer, integer, (...)]`
123
122
 
124
- *Example:* `widths: [600, 800, 1200]`
123
+ _Example:_ `widths: [600, 800, 1200]`
125
124
 
126
- *Default*: `[400, 600, 800, 1000]`
125
+ _Default_: `[400, 600, 800, 1000]`
127
126
 
128
127
  Array of image widths to generate, in pixels. For use when you want a width-based srcset
129
128
  (`srcset="img.jpg 800w, img2.jpg 1600w"`).
130
129
 
131
130
  * **Media_widths**
132
131
 
133
- *Format:*
132
+ _Format:_
134
133
 
135
134
  ```yml
136
135
  media_widths:
137
136
  (media preset name): [integer, integer, (...)]
138
137
  ```
139
138
 
140
- *Example:*
139
+ _Example:_
141
140
 
142
141
  ```yml
143
142
  media_widths:
144
143
  mobile: [400, 600, 800]
145
144
  ```
146
145
 
147
- *Default:* Widths setting
146
+ _Default:_ Widths setting
148
147
 
149
148
  If you are using art direction, there is no sense in generating desktop-size files for your mobile
150
149
  image. You can specify sets of widths to associate with given media queries. If not specified,
@@ -152,7 +151,7 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
152
151
 
153
152
  * **Sizes**
154
153
 
155
- *Format:*
154
+ _Format:_
156
155
 
157
156
  ```yml
158
157
  sizes:
@@ -160,7 +159,7 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
160
159
  (...)
161
160
  ```
162
161
 
163
- *Example:*
162
+ _Example:_
164
163
 
165
164
  ```yml
166
165
  sizes:
@@ -173,7 +172,7 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
173
172
  image will be (on the screen) when a given media query is true. CSS dimensions can be given in
174
173
  `px`, `em`, or `vw`. To be used along with a width-based srcset.
175
174
 
176
- Provide these in order of most restrictive to least restrictive. The browser will choose the
175
+ Provide these in order of most restrictive to least restrictive. The browser will choose the
177
176
  first one with an applicable media query.
178
177
 
179
178
  You don't have to provide a sizes attribute at all. If you don't, the browser will assume the
@@ -181,17 +180,17 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
181
180
 
182
181
  * **Size**
183
182
 
184
- *Format:* `size: (CSS Dimension)`
183
+ _Format:_ `size: (CSS Dimension)`
185
184
 
186
- *Example:* `size: 80vw`
185
+ _Example:_ `size: 80vw`
187
186
 
188
187
  Unconditional `sizes` setting, to be supplied either alone or after all conditional sizes.
189
188
 
190
189
  * **Pixel Ratios**
191
190
 
192
- *Format:* `pixel_ratios: [number, number, number (...)]`
191
+ _Format:_ `pixel_ratios: [number, number, number (...)]`
193
192
 
194
- *Example:* `pixel_ratios: [1, 1.5, 2]`
193
+ _Example:_ `pixel_ratios: [1, 1.5, 2]`
195
194
 
196
195
  Array of images to construct, given in multiples of the base width. If you set this, you must also
197
196
  give a `base_width`.
@@ -200,26 +199,79 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
200
199
 
201
200
  * **Base Width**
202
201
 
203
- *Format:* `base_width: integer`
202
+ _Format:_ `base_width: integer`
204
203
 
205
- *Example:* `base_width: 100`
204
+ _Example:_ `base_width: 100`
206
205
 
207
206
  When using pixel ratios, you must supply a base width. This sets how wide the 1x image should be.
208
207
 
208
+ * **Crop & Media Crop**
209
+
210
+ _Format:_
211
+
212
+ ```yml
213
+ crop: (geometery)
214
+ media_crop:
215
+ (media_preset): (geometry)
216
+ (media_preset): (geometry)
217
+ (...)
218
+ ```
219
+
220
+ _Example:_
221
+
222
+ ```yml
223
+ crop: 16:9
224
+ media_crop:
225
+ tablet: 3:2
226
+ mobile: 1:1
227
+ ```
228
+
229
+ **Check the [ installation guide ](installation) before using this feature.**
230
+
231
+ Crop geometry, given either generally or for specific media presets. The hierarchy is:
232
+ `tag argument` > `media_crop:` > `crop:`.
233
+
234
+ This setting accepts the same arguments as the `crop geometry` [tag parameter](usage).
235
+
236
+
237
+ * **Gravity & Media_gravity**
238
+
239
+ ```yml
240
+ crop: (gravity)
241
+ media_crop:
242
+ (media_preset): (gravity)
243
+ (media_preset): (gravity)
244
+ (...)
245
+ ```
246
+
247
+ _Example:_
248
+
249
+ ```yml
250
+ crop: north
251
+ media_crop:
252
+ tablet: east
253
+ mobile: southwest
254
+ ```
255
+
256
+ Crop gravity, given either generally or for specific media presets. The hierarchy is:
257
+ `tag argument` > `media_crop:` > `crop:` > `center` (default).
258
+
259
+ This setting accepts the same arguments as the `crop gravity` [tag parameter](usage).
260
+
209
261
  * **Quality**
210
262
 
211
- *Format:* `quality: 0 <= integer <= 100`
263
+ _Format:_ `quality: 0 <= integer <= 100`
212
264
 
213
- *Example:* `quality: 80`
265
+ _Example:_ `quality: 80`
214
266
 
215
- *Default:* `75`
267
+ _Default:_ `75`
216
268
 
217
269
  This allows you to specify an image compression level for all image formats (where it makes sense,
218
270
  anyway). The next option allows you to set them per format.
219
271
 
220
272
  * **Format Quality**
221
273
 
222
- *Format:*
274
+ _Format:_
223
275
 
224
276
  ```yml
225
277
  format_quality:
@@ -227,7 +279,7 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
227
279
  (...)
228
280
  ```
229
281
 
230
- *Example:*
282
+ _Example:_
231
283
 
232
284
  ```
233
285
  format_quality:
@@ -236,16 +288,46 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
236
288
  webp: 55
237
289
  ```
238
290
 
239
- *Default:* quality setting (above)
291
+ _Default:_ quality setting (above)
240
292
 
241
293
  This allows you to specify quality settings for various image formats, allowing you to take
242
294
  advantage of webp's better compression algorithm without trashing your jpg images (for example).
243
295
  If you don't give a setting for a particular format it'll fall back to the `quality` setting
244
- above, and if you don't set *that* it'll default to 75.
296
+ above, and if you don't set _that_ it'll default to 75.
245
297
 
246
- * **HTML Attributes**
298
+ * **Width & Height attributes (Anti-Loading-Jank)**
247
299
 
248
- *Format:*
300
+ _Format:_
301
+
302
+ ```yml
303
+ dimension_attributes: true | false
304
+ ```
305
+
306
+ _Example:_
307
+
308
+ ```yml
309
+ dimension_attributes: true
310
+ ```
311
+
312
+ _Default:_ `false`
313
+
314
+ Prevent page reflow (aka jank) while images are loading, by adding `width` and `height` attributes
315
+ to the `<img>` tag in the correct aspect ratio.
316
+
317
+ For an explanation of why and how you want to do this, [here](https://youtu.be/4-d_SoCHeWE) is a
318
+ great explanation.
319
+
320
+ Caveats:
321
+ * You need `width: 100%;` and `height: auto;` (or vice versa) set in CSS on the `<img>`
322
+ tags, or they will be stretched weirdly.
323
+ * This works on `<img>` tags and `<picture>` tags when offering images in multiple widths and
324
+ formats, but it does not work if you are using art direction (in other words, if you have
325
+ multiple source images). This is because these attributes can only be applied to the `<img>`
326
+ tag, of which there is exactly one.
327
+
328
+ * **Arbitrary HTML Attributes**
329
+
330
+ _Format:_
249
331
 
250
332
  ```yml
251
333
  attributes:
@@ -253,7 +335,7 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
253
335
  (...)
254
336
  ```
255
337
 
256
- *Example:*
338
+ _Example:_
257
339
 
258
340
  ```yml
259
341
  attributes:
@@ -261,49 +343,49 @@ width (thumbnails and icons). To use a multiplier-based srcset, set `pixel_ratio
261
343
  picture: 'class="even-cooler"'
262
344
  ```
263
345
 
264
- HTML attributes you would like to add. The same arguments are available here as in the liquid
346
+ HTML attributes you would like to add. The same arguments are available here as in the liquid
265
347
  tag: HTML element names, `alt:`, `link:`, and `parent:`. Unescaped double quotes cause problems
266
348
  with yml, so it's recommended to surround them with single quotes.
267
349
 
268
350
  * **Fallback Width**
269
351
 
270
- *Format:* `fallback_width: (integer)`
352
+ _Format:_ `fallback_width: (integer)`
271
353
 
272
- *Example:* `fallback_width: 800`
354
+ _Example:_ `fallback_width: 800`
273
355
 
274
- *Default*: `800`
356
+ _Default_: `800`
275
357
 
276
358
  Width of the fallback image.
277
359
 
278
360
  * **Fallback Format**
279
361
 
280
- *Format:* `fallback_format: (format)`
362
+ _Format:_ `fallback_format: (format)`
281
363
 
282
- *Example:* `fallback_format: jpg`
364
+ _Example:_ `fallback_format: jpg`
283
365
 
284
- *Default*: `original`
366
+ _Default_: `original`
285
367
 
286
368
  Format of the fallback image
287
369
 
288
370
  * **Source Image Link**
289
371
 
290
- *Format:* `link_source: (true|false)`
372
+ _Format:_ `link_source: (true|false)`
291
373
 
292
- *Example:* `link_source: true`
374
+ _Example:_ `link_source: true`
293
375
 
294
- *Default:* `false`
376
+ _Default:_ `false`
295
377
 
296
378
  Surround image with a link to the original source file. Your source image directory must be
297
379
  published as part of the compiled site. If you run into weird issues with the output, see
298
380
  the [notes]({{ site.baseurl }}/notes).
299
381
 
300
382
  * **Nomarkdown override**
301
-
302
- *Format:* `nomarkdown: (true|false)`
303
383
 
304
- *Example:* `nomarkdown: false`
384
+ _Format:_ `nomarkdown: (true|false)`
385
+
386
+ _Example:_ `nomarkdown: false`
305
387
 
306
- *Default:* `nil`
388
+ _Default:_ `nil`
307
389
 
308
390
  Hard setting for `{::nomarkdown}` tags, overrides both autodetection and the global setting in
309
- `_config.yml`. See the [notes]({{ site.baseurl }}/notes) for a detailed explanation.
391
+ `_config.yml`. See the [notes]({{ site.baseurl }}/notes) for a detailed explanation.