jekyll_picture_tag 1.10.1 → 1.14.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (103) hide show
  1. checksums.yaml +4 -4
  2. data/.envrc +2 -0
  3. data/.github/workflows/code-checks.yml +43 -0
  4. data/.gitignore +3 -0
  5. data/.rubocop.yml +30 -0
  6. data/.ruby-version +1 -1
  7. data/docs/.envrc +2 -0
  8. data/docs/Gemfile +4 -2
  9. data/docs/Gemfile.lock +14 -12
  10. data/docs/_config.yml +6 -10
  11. data/docs/devs/contributing/code.md +46 -0
  12. data/docs/devs/contributing/docs.md +31 -0
  13. data/docs/devs/contributing/index.md +15 -0
  14. data/docs/devs/contributing/setup.md +33 -0
  15. data/docs/devs/contributing/testing.md +34 -0
  16. data/docs/devs/index.md +7 -0
  17. data/docs/{releases.md → devs/releases.md} +44 -15
  18. data/docs/index.md +42 -26
  19. data/docs/users/configuration/directories.md +34 -0
  20. data/docs/users/configuration/disable.md +24 -0
  21. data/docs/users/configuration/fast_build.md +28 -0
  22. data/docs/users/configuration/ignore_missing.md +23 -0
  23. data/docs/users/configuration/index.md +29 -0
  24. data/docs/users/configuration/kramdown_fix.md +20 -0
  25. data/docs/users/configuration/suppress_warnings.md +16 -0
  26. data/docs/users/configuration/urls.md +69 -0
  27. data/docs/users/index.md +7 -0
  28. data/docs/users/installation.md +52 -0
  29. data/docs/users/liquid_tag/argument_reference/alternate_images.md +18 -0
  30. data/docs/users/liquid_tag/argument_reference/attributes.md +42 -0
  31. data/docs/users/liquid_tag/argument_reference/base_image.md +12 -0
  32. data/docs/users/liquid_tag/argument_reference/crop.md +48 -0
  33. data/docs/users/liquid_tag/argument_reference/link.md +16 -0
  34. data/docs/users/liquid_tag/argument_reference/preset.md +17 -0
  35. data/docs/users/liquid_tag/argument_reference/readme.md +9 -0
  36. data/docs/users/liquid_tag/examples.md +93 -0
  37. data/docs/users/liquid_tag/index.md +31 -0
  38. data/docs/users/notes/git_lfs.md +7 -0
  39. data/docs/users/notes/github_pages.md +5 -0
  40. data/docs/users/notes/html_attributes.md +5 -0
  41. data/docs/users/notes/index.md +6 -0
  42. data/docs/users/notes/input_checking.md +6 -0
  43. data/docs/users/notes/kramdown_bug.md +41 -0
  44. data/docs/users/notes/managing_images.md +21 -0
  45. data/docs/{migration.md → users/notes/migration.md} +0 -0
  46. data/docs/users/presets/cropping.md +61 -0
  47. data/docs/users/presets/default.md +24 -0
  48. data/docs/users/presets/examples.md +79 -0
  49. data/docs/users/presets/fallback_image.md +28 -0
  50. data/docs/users/presets/html_attributes.md +26 -0
  51. data/docs/users/presets/image_formats.md +21 -0
  52. data/docs/users/presets/image_quality.md +105 -0
  53. data/docs/users/presets/index.md +101 -0
  54. data/docs/users/presets/link_source.md +16 -0
  55. data/docs/users/presets/markup_formats/fragments.md +48 -0
  56. data/docs/users/presets/markup_formats/javascript_friendly.md +57 -0
  57. data/docs/users/presets/markup_formats/readme.md +43 -0
  58. data/docs/users/presets/markup_formats/standard_html.md +25 -0
  59. data/docs/users/presets/media_queries.md +36 -0
  60. data/docs/users/presets/nomarkdown_override.md +17 -0
  61. data/docs/users/presets/pixel_ratio_srcsets.md +32 -0
  62. data/docs/users/presets/quality_width_graph.png +0 -0
  63. data/docs/users/presets/strip_metadata.md +13 -0
  64. data/docs/users/presets/width_height_attributes.md +34 -0
  65. data/docs/users/presets/width_srcsets.md +85 -0
  66. data/install_imagemagick.sh +23 -0
  67. data/jekyll_picture_tag.gemspec +10 -6
  68. data/lib/jekyll_picture_tag.rb +5 -5
  69. data/lib/jekyll_picture_tag/cache.rb +3 -0
  70. data/lib/jekyll_picture_tag/cache/base.rb +61 -0
  71. data/lib/jekyll_picture_tag/cache/generated.rb +20 -0
  72. data/lib/jekyll_picture_tag/cache/source.rb +19 -0
  73. data/lib/jekyll_picture_tag/defaults/global.yml +2 -0
  74. data/lib/jekyll_picture_tag/defaults/presets.yml +2 -0
  75. data/lib/jekyll_picture_tag/images.rb +3 -0
  76. data/lib/jekyll_picture_tag/images/generated_image.rb +130 -0
  77. data/lib/jekyll_picture_tag/{img_uri.rb → images/img_uri.rb} +4 -1
  78. data/lib/jekyll_picture_tag/images/source_image.rb +103 -0
  79. data/lib/jekyll_picture_tag/instructions/arg_splitter.rb +3 -2
  80. data/lib/jekyll_picture_tag/instructions/preset.rb +24 -4
  81. data/lib/jekyll_picture_tag/instructions/set.rb +5 -1
  82. data/lib/jekyll_picture_tag/output_formats/basic.rb +16 -14
  83. data/lib/jekyll_picture_tag/output_formats/img.rb +11 -0
  84. data/lib/jekyll_picture_tag/output_formats/picture.rb +22 -0
  85. data/lib/jekyll_picture_tag/router.rb +3 -2
  86. data/lib/jekyll_picture_tag/srcsets/basic.rb +10 -1
  87. data/lib/jekyll_picture_tag/utils.rb +14 -0
  88. data/lib/jekyll_picture_tag/version.rb +1 -1
  89. data/readme.md +13 -10
  90. metadata +139 -46
  91. data/.travis.yml +0 -8
  92. data/docs/_layouts/directory.html +0 -32
  93. data/docs/assets/style.css +0 -31
  94. data/docs/contributing.md +0 -109
  95. data/docs/example_presets.md +0 -116
  96. data/docs/global_configuration.md +0 -173
  97. data/docs/installation.md +0 -45
  98. data/docs/notes.md +0 -91
  99. data/docs/output.md +0 -63
  100. data/docs/presets.md +0 -361
  101. data/docs/usage.md +0 -143
  102. data/lib/jekyll_picture_tag/generated_image.rb +0 -161
  103. data/lib/jekyll_picture_tag/source_image.rb +0 -87
