jekyll-picture-tag-latest 1.3.0

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 (41) hide show
  1. checksums.yaml +7 -0
  2. data/.gitignore +12 -0
  3. data/.ruby-version +1 -0
  4. data/Gemfile +4 -0
  5. data/LICENSE.txt +24 -0
  6. data/Rakefile +1 -0
  7. data/bin/console +14 -0
  8. data/bin/setup +7 -0
  9. data/examples/_config.yml +4 -0
  10. data/examples/_data/picture.yml +85 -0
  11. data/examples/post.md +18 -0
  12. data/jekyll-picture-tag-latest.gemspec +40 -0
  13. data/lib/jekyll-picture-tag.rb +67 -0
  14. data/lib/jekyll-picture-tag/defaults/global.yml +11 -0
  15. data/lib/jekyll-picture-tag/defaults/presets.yml +7 -0
  16. data/lib/jekyll-picture-tag/generated_image.rb +68 -0
  17. data/lib/jekyll-picture-tag/instructions.rb +105 -0
  18. data/lib/jekyll-picture-tag/instructions/configuration.rb +117 -0
  19. data/lib/jekyll-picture-tag/instructions/html_attributes.rb +59 -0
  20. data/lib/jekyll-picture-tag/instructions/preset.rb +61 -0
  21. data/lib/jekyll-picture-tag/instructions/tag_parser.rb +48 -0
  22. data/lib/jekyll-picture-tag/output_formats.rb +9 -0
  23. data/lib/jekyll-picture-tag/output_formats/auto.rb +15 -0
  24. data/lib/jekyll-picture-tag/output_formats/basics.rb +105 -0
  25. data/lib/jekyll-picture-tag/output_formats/data_attributes.rb +44 -0
  26. data/lib/jekyll-picture-tag/output_formats/data_auto.rb +14 -0
  27. data/lib/jekyll-picture-tag/output_formats/data_img.rb +8 -0
  28. data/lib/jekyll-picture-tag/output_formats/data_picture.rb +8 -0
  29. data/lib/jekyll-picture-tag/output_formats/direct_url.rb +13 -0
  30. data/lib/jekyll-picture-tag/output_formats/img.rb +24 -0
  31. data/lib/jekyll-picture-tag/output_formats/picture.rb +66 -0
  32. data/lib/jekyll-picture-tag/source_image.rb +62 -0
  33. data/lib/jekyll-picture-tag/srcsets.rb +3 -0
  34. data/lib/jekyll-picture-tag/srcsets/basics.rb +78 -0
  35. data/lib/jekyll-picture-tag/srcsets/pixel_ratio.rb +32 -0
  36. data/lib/jekyll-picture-tag/srcsets/width.rb +45 -0
  37. data/lib/jekyll-picture-tag/utils.rb +67 -0
  38. data/lib/jekyll-picture-tag/version.rb +3 -0
  39. data/migration.md +178 -0
  40. data/readme.md +823 -0
  41. metadata +205 -0
data/migration.md ADDED
@@ -0,0 +1,178 @@
1
+ # Update and Migration guide
2
+
3
+ This document details the changes from previous versions (Everything before 1.0), and how to migrate
4
+ an existing site to the new version. For now it's a markdown document, once this branch is merged
5
+ into master it'll be a wiki page.
6
+
7
+ ## Changes from previous versions:
8
+
9
+ - The default output formats are bone-stock HTML. Picturefill, as of version 3, no longer requires
10
+ special markup, so it remains compatible. Other javascript image solutions are supported with
11
+ the `data_` selection of markup formats. Interchange support is removed, though adding it again
12
+ is not difficult if there is demand for it.
13
+ - There are now 2 basic markup formats to choose from: `<source>` tags within a `<picture>`, and a
14
+ single `<img>` tag. If markup is set to 'auto', or if it is not set at all, the plugin will
15
+ automatically determine which is most appropriate. These formats also have `data_` counterparts
16
+ (i.e. `data_auto`), which accomplish the same thing except setting respective data-attributes
17
+ to allow for lazy loading and such.
18
+ - There are also 2 srcset formats: one which supplies image width, and another which supplies
19
+ multiples (pixel ratios) of the base size.
20
+ - Source Keys are replaced by media query presets, which can also be used to create the 'sizes'
21
+ attribute.
22
+ - Jekyll Picture Tag no longer accepts height arguments, and will no longer crop images for you.
23
+ Aspect ratio will always be maintained.
24
+ - Multiple image widths are now supported, which will be used to create a corresponding srcset.
25
+ - Multiple image formats are now possible, including webp.
26
+ - PictureTag can now generate sizes attributes.
27
+ - Configuration takes a very different format. It should be simpler to write your config than the
28
+ old version, and migrating to it should not be difficult. Instead of creating individual source
29
+ keys, you supply an array of widths you'd like to construct. You can also supply an array (yaml
30
+ sequence) of formats, including 'original'.
31
+ - Only global settings are placed in `_config.yml`. Presets are moved to `_data/picture.yml`.
32
+
33
+ ## Migration
34
+
35
+ ### Liquid Tags
36
+
37
+ Previous tag syntax has been extended, but backwards compatibility (and behaviour of previous
38
+ versions) is maintained.
39
+
40
+ `{% picture img.jpg (implicit attributes) --(argument) (explicit attributes) %}`
41
+
42
+ Implicit attributes are the old way. They are specified after the last source image, and before any
43
+ explicit attributes (if they are included). These attributes are applied to the `<img>` tag, as in
44
+ previous versions.
45
+
46
+ Explicit attributes are the new way, documented in the readme. It is possible to use a mix of both,
47
+ though I'm not sure why you would want to.
48
+
49
+ There is one instance I can think of where you will have to change your tags:
50
+
51
+ - You use art direction with more than one different preset.
52
+ - These presets have source keys of the same name.
53
+ - These source keys have different associated media queries.
54
+
55
+ If all of the above are true, you will either have to pick one media query which works for both, or
56
+ rename one of them and change it everywhere it's used.
57
+
58
+ Another trouble spot will be CSS; your output markup may change, meaning your CSS selectors may stop
59
+ working.
60
+
61
+ Outside of those situations, and provided you have created media_presets to match your old source
62
+ keys, your existing tags should keep working. If they don't, it's a bug. Please report it.
63
+
64
+ ### Configuration
65
+
66
+ The new configuration is described in the readme so I won't document it here, but I will show an old
67
+ config alongside an equivalent new one.
68
+
69
+ Example old configuration:
70
+
71
+ ```yml
72
+ # _config.yml
73
+
74
+ picture:
75
+ source: assets/images/_fullsize
76
+ output: generated
77
+ markup: picture
78
+ presets:
79
+ # Full width pictures
80
+ default:
81
+ ppi: [1, 1.5]
82
+ attr:
83
+ class: blog-full
84
+ itemprop: image
85
+ source_lrg:
86
+ media: "(min-width: 40em)"
87
+ width: 700
88
+ source_med:
89
+ media: "(min-width: 30em)"
90
+ width: 450
91
+ source_default:
92
+ width: 350
93
+ height: 200
94
+ # Half width pictures
95
+ half:
96
+ ppi: [1, 1.5]
97
+ attr:
98
+ data-location: "{{location}}"
99
+ data-active: nil
100
+ source_lrg:
101
+ media: "(min-width: 40em)"
102
+ width: 400
103
+ source_med:
104
+ media: "(min-width: 30em)"
105
+ width: 250
106
+ source_default:
107
+ width: 350
108
+ # Self-set resolution sources. Useful if you don't want a 1:1 image size to dppx ratio.
109
+ gallery:
110
+ source_wide_hi:
111
+ media: "(min-width: 40em) and (min-resolution: 1.5dppx)"
112
+ width: 900
113
+ height: 600
114
+ source_wide:
115
+ media: "(min-width: 40em)"
116
+ width: 600
117
+ height: 400
118
+ source_default:
119
+ width: 250
120
+ height: 250
121
+ ```
122
+
123
+ Equivalent new configuration:
124
+
125
+ ```yml
126
+ # _config.yml
127
+
128
+ picture:
129
+ source: assets/images/_fullsize
130
+ output: generated
131
+ ```
132
+
133
+ ```yml
134
+ # _data/picture.yml
135
+
136
+ # Media presets are named media queries. To maintain compatibility with your tags, you need to
137
+ # create presets of the same name as your old source keys. There is no limit to how many of them you
138
+ # can have, so you're free to create additional new ones with better names to use going forward.
139
+ media_presets:
140
+ source_lrg: '(min-width: 40em)'
141
+ source_med: '(min-width: 30em)'
142
+ source_wide_hi: "(min-width: 40em) and (min-resolution: 1.5dppx)"
143
+ source_wide: "(min-width: 40em)"
144
+
145
+ markup_presets:
146
+ # You can't specify both widths and pixel ratios anymore. Choose one.
147
+ # Full width pictures, width-based srcset
148
+ default:
149
+ markup: picture
150
+ widths: [350, 450, 700]
151
+ attributes:
152
+ picture: 'class="blog-full" itemprop="image"'
153
+
154
+ # Full width pictures, multiplier based srcset
155
+ default-ppi:
156
+ markup: picture
157
+ base_width: 350
158
+ pixel_ratios: [1, 1.5]
159
+ attributes:
160
+ picture: 'class="blog-full" itemprop="image"'
161
+
162
+ # Half width pictures
163
+ half:
164
+ widths: [250, 350, 400]
165
+ attributes:
166
+ picture: 'data-location="{{location}}" data-active="nil"'
167
+
168
+ # Note you can't set heights anymore. You'll have to crop your images either ahead of time, or
169
+ # do it with CSS.
170
+ #
171
+ # You have to use arrays for widths, even if only specifying a single value. There's no reason you
172
+ # can't add more.
173
+ gallery:
174
+ widths: [250]
175
+ media_widths:
176
+ source_wide_hi: [900]
177
+ source_wide: [600]
178
+ ```
data/readme.md ADDED
@@ -0,0 +1,823 @@
1
+ # Jekyll Picture Tag
2
+
3
+ **Easy responsive images for Jekyll.**
4
+
5
+ It's easy to throw an image on a webpage and call it a day. Doing justice to your users by serving it
6
+ efficiently on all screen sizes is tedious and tricky. Tedious, tricky things should be automated.
7
+
8
+ Jekyll Picture Tag is a liquid tag that adds responsive images to your
9
+ [Jekyll](http://jekyllrb.com) static site. It automatically creates resized,
10
+ reformatted source images, is fully configurable, implements sensible defaults,
11
+ and solves both the art direction and resolution switching problems, with a
12
+ little YAML configuration and a simple template tag. It can be configured to
13
+ work with JavaScript libraries such as
14
+ [LazyLoad](https://github.com/verlok/lazyload).
15
+
16
+ ## Why use Jekyll Picture Tag?
17
+
18
+ **Performance:** The fastest sites are static sites. If we're not using responsive images we're
19
+ throwing those performance gains away by serving kilobytes of pixels a user will never see.
20
+
21
+ **Design:** Your desktop image may not work well on mobile, regardless of its resolution. We often
22
+ want to do more than just resize images for different screen sizes.
23
+
24
+ **Developer Sanity:** Image downloading starts before the browser has parsed your CSS and
25
+ JavaScript; this gets them on the page *fast*, but it leads to some ridiculously verbose markup.
26
+ Ultimately, to serve responsive images correctly, we must:
27
+
28
+ - Generate, name, and organize the required images (formats \* resolutions, for each source image)
29
+ - Inform the browser about the image itself-- format, size, URI, and the screen sizes where it
30
+ should be used.
31
+ - Inform the browser how large the space for that image on the page will be (which also probably has associated media
32
+ queries).
33
+
34
+ It's a lot. It's tedious and complicated. Jekyll Picture Tag automates it.
35
+
36
+ ## Features
37
+
38
+ * Automatic generation of resized, converted image files.
39
+ * Automatic generation of complex markup in one of several different formats.
40
+ * No configuration required, extensive configuration available.
41
+ * Auto-select between `<picture>` or lone `<img>` as necessary.
42
+ * Support for both width based and pixel ratio based srcsets.
43
+ * Webp conversion.
44
+ * `sizes` attribute assistance.
45
+ * named media queries so you don't have to remember them.
46
+ * Optional `<noscript>` tag with a basic fallback image, so you can lazy load without excluding your
47
+ javascript-impaired users.
48
+ * Optionally, automatically link to the source image. Or manually link to anywhere else, with just a
49
+ tag parameter!
50
+
51
+ # Required Knowledge
52
+
53
+ Jekyll Picture tag is basically a programmatic implementation of the [MDN Responsive Images
54
+ guide](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).
55
+ If you don't know the difference between resolution switching and art direction, stop now and read it
56
+ in detail. Ideally, play around with a basic HTML file, a few test images, and a few different
57
+ browser widths until you understand it.
58
+
59
+ # Table of Contents
60
+
61
+ * [Installation](#installation)
62
+ * [Usage](#usage)
63
+ * [Configuration](#configuration)
64
+ * [Global](#global-configuration)
65
+ * [Presets](#preset-configuration)
66
+ * [Other notes](#miscellaneous-tidbits)
67
+ * [Contribute](#contribute)
68
+ * [Release History](#release-history)
69
+ * [License](#license)
70
+
71
+ # Quick start / Demo
72
+
73
+ **All configuration is optional.** Here's the simplest possible use case:
74
+
75
+ Add j-p-t to your gemfile:
76
+
77
+ ```ruby
78
+ group :jekyll_plugins do
79
+ gem 'jekyll-picture-tag', git: 'https://github.com/robwierzbowski/jekyll-picture-tag/'
80
+ end
81
+ ```
82
+
83
+ Write this:
84
+
85
+ `{% picture test.jpg %}`
86
+
87
+ Get this:
88
+
89
+ ```html
90
+ <!-- Line breaks added for readability, the actual markup will not have them. -->
91
+ <img
92
+ src="http://localhost:4000/generated/test-800by450-195f7d.jpg"
93
+ srcset="
94
+ http://localhost:4000/generated/test-400by225-195f7d.jpg 400w,
95
+ http://localhost:4000/generated/test-600by338-195f7d.jpg 600w,
96
+ http://localhost:4000/generated/test-800by450-195f7d.jpg 800w,
97
+ http://localhost:4000/generated/test-1000by563-195f7d.jpg 1000w"
98
+ >
99
+ ```
100
+
101
+ **Here's a more complete example:**
102
+
103
+ With this configuration:
104
+
105
+ ```yml
106
+
107
+ # _data/picture.yml
108
+
109
+ media_presets:
110
+ mobile: 'max-width: 600px'
111
+
112
+ markup_presets:
113
+ default:
114
+ widths: [600, 900, 1200]
115
+ formats: [webp, original]
116
+ sizes:
117
+ mobile: 80vw
118
+ size: 500px
119
+
120
+ ```
121
+
122
+ Write this:
123
+
124
+ `{% picture test.jpg mobile: test2.jpg --alt Alternate Text %}`
125
+
126
+ Get this:
127
+
128
+ ```html
129
+
130
+ <!-- Formatted for readability -->
131
+ <picture>
132
+ <source
133
+ sizes="(max-width: 600px) 80vw, 500px"
134
+ media="(max-width: 600px)"
135
+ type="image/webp"
136
+ srcset="http://localhost:4000/generated/test2-600by338-21bb6f.webp 600w,
137
+ http://localhost:4000/generated/test2-900by506-21bb6f.webp 900w,
138
+ http://localhost:4000/generated/test2-1200by675-21bb6f.webp 1200w">
139
+
140
+ <source
141
+ sizes="(max-width: 600px) 80vw, 500px"
142
+ type="image/webp"
143
+ srcset="http://localhost:4000/generated/test-600by338-195f7d.webp 600w,
144
+ http://localhost:4000/generated/test-900by506-195f7d.webp 900w,
145
+ http://localhost:4000/generated/test-1200by675-195f7d.webp 1200w">
146
+
147
+ <source
148
+ sizes="(max-width: 600px) 80vw, 500px"
149
+ media="(max-width: 600px)"
150
+ type="image/jpeg"
151
+ srcset="http://localhost:4000/generated/test2-600by338-21bb6f.jpg 600w,
152
+ http://localhost:4000/generated/test2-900by506-21bb6f.jpg 900w,
153
+ http://localhost:4000/generated/test2-1200by675-21bb6f.jpg 1200w">
154
+
155
+ <source
156
+ sizes="(max-width: 600px) 80vw, 500px"
157
+ type="image/jpeg"
158
+ srcset="http://localhost:4000/generated/test-600by338-195f7d.jpg 600w,
159
+ http://localhost:4000/generated/test-900by506-195f7d.jpg 900w,
160
+ http://localhost:4000/generated/test-1200by675-195f7d.jpg 1200w">
161
+
162
+ <img
163
+ src="http://localhost:4000/generated/test-800by450-195f7d.jpg"
164
+ alt="Alternate Text">
165
+ </picture>
166
+ ```
167
+
168
+ # Installation
169
+
170
+ Add `jekyll-picture-tag` to your Gemfile in the `:jekyll_plugins` group.
171
+ For now I don't have push access to RubyGems, meaning you have to point your gemfile at this git repo.
172
+ If you don't you'll get an old, incompatible version.
173
+
174
+ ```ruby
175
+ group :jekyll_plugins do
176
+ gem 'jekyll-picture-tag', git: 'https://github.com/robwierzbowski/jekyll-picture-tag/'
177
+ end
178
+ ```
179
+
180
+ ### ImageMagick
181
+
182
+ Jekyll Picture Tag ultimately relies on [ImageMagick](https://www.imagemagick.org/script/index.php)
183
+ for image conversions, so it must be installed on your system. There's a very good chance you
184
+ already have it. If you want to build webp images, you will need to install a webp delegate for it
185
+ as well.
186
+
187
+ Verify it's installed by entering the following into a terminal:
188
+
189
+ $ convert --version
190
+
191
+ You should see something like this:
192
+
193
+ chronos@localhost ~ $ convert --version
194
+ Version: ImageMagick 7.0.8-14 Q16 x86_64 2018-10-31 https://imagemagick.org
195
+ Copyright: © 1999-2018 ImageMagick Studio LLC
196
+ License: https://imagemagick.org/script/license.php
197
+ Features: Cipher DPC HDRI OpenMP
198
+ Delegates (built-in): bzlib fontconfig freetype jng jp2 jpeg lcms lzma pangocairo png tiff webp xml zlib
199
+
200
+ Note webp under delegates. This is required if you want to generate webp files.
201
+
202
+ If you get a 'command not found' error, you'll need to install it. Most Linux package managers
203
+ include it, otherwise it can be downloaded [here](https://imagemagick.org/script/download.php)
204
+
205
+ # Usage
206
+
207
+ The tag takes a mix of user input and pointers to configuration settings:
208
+
209
+ `{% picture [preset] (source image) [alternate images] [attributes] %}`
210
+
211
+ Note the tag parser separates arguments by looking for some whitespace followed by `'--'`. If you
212
+ need to set HTML attribute values which begin with `'--'`, either set them first
213
+ (`class="--my-class"`) or using `_data/picture.yml` settings. `class="some-class
214
+ --some-other-class"` will break things.
215
+
216
+ * **Preset**
217
+
218
+ *Format:* `(name of a markup preset described in _data/picture.yml)`
219
+
220
+ *Default:* `default`
221
+
222
+ Optionally specify a markup [preset](#markup-presets) to use, or leave blank for the `default` preset.
223
+
224
+ * **Source Image** (Required)
225
+
226
+ *Format:* `(Image filename, relative to source setting in _config.yml)`
227
+
228
+ The base image that will be resized for your picture sources. Can be a jpeg, png, webp, or gif.
229
+
230
+ * **Alternate images**
231
+
232
+ *Format:* `(media query preset): (image filename, relative to source directory)`
233
+
234
+ *Example:* `tablet: img_cropped.jpg mobile: img_cropped_more.jpg`
235
+
236
+ Optionally specify any number of alternate base images for given [media queries](#media-presets)
237
+ (specified in `_data/picture.yml`). This is one of of picture's strongest features, often referred
238
+ to as the [art direction use case](http://usecases.responsiveimages.org/#art-direction).
239
+
240
+ Give your images in order of ascending specificity (The first image is the most general). They will
241
+ be provided to the browser in reverse order, and it will select the first one with a media query
242
+ that evaluates true.
243
+
244
+ * **Attributes**
245
+
246
+ Optionally specify any number of HTML attributes. These will be added to any attributes you've
247
+ set in a preset. They can take a few different formats:
248
+
249
+ ##### `--link`
250
+
251
+ *Format:* `--link (some url)`
252
+
253
+ *Examples*: `--link https://example.com`, `--link /blog/some_post/`
254
+
255
+ Wrap the image in an anchor tag, with the `href` attribute set to whatever value you give it.
256
+ This will override automatic source image linking, if you have enabled it.
257
+
258
+ **Note**: Don't disable the `nomarkdown` global setting if you would like do this within markdown
259
+ files and you are using Kramdown (Jekyll's default markdown parser.)
260
+
261
+ ##### `--(element)`
262
+
263
+ *Format:* `--(picture|img|source|a|parent|alt) (Whatever HTML attributes you want)`
264
+
265
+ *Example:* `--img class="awesome-fade-in" id="coolio" --a data-awesomeness="11"`
266
+
267
+ Apply attributes to a given HTML element. Your options are:
268
+
269
+ * `picture`
270
+ * `img`
271
+ * `source`
272
+ * `a` (anchor tag)
273
+ * `parent`
274
+ * `alt`
275
+
276
+ `--parent` will be applied to the `<picture>` if present, otherwise the `<img>`; useful when using
277
+ the `auto` output format.
278
+
279
+ `--alt` is a shortcut for `--img alt="..."`
280
+ *Example:* `--alt Here is my alt text!`
281
+
282
+ ##### Old syntax
283
+
284
+ The old syntax is to just dump all attributes at the end:
285
+
286
+ `{% picture example.jpg alt="alt text" class="super-duper" %}`
287
+
288
+ This will continue to work. For backwards compatibility, behavior of previous versions is
289
+ maintained: all attributes specified this way are applied to the img tag.
290
+
291
+ #### Line breaks
292
+ Line breaks and spaces are interchangeable, the following is perfectly acceptable:
293
+
294
+ ```
295
+ {%
296
+ picture my-preset
297
+ img.jpg
298
+ mobile: alt.jpg
299
+ --alt Alt Text
300
+ --picture class="stumpy"
301
+ %}
302
+ ```
303
+ #### Liquid variables
304
+
305
+ You can use liquid variables in a picture tag:
306
+
307
+ `html {% picture {{ post.featured_image }} --alt Our Project %}`
308
+
309
+ # Configuration
310
+
311
+ **All configuration is optional**. If you are happy with the defaults, you don't have to touch a
312
+ single yaml file.
313
+
314
+ ## Global Configuration
315
+
316
+ Global settings are stored under the `picture:` key in `/_config.yml`.
317
+
318
+ **Example config:**
319
+
320
+ ```yml
321
+ picture:
322
+ source: "assets/images/fullsize"
323
+ output: "assets/images/generated"
324
+ ```
325
+
326
+ * **Source Image Directory**
327
+
328
+ *Format:* `source: (directory)`
329
+
330
+ *Example:* `source: images/`
331
+
332
+ *Default:* Jekyll site root.
333
+
334
+ To make writing tags easier you can specify a source directory for your assets. Base images in the
335
+ tag will be relative to the `source` directory, which is relative to the Jekyll site root.
336
+
337
+ For example, if `source` is set to `assets/images/_fullsize`, the tag
338
+ `{% picture enishte/portrait.jpg --alt An unsual picture %}` will look for a file at
339
+ `assets/images/_fullsize/enishte/portrait.jpg`.
340
+
341
+ * **Destination Image Directory**
342
+
343
+ *Format:* `output: (directory)`
344
+
345
+ *Example:* `output: resized_images/`
346
+
347
+ *Default*: `generated/`
348
+
349
+ Jekyll Picture Tag saves resized, reformatted images to the `output` directory in your compiled
350
+ site. The organization of your `source` directory is maintained.
351
+
352
+ This setting is relative to your compiled site, which means `_site` unless you've changed it.
353
+
354
+ * **Suppress Warnings**
355
+
356
+ *Format:* `suppress_warnings: (true|false)`
357
+
358
+ *Example:* `suppress_warnings: true`
359
+
360
+ *Default*: `false`
361
+
362
+ Jekyll Picture Tag will warn you in a few different scenarios, such as when your base image is
363
+ smaller than one of the sizes in your preset. (Note that Jekyll Picture Tag will never resize an
364
+ image to be larger than its source). Set this value to `true`, and these warnings will not be shown.
365
+
366
+ * **Use Relative Urls**
367
+
368
+ *Format:* `relative_url: (true|false)`
369
+
370
+ *Example:* `relative_url: false`
371
+
372
+ *Default*: `true`
373
+
374
+ Whether to use relative (`/generated/test(...).jpg`) or absolute
375
+ (`https://example.com/generated/test(...).jpg`) urls in your src and srcset attributes.
376
+
377
+ * **Use a CDN Url**
378
+
379
+ *Format:* `cdn_url: (url)`
380
+
381
+ *Example:* `cdn_url: https://cdn.example.com`
382
+
383
+ *Default*: none
384
+
385
+ Use for images that are hosted at a different domain or subdomain than the Jekyll site root. Overrides
386
+ `relative_url`. Keep reading, the next option is important.
387
+
388
+ * **CDN build environments**
389
+
390
+ *Format:* `cdn_environments: (array of strings)`
391
+
392
+ *Example:* `cdn_environments: ['production', 'staging']`
393
+
394
+ *Default*: `['production']`
395
+
396
+ It's likely that if you're using a CDN, you may not want to use it in your local development environment. This
397
+ allows you to build a site with local images while in development, and still push to a CDN when you build for
398
+ production by specifying a different [environment](https://jekyllrb.com/docs/configuration/environments/).
399
+
400
+ **Note that the default jekyll environment is `development`**, meaning that if you only set `cdn_url` and run
401
+ `jekyll serve` or `jekyll build`, nothing will change. You'll either need to run `JEKYLL_ENV=production bundle exec
402
+ jekyll build`, or add `development` to this setting.
403
+
404
+ * **Kramdown nomarkdown fix**
405
+
406
+ *Format:* `nomarkdown: (true|false)`
407
+
408
+ *Example:* `nomarkdown: false`
409
+
410
+ *Default*: `true`
411
+
412
+ Whether or not to surround j-p-t's output with a `{::nomarkdown}..{:/nomarkdown}` block when called
413
+ from within a markdown file. This one requires some explanation, but you can probably just leave
414
+ it enabled.
415
+
416
+ Under certain circumstances, Kramdown (Jekyll's default markdown parser) will get confused by HTML
417
+ and will subsequently butcher it. One instance is when you wrap a block level element (such as a
418
+ `<picture>`) within a span level element (such as an anchor tag). This flag fixes that issue.
419
+
420
+ You should disable this if one of the following applies:
421
+ * You have changed the markdown parser to something other than kramdown.
422
+ * You will never wrap your images with links within a markdown file, and it's important that
423
+ your generated markup is pretty.
424
+ * It's causing issues. If you're seeing stray `{::nomarkdown}` or garbled HTML, try disabling
425
+ this and in either case please file a bug report!
426
+
427
+ Kramdown is finicky about when it will or won't listen to the `nomarkdown` option, depending on the
428
+ line breaks before, after, and within the block. The most general solution I've found is to remove
429
+ all line breaks from j-p-t's output, giving the whole shebang on one line. It makes for ugly markup,
430
+ but it's pretty much only ever seen by the browser anyway. If you know a better way to accomplish
431
+ this, I'm all ears!
432
+
433
+ ## Preset Configuration
434
+
435
+ Presets are stored in `_data/picture.yml`, to avoid cluttering `_config.yml`. You will have to
436
+ create this file, and probably the `_data/` directory as well.
437
+
438
+ All settings are optional, moderately sensible defaults have been implemented. A template can be
439
+ found in the [example data file](examples/_data/picture.yml) in the examples directory.
440
+
441
+ **Example settings:**
442
+
443
+ ```yml
444
+
445
+ # _data/picture.yml
446
+
447
+ media_presets:
448
+ wide_desktop: 'min-width: 1801px'
449
+ desktop: 'max-width: 1800px'
450
+ wide_tablet: 'max-width: 1200px'
451
+ tablet: 'max-width: 900px'
452
+ mobile: 'max-width: 600px'
453
+
454
+ markup_presets:
455
+ default:
456
+ formats: [webp, original]
457
+ widths: [200, 400, 800, 1600]
458
+ media_widths:
459
+ mobile: [200, 400, 600]
460
+ tablet: [400, 600, 800]
461
+ size: 800px
462
+ sizes:
463
+ mobile: 100vw
464
+ desktop: 60vw
465
+ attributes:
466
+ picture: 'class="awesome" data-volume="11"'
467
+ img: 'class="some-other-class"'
468
+
469
+ icon:
470
+ base-width: 20
471
+ pixel_ratios: [1, 1.5, 2]
472
+
473
+ lazy:
474
+ markup: data_auto
475
+ formats: [webp, original]
476
+ widths: [200, 400, 600, 800]
477
+ noscript: true
478
+ attributes:
479
+ img: class="lazy"
480
+
481
+ ```
482
+
483
+ #### Media Presets
484
+
485
+ *Format:*
486
+
487
+ ```yml
488
+ media_presets:
489
+ (name): (css media query)
490
+ (name): (css media query)
491
+ (name): (css media query)
492
+ (...)
493
+
494
+ ```
495
+
496
+ *Example:*
497
+
498
+ ```yml
499
+ media_presets:
500
+ desktop: 'min-width: 1200px'
501
+ ```
502
+
503
+ These are named media queries for use in a few different places.
504
+
505
+ Keys are names by which you can refer to the media queries supplied as their respective values.
506
+ These are used for specifying alternate source images in your liquid tag, and for building the
507
+ 'sizes' attribute within your presets. Quotes are required around the media
508
+ queries, because yml gets confused by free colons.
509
+
510
+ #### Markup Presets
511
+
512
+ *Format:*
513
+
514
+ ```yml
515
+ markup_presets:
516
+ (name):
517
+ (option): (setting)
518
+ (option): (setting)
519
+ (option): (setting)
520
+ (...)
521
+ (another name):
522
+ (option): (setting)
523
+ (option): (setting)
524
+ (option): (setting)
525
+ (...)
526
+ ```
527
+
528
+ *Example:*
529
+
530
+ ```yml
531
+ markup_presets:
532
+ default:
533
+ formats: [webp, original]
534
+ widths: [200, 400, 800, 1600]
535
+ link_source: true
536
+ lazy:
537
+ markup: data_auto
538
+ widths: [200, 400, 800, 1600]
539
+ link_source: true
540
+ noscript: true
541
+ ```
542
+
543
+ These are the 'presets' from previous versions, with different structure. Each entry is a
544
+ pre-defined collection of settings to build a given chunk of HTML and its respective images. You
545
+ can select one as the first argument given to the tag:
546
+
547
+ `{% picture my-preset image.jpg %}`
548
+
549
+ The `default` preset will be used if none is specified. A preset name can't contain the `.`, `:`,
550
+ or `/` characters.
551
+
552
+ #### A Note on srcsets, for the bad kids who didn't do the required reading.
553
+
554
+ There are 2 srcset formats, one based on providing widths, the other based on providing multipliers.
555
+
556
+ Width based srcsets look like this: `srcset="img.jpg 600w, img2.jpg 800w, img3.jpg 1000w"`. The
557
+ `(number)w` tells the browser how wide that image file is. Browsers are smart, they know their
558
+ device's pixel ratio, so in combination with the sizes attribute (if given, otherwise it assumes the
559
+ image will be 100vw) they can select the best-fitting image for the space it will fill on the screen.
560
+
561
+ Multiplier based srcsets look like this: `srcset="img.jpg 1x, img2.jpg 1.5x, img3.jpg 3x"`. The
562
+ browser is less smart here; it looks at its own device's pixel ratio, compares it to the given
563
+ multiplier, and picks the closest one. It doesn't consider anything else at all. Multiplier based
564
+ srcsets are best used when the image will always be the same size, on all screen sizes.
565
+
566
+ To use a width based srcset in a preset, specify a `widths` setting (or don't, for the default), and
567
+ optionally the `sizes` and `size` settings.
568
+
569
+ To use a multiplier based srcset, set `pixel_ratios` and `base_width`.
570
+
571
+ * **Markup format**
572
+
573
+ *Format:* `markup: (setting)`
574
+
575
+ *Default*: `auto`
576
+
577
+ Defines what format the generated HTML will take. Here are your options:
578
+
579
+ * `picture`: `<picture>` element surrounding a `<source>` tag for each required srcset, and a
580
+ fallback `<img>`.
581
+ * `img`: output a single `<img>` tag with a `srcset` entry.
582
+ * `auto`: Supply an img tag when you have only one srcset, otherwise supply a picture tag.
583
+ * `data_picture`, `data_img`, `data_auto`: Analogous to their counterparts,
584
+ but instead of `src`, `srcset`, and `sizes`, you get `data-src`, `data-srcset`, and
585
+ `data-sizes`. This allows you to use javascript for things like [lazy loading](https://github.com/verlok/lazyload)
586
+ * `direct_url`: Generates an image and returns only its url. Uses `fallback_` properties (width
587
+ and format)
588
+
589
+ * **Image Formats**
590
+
591
+ *Format:* `format: [format1, format2, (...)]`
592
+
593
+ *Example:* `format: [webp, original]`
594
+
595
+ *Default*: `original`
596
+
597
+ *Supported formats are anything which imagemagick supports, including the
598
+ following:*
599
+ * jpg/jpeg
600
+ * png
601
+ * gif
602
+ * webp
603
+ * jxr
604
+ * jp2
605
+
606
+ Array (yml sequence) of the image formats you'd like to generate, in decreasing order
607
+ of preference. Browsers will render the first format they find and understand, so if you put jpg
608
+ before webp, your webp images will never be used. `original` does what you'd expect. To supply
609
+ webp, you must have an imagemagick webp delegate installed, described [here](#imagemagick).
610
+
611
+ * **widths**
612
+
613
+ *Format:* `widths: [integer, integer, (...)]`
614
+
615
+ *Example:* `widths: [600, 800, 1200]`
616
+
617
+ *Default*: `[400, 600, 800, 1000]`
618
+
619
+ Array of image widths to generate, in pixels. For use when you want a size-based srcset
620
+ (`srcset="img.jpg 800w, img2.jpg 1600w"`).
621
+
622
+ * **media_widths**
623
+
624
+ *Format:*
625
+
626
+ ```yml
627
+ media_widths:
628
+ (media preset name): [integer, integer, (...)]
629
+ ```
630
+
631
+ *Example:*
632
+
633
+ ```yml
634
+ media_widths:
635
+ mobile: [400, 600, 800]
636
+ ```
637
+
638
+ *Default:* Widths setting
639
+
640
+ If you are using art direction, there is no sense in generating desktop-size files for your mobile
641
+ image. You can specify sets of widths to associate with given media queries. If not specified,
642
+ will use `widths` setting.
643
+
644
+ * **Fallback Image**
645
+
646
+ *Format:* `fallback_width: (integer)`
647
+ `fallback_format: (format)`
648
+
649
+ *Example:* `fallback_width: 800`
650
+ `fallback_format: jpg`
651
+
652
+ *Default*: `800` and `original`
653
+
654
+ Properties of the fallback image, format and width.
655
+
656
+ * **Sizes**
657
+
658
+ *Format:*
659
+ ```yml
660
+ sizes:
661
+ (media query): (CSS dimension)
662
+ (media query): (CSS dimension)
663
+ (media query): (CSS dimension)
664
+ (...)
665
+ ```
666
+
667
+ *Example:*
668
+ ```yml
669
+ sizes:
670
+ mobile: 80vw
671
+ tablet: 60vw
672
+ desktop: 900px
673
+ ```
674
+
675
+ Conditional sizes, used to construct the `sizes=` HTML attribute telling the browser how wide your
676
+ image will be (on the screen) when a given media query is true. CSS dimensions can be given in
677
+ `px`, `em`, or `vw`. To be used along with a width based srcset.
678
+
679
+ You don't have to provide a sizes attribute at all. If you don't, the browser will assume the
680
+ image is 100% the width of the viewport.
681
+
682
+ The same sizes attribute is used for every source tag in a given picture tag. This causes some
683
+ redundant markup, specifying sizes for situations when an image will never be rendered, but it
684
+ simplifies configuration greatly.
685
+
686
+ * **Size**
687
+
688
+ *Format:* `size: (CSS Dimension)`
689
+
690
+ *Example:* `size: 80vw`
691
+
692
+ Unconditional image width to give the browser (by way of the html sizes attribute), to be supplied
693
+ either alone or after all conditional sizes.
694
+
695
+ * **Pixel Ratios**
696
+
697
+ *Format:* `pixel_ratios: [number, number, number (...)]`
698
+
699
+ *Example:* `pixel_ratios: [1, 1.5, 2]`
700
+
701
+ Array of images to construct, given in multiples of the base width. If you set this, you must also
702
+ give a `base_width`.
703
+
704
+ Set this when you want a multiplier based srcset (example: `srcset="img.jpg 1x, img2.jpg 2x"`).
705
+
706
+ * **Base Width**
707
+
708
+ *Format:* `base_width: integer`
709
+
710
+ *Example:* `base_width: 100`
711
+
712
+ When using pixel ratios, you must supply a base width. This sets how wide the 1x image should be.
713
+
714
+ * **HTML Attributes**
715
+
716
+ *Format:*
717
+
718
+ ```yml
719
+ attributes:
720
+ (element): '(attributes)'
721
+ (element): '(attributes)'
722
+ (element): '(attributes)'
723
+ (...)
724
+ ```
725
+
726
+ *Example:*
727
+
728
+ ```yml
729
+ attributes:
730
+ img: 'class="soopercool" data-awesomeness="11"'
731
+ picture: 'class="even-cooler"'
732
+ ```
733
+
734
+ HTML attributes you would like to add. The same arguments are available here as in the liquid
735
+ tag; element names, `alt:`, `url:`, and `parent:`. Unescaped double quotes cause problems with
736
+ yml, so it's recommended to surround them with single quotes.
737
+
738
+ * **Noscript**
739
+
740
+ *Format:* `noscript: (true|false)`
741
+
742
+ *Example:* `noscript: true`
743
+
744
+ *Default:* `false`
745
+
746
+ For use with the `data_` output formats. When true, will include a basic `img` fallback within a
747
+ `<noscript>` tag after the standard html. This allows you to use lazy loading or other javascript
748
+ image tools, without breaking all of your images for non-javascript-enabled users.
749
+
750
+ * **Source Image Linking**
751
+
752
+ *Format:* `link_source: (true|false)`
753
+
754
+ *Example:* `link_source: true`
755
+
756
+ *Default:* `false`
757
+
758
+ Surround image with a link to the original source file. Your source image directory must
759
+ be published as part of the compiled site. The same caveats apply as the `--url` flag: don't
760
+ disable `nomarkdown` if you'll be using this from within a kramdown parsed markdown file.
761
+
762
+ # Miscellaneous Tidbits
763
+
764
+ ### Lazy Loading, and other javascript related tomfoolery
765
+
766
+ Use one of the `data_` output formats and something like
767
+ [LazyLoad](https://github.com/verlok/lazyload). The 'lazy' preset in the example config will work.
768
+
769
+ ### PictureFill
770
+
771
+ [Picturefill](http://scottjehl.github.io/picturefill/) version 3 no longer requires special markup.
772
+ Standard outputs should be compatible.
773
+
774
+ ### Managing Generated Images
775
+
776
+ Jekyll Picture Tag creates resized versions of your images when you build the site. It uses a smart
777
+ caching system to speed up site compilation, and re-uses images as much as possible. Filenames
778
+ take the following format:
779
+
780
+ `(original filename without extension)_(width)by(height)_(source hash).(format)`
781
+
782
+ Source hash is the first 5 characters of an md5 checksum of the source image.
783
+
784
+ Try to use a base image that is larger than the largest resized image you need. Jekyll Picture Tag
785
+ will warn you if a base image is too small, and won't upscale images.
786
+
787
+ By specifying a `source` directory that is ignored by Jekyll you can prevent huge base images from
788
+ being copied to the compiled site. For example, `source: assets/images/_fullsize` and `output:
789
+ generated` will result in a compiled site that contains resized images but not the originals. Note
790
+ that this will break source image linking, if you wish to enable it. (Can't link to images that
791
+ aren't public!)
792
+
793
+ The `output` directory is never deleted by Jekyll. You may want to manually clean it every once in a
794
+ while to remove unused images.
795
+
796
+ # Contribute
797
+
798
+ Report bugs and feature proposals in the
799
+ [Github issue tracker](https://github.com/robwierzbowski/jekyll-picture-tag/issues).
800
+
801
+ Pull requests are encouraged. With a few exceptions, this plugin is written to follow the Rubocop
802
+ default settings (except the frozen string literal comment).
803
+
804
+ If you add a new setting, it is helpful to add a default value (look under `lib/defaults/`) and
805
+ relevant documentation to the readme. Don't let that stop you from submitting a pull request,
806
+ though! Just allow modifications and I'll take care of it.
807
+
808
+ # Release History
809
+
810
+ * 1.2.0 Feb 9, 2019: Add nomarkdown fix, noscript option, relative url option, anchor tag wrappers
811
+ * 1.1.0 Jan 22, 2019: Add direct_url markup format, auto-orient images before stripping metadata.
812
+ * 1.0.2 Jan 18, 2019: Fix ruby version specification
813
+ * 1.0.1 Jan 13, 2019: Added ruby version checking for more helpful error messages when running old versions of ruby.
814
+ * **1.0.0** Nov 27, 2018: Rewrite from the ground up. See [migration.md](/migration.md).
815
+ * 0.2.2 Aug 2, 2013: Bugfixes.
816
+ * 0.2.1 Jul 17, 2013: Refactor again, add Liquid parsing.
817
+ * 0.2.0 Jul 14, 2013: Rewrite code base, bring in line with Jekyll Image Tag.
818
+ * 0.1.1 Jul 5, 2013: Quick round of code improvements.
819
+ * 0.1.0 Jul 5, 2013: Initial release.
820
+
821
+ # License
822
+
823
+ [BSD-NEW](http://en.wikipedia.org/wiki/BSD_License)