@@ -0,0 +1,24 @@
1
+ ---
2
+ sort: 14
3
+ ---
4
+
5
+ # Default preset
6
+
7
+ Here are the default preset settings:
8
+
9
+ ```yml
10
+ presets:
11
+ default:
12
+ markup: auto
13
+ formats: [original]
14
+ widths: [400, 600, 800, 1000]
15
+ fallback_width: 800
16
+ fallback_format: original
17
+ noscript: false
18
+ link_source: false
19
+ quality: 75
20
+ data_sizes: true
21
+ gravity: center
22
+ dimension_attributes: false
23
+ strip_metadata: true
24
+ ```
@@ -0,0 +1,79 @@
1
+ ---
2
+ sort: 13
3
+ ---
4
+ # Example _data/picture.yml
5
+
6
+ These are example settings- I mostly made them up off the top of my head. You
7
+ probably don't want to just copy-paste them.
8
+
9
+ ```yaml
10
+ # _data/picture.yml
11
+
12
+ media_queries:
13
+ wide_desktop: 'min-width: 1801px'
14
+ desktop: 'max-width: 1800px'
15
+ wide_tablet: 'max-width: 1200px'
16
+ tablet: 'max-width: 900px'
17
+ mobile: 'max-width: 600px'
18
+
19
+ presets:
20
+ default:
21
+ markup: auto
22
+ link_source: true # wrap images in a link to the original source image.
23
+ dimension_attributes: true # Page reflow begone!
24
+
25
+ formats: [webp, original] # Must be an array, and order matters.
26
+
27
+ widths: [200, 400, 800, 1600] # Must be an array.
28
+ media_widths: # Because a cell phone doesn't want 1600 pixels.
29
+ mobile: [200, 400, 600]
30
+ tablet: [400, 600, 800]
31
+
32
+ sizes:
33
+ mobile: 100vw
34
+ tablet: 80vw
35
+ size: 800px
36
+
37
+ fallback_width: 800
38
+ fallback_format: original
39
+
40
+ attributes:
41
+ parent: 'data-downloadable="true"'
42
+ picture: 'class="awesome" data-volume="11"'
43
+ img: 'class="some-other-class"'
44
+ a: 'class="image-link"'
45
+
46
+ # This is an example of how you would create a 'multiplier' based srcset;
47
+ # useful when an image will always be the same size on all screens (icons,
48
+ # graphics, thumbnails, etc), but you'd like to supply higher resolution
49
+ # images to devices with higher pixel ratios.
50
+ icon:
51
+ base_width: 20 # How wide the 1x image should be.
52
+ pixel_ratios: [1, 1.5, 2]
53
+ fallback_width: 20
54
+ attributes:
55
+ img: 'class="icon"'
56
+
57
+ # Here's an example of how you'd configure jekyll-picture-tag to work with
58
+ # something like lazyload: https://github.com/verlok/lazyload
59
+ lazy:
60
+ markup: data_auto
61
+ formats: [webp, original]
62
+ widths: [200, 400, 600, 800]
63
+ noscript: true # add a fallback image inside a <noscript> tag.
64
+ attributes:
65
+ img: class="lazy"
66
+
67
+ # This is an example of how you'd get generated image and a URL, and nothing
68
+ # else.
69
+ direct:
70
+ markup: direct_url
71
+ fallback_format: webp
72
+ fallback_width: 600
73
+
74
+ # Here's a naked srcset. Doesn't even give you the surrounding quotes.
75
+ srcset:
76
+ markup: naked_srcset
77
+ formats: [webp] # must be an array, even if it only has one item
78
+
79
+ ```
@@ -0,0 +1,28 @@
1
+ ---
2
+ sort: 9
3
+ ---
4
+
5
+ # Fallback Image
6
+
7
+ A valid `<picture>` tag must contain an `<img>` tag, and a valid `<img>` tag
8
+ must contain a `src` with a single image. We call this the 'fallback' image.
9
+
10
+ ## Fallback Width
11
+
12
+ _Format:_ `fallback_width: (integer)`
13
+
14
+ _Example:_ `fallback_width: 800`
15
+
16
+ _Default_: `800`
17
+
18
+ Width of the fallback image.
19
+
20
+ ## Fallback Format
21
+
22
+ _Format:_ `fallback_format: (format)`
23
+
24
+ _Example:_ `fallback_format: jpg`
25
+
26
+ _Default_: `original`
27
+
28
+ Format of the fallback image.
@@ -0,0 +1,26 @@
1
+ ---
2
+ sort: 8
3
+ ---
4
+
5
+ # Arbitrary HTML Attributes
6
+
7
+ _Format:_
8
+
9
+ ```yaml
10
+ attributes:
11
+ (element): '(attributes)'
12
+ (...)
13
+ ```
14
+
15
+ _Example:_
16
+
17
+ ```yaml
18
+ attributes:
19
+ img: 'class="soopercool" data-awesomeness="11"'
20
+ picture: 'class="even-cooler"'
21
+ ```
22
+
23
+ HTML attributes you would like to add. The same arguments are available here as
24
+ in the liquid tag: HTML element names, `alt:`, `link:`, and `parent:`. Unescaped
25
+ double quotes cause problems with yml, so it's recommended to surround them with
26
+ single quotes.
@@ -0,0 +1,21 @@
1
+ ---
2
+ sort: 2
3
+ ---
4
+
5
+ # Image Formats
6
+
7
+ _Format:_ `format: [format1, format2, (...)]`
8
+
9
+ _Example:_ `format: [webp, original]`
10
+
11
+ _Default_: `original`
12
+
13
+ Array (yml sequence) of the image formats you'd like to generate, in decreasing
14
+ order of preference. Browsers will render the first format they find and
15
+ understand, so **If you put jpg before webp, your webp images will never be
16
+ used**. `original` does what you'd expect. To supply webp, you must have an
17
+ imagemagick webp delegate installed. (Most package managers just name it 'webp')
18
+
19
+ _Supported formats are anything which imagemagick supports, and has an installed
20
+ delegate. See a list by running `$ convert --version`_.
21
+
@@ -0,0 +1,105 @@
1
+ ---
2
+ sort: 6
3
+ ---
4
+
5
+ # Image Quality
6
+
7
+ Image quality can be as simple as a constant for all images, or can be varied based on image width
8
+ and output format.
9
+
10
+ ```note
11
+ For lossless webp images, set quality to 100.
12
+ ```
13
+
14
+
15
+ ## Quality
16
+
17
+ ### Constant
18
+
19
+ _Format:_ `quality: 0 <= integer <= 100`
20
+
21
+ _Example:_ `quality: 80`
22
+
23
+ _Default:_ `75`
24
+
25
+ Specify an image compression level for all widths, all image formats.
26
+
27
+ ### Variable
28
+
29
+ _Format:_
30
+
31
+ ```yaml
32
+ quality:
33
+ (image width): (quality setting)
34
+ (image width): (quality setting)
35
+ ```
36
+
37
+ _Example:_
38
+
39
+ ```yaml
40
+ quality:
41
+ 1000: 65
42
+ 300: 100
43
+ ```
44
+
45
+ Set a variable image quality, based on image width. Provide exactly 2 image widths and associated
46
+ quality settings. Quality will be calculated as follows:
47
+
48
+ * For images smaller than the lowest image width, the setting for the lowest width is used.
49
+ * For images larger than the highest image width, the setting for the highest width is used.
50
+ * For images in between the 2, the quality setting will be linearly interpolated to some value in
51
+ between.
52
+
53
+ ![](quality_width_graph.png)
54
+
55
+ Using this setting, you can get away with more compression on high pixel density screens without
56
+ sacrificing image quality for low-density screens. Taking the example settings above:
57
+
58
+ * A 1500px image will use a quality of 65.
59
+ * A 200px image will use a quality of 100.
60
+ * A 500px image will use a quality of 90.
61
+
62
+
63
+ ## Format Quality
64
+
65
+ _Format:_
66
+
67
+ ```yaml
68
+ format_quality:
69
+ (format): 0 <= integer <= 100
70
+ (...)
71
+ ```
72
+
73
+ ```yaml
74
+ format_quality:
75
+ (format):
76
+ (image width): (quality setting)
77
+ (image width): (quality setting)
78
+ ```
79
+
80
+
81
+ _Example:_
82
+
83
+ ```yaml
84
+ format_quality:
85
+ jpg: 75
86
+ png: 65
87
+ webp: 55
88
+ ```
89
+
90
+ ```yaml
91
+ format_quality:
92
+ jpg:
93
+ 1000: 65
94
+ 300: 100
95
+ (...)
96
+ ```
97
+
98
+ _Default:_ quality setting
99
+
100
+ Specify quality settings for various image formats, allowing you to take advantage of webp's
101
+ better compression algorithm without trashing your jpg images (for example). If you don't give a
102
+ setting for a particular format it'll fall back to the `quality` setting above, and if you don't
103
+ set _that_ it'll default to 75.
104
+
105
+ Note that this setting can accept the same variable quality setting format as the basic `quality` setting.
@@ -0,0 +1,101 @@
1
+ ---
2
+ sort: 3
3
+ ---
4
+
5
+ # Writing Presets
6
+
7
+ Presets are named collections of settings that determine basically everything
8
+ about JPT's output. Think of them like frameworks that you can plug images into;
9
+ the preset determines what markup, what image sizes, and what image formats to
10
+ create, while the picture tag determines which image(s) will be used. They are
11
+ stored in `_data/picture.yml`. You will have to create this file, and probably
12
+ the `_data/` directory as well.
13
+
14
+ Any settings which are specific to particular markup formats are documented on
15
+ their respective markup format page.
16
+
17
+ ## Required Knowledge
18
+
19
+ If you don't know the difference between resolution switching and art direction,
20
+ stop now and learn responsive images. Ideally, write a few yourself until you
21
+ understand them.
22
+
23
+ Here are some good guides:
24
+
25
+ * [MDN Responsive Images guide](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)
26
+ * [CSS Tricks Guide to Reponsive Images](https://css-tricks.com/a-guide-to-the-responsive-images-syntax-in-html/)
27
+ * [Cloud 4 - Responsive Images 101](https://cloudfour.com/thinks/responsive-images-101-definitions/)
28
+
29
+ ## Media Queries
30
+
31
+ **Media queries are not presets**, but they are used when writing them. They are
32
+ defined in `_data/picture.yml` alongside presets. More information
33
+ [here](media_queries).
34
+
35
+ ## Presets
36
+
37
+ _General Format:_
38
+
39
+ ```yaml
40
+ # _data/picture.yml
41
+
42
+ presets:
43
+ (name):
44
+ (option): (setting)
45
+ (option): (setting)
46
+ (...)
47
+ (...)
48
+ ```
49
+
50
+ _Example:_
51
+
52
+ ```yaml
53
+ # _data/picture.yml
54
+
55
+ presets:
56
+ default:
57
+ formats: [webp, original]
58
+ widths: [200, 400, 800, 1600]
59
+ link_source: true
60
+
61
+ lazy:
62
+ markup: data_auto
63
+ widths: [200, 400, 800, 1600]
64
+ link_source: true
65
+ noscript: true
66
+ ```
67
+
68
+ Each entry is a pre-defined collection of settings to build a given chunk of
69
+ text (usually HTML) and its respective images. You can select one as the first
70
+ argument given to the tag:
71
+
72
+ {% raw %}
73
+ `{% picture my-preset image.jpg %}`
74
+ {% endraw %}
75
+
76
+ The `default` preset will be used if none is specified. A preset name can't
77
+ contain a `.` (period). You can create as many as you like.
78
+
79
+ ```note
80
+ `media_queries` and `presets` used to be called `media_presets` and
81
+ `markup_presets`. These names were causing some confusion, so they were
82
+ changed. The old names will continue working for the forseeable future, at least
83
+ until the next major version update.
84
+ ```
85
+
86
+ ## Markup Format
87
+
88
+ The high level, overall markup format is controlled with the `markup:` setting,
89
+ documented [here](markup_formats).
90
+
91
+ ## Choosing a Srcset format
92
+
93
+ For images that are different sizes on different screens (most images), use a
94
+ [width-based srcset](width_srcsets) (which is the default).
95
+
96
+ Use a [pixel-ratio srcset](pixel_ratio_srcsets) when the image will always be
97
+ the same size, regardless of screen width (thumbnails and icons).
98
+
99
+ ## Settings reference
100
+
101
+ {% include list.liquid %}
@@ -0,0 +1,16 @@
1
+ ---
2
+ sort: 10
3
+ ---
4
+
5
+ # Source Image Link
6
+
7
+ _Format:_ `link_source: (true|false)`
8
+
9
+ _Example:_ `link_source: true`
10
+
11
+ _Default:_ `false`
12
+
13
+ Surround image with a link to the original source file. Your source image
14
+ directory must be published as part of the compiled site. If you run into weird
15
+ issues with the output, see the [notes]({{ site.baseurl }}/notes).
16
+
@@ -0,0 +1,48 @@
1
+ ---
2
+ sort: 3
3
+ ---
4
+
5
+ # Fragments
6
+
7
+ The following are not complete markup; they're building blocks that you can use
8
+ to make things outside the scope of JPT.
9
+
10
+ - `direct_url` Generates an image and returns only its url. Uses
11
+ `fallback_width` and `fallback_format`.
12
+
13
+ ```yml
14
+ # _data/picture.yml
15
+
16
+ markup_presets:
17
+ direct:
18
+ markup: direct_url
19
+ fallback_width: 800
20
+ fallback_format: webp
21
+ ```
22
+
23
+ ```
24
+ {% raw %}
25
+ {% picture direct myimage.jpg %} --> /generated/myimage-800-abcd12345.webp
26
+ {% endraw %}
27
+ ```
28
+
29
+ - `naked_srcset`: Builds a srcset and nothing else (not even the surrounding quotes). Note that the
30
+ (image) `format` setting must still be an array, even if you only give it one
31
+ value. (This is on the list of things to improve.)
32
+
33
+ ```yml
34
+ # _data/picture.yml
35
+
36
+ markup_presets:
37
+ only_srcset:
38
+ markup: naked_srcset
39
+ widths: [800, 1200, 1600]
40
+ format: [webp]
41
+ ```
42
+
43
+ ```
44
+ {% raw %}
45
+ {% picture only_srcset myimage.jpg %} -->
46
+ /generated/myimage-800-abcd12345.webp 800w, /generated/myimage-1200-abcd12345.webp 1200w, (...)
47
+ {% endraw %}
48
+ ```