jekyll_picture_tag 1.9.0 → 1.12.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (96) 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 +4 -2
  6. data/docs/Gemfile.lock +186 -89
  7. data/docs/_config.yml +6 -10
  8. data/docs/devs/contributing/code.md +44 -0
  9. data/docs/devs/contributing/docs.md +13 -0
  10. data/docs/devs/contributing/index.md +15 -0
  11. data/docs/devs/contributing/setup.md +13 -0
  12. data/docs/devs/contributing/testing.md +41 -0
  13. data/docs/devs/index.md +7 -0
  14. data/docs/{releases.md → devs/releases.md} +35 -13
  15. data/docs/index.md +58 -36
  16. data/docs/users/configuration/cdn.md +35 -0
  17. data/docs/users/configuration/directories.md +34 -0
  18. data/docs/users/configuration/disable.md +24 -0
  19. data/docs/users/configuration/fast_build.md +28 -0
  20. data/docs/users/configuration/ignore_missing.md +23 -0
  21. data/docs/users/configuration/index.md +29 -0
  22. data/docs/users/configuration/kramdown_fix.md +20 -0
  23. data/docs/users/configuration/relative_urls.md +15 -0
  24. data/docs/users/configuration/suppress_warnings.md +16 -0
  25. data/docs/users/index.md +7 -0
  26. data/docs/users/installation.md +52 -0
  27. data/docs/users/liquid_tag/argument_reference/alternate_images.md +18 -0
  28. data/docs/users/liquid_tag/argument_reference/attributes.md +42 -0
  29. data/docs/users/liquid_tag/argument_reference/base_image.md +12 -0
  30. data/docs/users/liquid_tag/argument_reference/crop.md +48 -0
  31. data/docs/users/liquid_tag/argument_reference/link.md +16 -0
  32. data/docs/users/liquid_tag/argument_reference/preset.md +17 -0
  33. data/docs/users/liquid_tag/argument_reference/readme.md +9 -0
  34. data/docs/users/liquid_tag/examples.md +81 -0
  35. data/docs/users/liquid_tag/index.md +31 -0
  36. data/docs/users/notes/git_lfs.md +7 -0
  37. data/docs/users/notes/github_pages.md +5 -0
  38. data/docs/users/notes/html_attributes.md +5 -0
  39. data/docs/users/notes/index.md +6 -0
  40. data/docs/users/notes/input_checking.md +6 -0
  41. data/docs/users/notes/kramdown_bug.md +41 -0
  42. data/docs/users/notes/managing_images.md +21 -0
  43. data/docs/{migration.md → users/notes/migration.md} +0 -0
  44. data/docs/users/presets/cropping.md +61 -0
  45. data/docs/users/presets/default.md +23 -0
  46. data/docs/users/presets/examples.md +79 -0
  47. data/docs/users/presets/fallback_image.md +28 -0
  48. data/docs/users/presets/html_attributes.md +26 -0
  49. data/docs/users/presets/image_formats.md +21 -0
  50. data/docs/users/presets/image_quality.md +43 -0
  51. data/docs/users/presets/index.md +101 -0
  52. data/docs/users/presets/link_source.md +16 -0
  53. data/docs/users/presets/markup_formats/fragments.md +48 -0
  54. data/docs/users/presets/markup_formats/javascript_friendly.md +57 -0
  55. data/docs/users/presets/markup_formats/readme.md +43 -0
  56. data/docs/users/presets/markup_formats/standard_html.md +25 -0
  57. data/docs/users/presets/media_queries.md +36 -0
  58. data/docs/users/presets/nomarkdown_override.md +17 -0
  59. data/docs/users/presets/pixel_ratio_srcsets.md +32 -0
  60. data/docs/users/presets/width_height_attributes.md +34 -0
  61. data/docs/users/presets/width_srcsets.md +85 -0
  62. data/jekyll_picture_tag.gemspec +1 -1
  63. data/lib/jekyll_picture_tag.rb +1 -0
  64. data/lib/jekyll_picture_tag/cache.rb +3 -0
  65. data/lib/jekyll_picture_tag/cache/base.rb +59 -0
  66. data/lib/jekyll_picture_tag/cache/generated.rb +20 -0
  67. data/lib/jekyll_picture_tag/cache/source.rb +19 -0
  68. data/lib/jekyll_picture_tag/defaults/presets.yml +2 -0
  69. data/lib/jekyll_picture_tag/generated_image.rb +52 -41
  70. data/lib/jekyll_picture_tag/img_uri.rb +1 -0
  71. data/lib/jekyll_picture_tag/instructions.rb +1 -0
  72. data/lib/jekyll_picture_tag/instructions/arg_splitter.rb +69 -0
  73. data/lib/jekyll_picture_tag/instructions/configuration.rb +1 -1
  74. data/lib/jekyll_picture_tag/instructions/preset.rb +40 -15
  75. data/lib/jekyll_picture_tag/instructions/set.rb +23 -9
  76. data/lib/jekyll_picture_tag/instructions/tag_parser.rb +59 -69
  77. data/lib/jekyll_picture_tag/output_formats/basic.rb +34 -15
  78. data/lib/jekyll_picture_tag/output_formats/img.rb +11 -0
  79. data/lib/jekyll_picture_tag/output_formats/picture.rb +22 -0
  80. data/lib/jekyll_picture_tag/router.rb +9 -0
  81. data/lib/jekyll_picture_tag/source_image.rb +60 -44
  82. data/lib/jekyll_picture_tag/srcsets/basic.rb +29 -7
  83. data/lib/jekyll_picture_tag/utils.rb +18 -0
  84. data/lib/jekyll_picture_tag/version.rb +1 -1
  85. data/readme.md +40 -16
  86. metadata +67 -20
  87. data/docs/_layouts/directory.html +0 -32
  88. data/docs/assets/style.css +0 -31
  89. data/docs/contributing.md +0 -75
  90. data/docs/example_presets.md +0 -116
  91. data/docs/global_configuration.md +0 -173
  92. data/docs/installation.md +0 -30
  93. data/docs/notes.md +0 -91
  94. data/docs/output.md +0 -63
  95. data/docs/presets.md +0 -309
  96. data/docs/usage.md +0 -113
@@ -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
+ ```
@@ -0,0 +1,57 @@
1
+ ---
2
+ sort: 2
3
+ ---
4
+
5
+ # Javascript Friendly
6
+
7
+ These are analogous to their plain HTML counterparts, but instead of `src`,
8
+ `srcset`, and `sizes`, you get `data-src`, `data-srcset`, and `data-sizes`. This
9
+ allows you to use javascript for things like [lazy
10
+ loading](https://github.com/verlok/lazyload).
11
+
12
+ - `data_picture`
13
+
14
+ ```html
15
+ <picture>
16
+ <source data-srcset="..." data-sizes="...">
17
+ <source data-srcset="..." data-sizes="...">
18
+ (...)
19
+ <img data-src="...">
20
+ </picture>
21
+ ```
22
+
23
+ - `data_img`
24
+ ```html
25
+ <img data-srcset="..." data-src="..." data-sizes="...">
26
+ ```
27
+
28
+ - `data_auto` - `data_picture` when needed, otherwise `data_img`.
29
+
30
+ ## Special Options
31
+
32
+ The following preset settings only apply to these output formats.
33
+
34
+ - `noscript`
35
+
36
+ _Format:_ `noscript: true|false`
37
+
38
+ _Default:_ `false`
39
+
40
+ Include a basic `img` fallback within a `<noscript>` tag, giving your
41
+ non-javascript-running users something to look at.
42
+
43
+ ```html
44
+ <img data-srcset="..." data-src="..." data-sizes="...">
45
+ <noscript>
46
+ <img src="..." alt="...">
47
+ </noscript>
48
+ ```
49
+
50
+ - `data_sizes`
51
+
52
+ _Format:_ `data_sizes: true|false`
53
+
54
+ _Default:_ `true`
55
+
56
+ This option sets whether you would like JPT's auto-generated sizes to be returned as a
57
+ `data-sizes` attribute or a normal `sizes` attribute.
@@ -0,0 +1,43 @@
1
+ ---
2
+ sort: 1
3
+ ---
4
+
5
+ # Markup Formats
6
+
7
+ Define what format the generated text will take. Select one by setting
8
+ `markup:` in the relevant [preset]({{ site.baseurl }}/users/presets).
9
+
10
+ _Format:_ `markup: (setting)`
11
+
12
+ _Default_: `auto`
13
+
14
+
15
+ Example:
16
+
17
+ ```yml
18
+ # /_data/picture.yml
19
+
20
+ markup_presets:
21
+ my_preset:
22
+ markup: data_auto
23
+ ```
24
+
25
+ ## Valid options:
26
+
27
+ ### Standard HTML:
28
+ - `auto` - default
29
+ - `picture`
30
+ - `img`
31
+
32
+ ### Javascript Friendly:
33
+ - `data_auto`
34
+ - `data_picture`
35
+ - `data_img`
36
+
37
+ ### Fragments:
38
+ - `direct_url`
39
+ - `naked_srcset`
40
+
41
+ ## Reference:
42
+
43
+ {% include list.liquid %}
@@ -0,0 +1,25 @@
1
+ ---
2
+ sort: 1
3
+ ---
4
+
5
+ # Standard HTML
6
+
7
+ - **`picture`** - `<picture>` element surrounding a `<source>` tag for each required srcset, and a
8
+ fallback `<img>`:
9
+
10
+ ```html
11
+ <picture>
12
+ <source srcset="..." sizes="..." media="..." type="...">
13
+ <source srcset="..." sizes="..." media="..." type="...">
14
+ (...)
15
+ <img src="...">
16
+ </picture
17
+ ```
18
+
19
+ - **`img`** - a single `<img>` tag with a `srcset` entry:
20
+
21
+ ```html
22
+ <img src="..." srcset="..." sizes="..." alt="..." width="..." height="...">
23
+ ```
24
+
25
+ - **`auto`** - Supply an img tag when you have only one srcset, otherwise supply a picture tag.
@@ -0,0 +1,36 @@
1
+ ---
2
+ sort: 1
3
+ ---
4
+
5
+ # Media Queries
6
+
7
+ Jekyll Picture Tag handles media queries by letting you define them by name in
8
+ `_data/picture.yml`, and then referencing that name whenever you need it.
9
+
10
+ _Format:_
11
+
12
+ ```yaml
13
+ # _data/picture.yml
14
+
15
+ media_queries:
16
+ (name): (css media query)
17
+ (name): (css media query)
18
+ (...)
19
+
20
+ ```
21
+
22
+ _Example:_
23
+
24
+ ```yaml
25
+ # _data/picture.yml
26
+
27
+ media_queries:
28
+ mobile: "max-width: 600px"
29
+ tablet: "max-width: 800px"
30
+ ultrawide: "min-width: 1400px"
31
+ ```
32
+
33
+ They are used in a few different places: specifying alternate source images in
34
+ your liquid tag, building the 'sizes' attribute within your presets, and in a
35
+ few configuration settings. Quotes are recommended, because yml gets confused by
36
+ colons.
@@ -0,0 +1,17 @@
1
+ ---
2
+ sort: 11
3
+ ---
4
+
5
+ # Nomarkdown Override
6
+
7
+ _Format:_ `nomarkdown: (true|false)`
8
+
9
+ _Example:_ `nomarkdown: false`
10
+
11
+ _Default:_ `nil`
12
+
13
+ Hard setting for `{::nomarkdown}` tags, overrides both autodetection and the
14
+ global setting in `_config.yml`.
15
+
16
+ See this [note]({{ site.baseurl }}/users/notes/kramdown_bug) for a detailed
17
+ explanation.
@@ -0,0 +1,32 @@
1
+ ---
2
+ sort: 4
3
+ ---
4
+
5
+ # Pixel Ratio Srcsets
6
+
7
+ A Pixel Ratio srcset looks like this:
8
+
9
+ ```html
10
+ srcset="myimage-200.jpg 1.0x, myimage-300.jpg 1.5x, myimage-400.jpg 2.0x"
11
+ ```
12
+
13
+ To use one, set `pixel_ratios` and `base_width`. They are most appropriate for
14
+ thumbnails and icons, where the image will be the same size on all screens, and
15
+ all you need to account for is pixel ratio.
16
+
17
+ ## Base Width
18
+
19
+ _Format:_ `base_width: integer`
20
+
21
+ _Example:_ `base_width: 100`
22
+
23
+ Sets how wide the 1x image should be. Required when using a Pixel Ratio srcset.
24
+
25
+ ## Pixel Ratios
26
+
27
+ _Format:_ `pixel_ratios: [number, number, number (...)]`
28
+
29
+ _Example:_ `pixel_ratios: [1, 1.5, 2]`
30
+
31
+ Array of images to construct, given in multiples of the base width.
32
+
@@ -0,0 +1,34 @@
1
+ ---
2
+ sort: 7
3
+ ---
4
+
5
+ # Width & Height (Anti-Loading-Jank)
6
+
7
+ _Format:_
8
+
9
+ ```yml
10
+ dimension_attributes: true | false
11
+ ```
12
+
13
+ _Example:_
14
+
15
+ ```yml
16
+ dimension_attributes: true
17
+ ```
18
+
19
+ _Default:_ `false`
20
+
21
+ Prevent page reflow (aka jank) while images are loading, by adding `width` and
22
+ `height` attributes to the `<img>` tag in the correct aspect ratio.
23
+
24
+ For an explanation of why and how you want to do this,
25
+ [here](https://youtu.be/4-d_SoCHeWE) is a great explanation.
26
+
27
+ Caveats:
28
+ * You need either `width: auto;` or `height: auto;` set in CSS on the `<img>`
29
+ tags, or they will be stretched.
30
+ * This works on `<img>` tags and `<picture>` tags when offering images in
31
+ multiple widths and formats, but it does not work if you are using art
32
+ direction (in other words, if you have multiple source images). This is
33
+ because these attributes can only be applied to the `<img>` tag, of which
34
+ there is exactly one.
@@ -0,0 +1,85 @@
1
+ ---
2
+ sort: 3
3
+ ---
4
+
5
+ # Width Based Srcsets
6
+
7
+ A width based srcset looks like this:
8
+
9
+ ```html
10
+ srcset="myimage-800.jpg 800w, myimage-1200.jpg 1200w, myimage-2000.jpg 2000w"
11
+ ```
12
+
13
+ It's the default; to use it specify a `widths` setting (or don't, for the
14
+ default set), and optionally the `sizes` and `size` settings.
15
+
16
+ ## Widths
17
+
18
+ _Format:_ `widths: [integer, integer, (...)]`
19
+
20
+ _Example:_ `widths: [600, 800, 1200]`
21
+
22
+ _Default_: `[400, 600, 800, 1000]`
23
+
24
+ Array of image widths to generate, in pixels.
25
+
26
+ ## Media Widths
27
+
28
+ _Format:_
29
+
30
+ ```yml
31
+ media_widths:
32
+ (media_query name): [integer, integer, (...)]
33
+ ```
34
+
35
+ _Example:_
36
+
37
+ ```yml
38
+ media_widths:
39
+ mobile: [400, 600, 800]
40
+ ```
41
+
42
+ _Default:_ `widths` setting
43
+
44
+ If you are using art direction, there is no sense in generating desktop-size
45
+ files for your mobile image. You can specify sets of widths to associate with
46
+ given media queries. If not specified, will use `widths` setting.
47
+
48
+ ## Sizes
49
+
50
+ _Format:_
51
+
52
+ ```yml
53
+ sizes:
54
+ (media preset): (CSS dimension)
55
+ (...)
56
+ ```
57
+
58
+ _Example:_
59
+
60
+ ```yml
61
+ sizes:
62
+ mobile: 80vw
63
+ tablet: 60vw
64
+ desktop: 900px
65
+ ```
66
+
67
+ Conditional sizes, used to construct the `sizes=` HTML attribute telling the
68
+ browser how wide your image will be (on the screen) when a given media query
69
+ is true. CSS dimensions can be given in `px`, `em`, or `vw`. To be used along
70
+ with a width-based srcset.
71
+
72
+ Provide these in order of most restrictive to least restrictive. The browser
73
+ will choose the first one with an applicable media query.
74
+
75
+ You don't have to provide a sizes attribute at all. If you don't, the browser
76
+ will assume the image is 100% the width of the viewport.
77
+
78
+ ## Size
79
+
80
+ _Format:_ `size: (CSS Dimension)`
81
+
82
+ _Example:_ `size: 80vw`
83
+
84
+ Unconditional `sizes` setting, to be supplied either alone or after all
85
+ conditional sizes.
@@ -40,7 +40,7 @@ Gem::Specification.new do |spec|
40
40
  spec.add_dependency 'addressable', '~> 2.6'
41
41
  spec.add_dependency 'mime-types', '~> 3'
42
42
  spec.add_dependency 'mini_magick', '~> 4'
43
- spec.add_dependency 'objective_elements', '~> 1.1.1'
43
+ spec.add_dependency 'objective_elements', '~> 1.1.2'
44
44
 
45
45
  spec.add_runtime_dependency 'jekyll', '< 5'
46
46
  end
@@ -9,6 +9,7 @@ require_relative 'jekyll_picture_tag/srcsets'
9
9
  require_relative 'jekyll_picture_tag/utils'
10
10
  require_relative 'jekyll_picture_tag/img_uri'
11
11
  require_relative 'jekyll_picture_tag/router'
12
+ require_relative 'jekyll_picture_tag/cache'
12
13
 
13
14
  # Title: Jekyll Picture Tag
14
15
  # Authors: Rob Wierzbowski : @robwierzbowski
@@ -0,0 +1,3 @@
1
+ require_relative 'cache/base'
2
+ require_relative 'cache/source'
3
+ require_relative 'cache/generated'
@@ -0,0 +1,59 @@
1
+ require 'json'
2
+
3
+ module PictureTag
4
+ module Cache
5
+ # Basic image information cache functionality
6
+ module Base
7
+ def initialize(base_name)
8
+ @base_name = base_name
9
+ end
10
+
11
+ def [](key)
12
+ data[key]
13
+ end
14
+
15
+ def []=(key, value)
16
+ raise ArgumentError unless template.keys.include? key
17
+
18
+ data[key] = value
19
+ end
20
+
21
+ # Call after updating data.
22
+ def write
23
+ FileUtils.mkdir_p(File.join(base_directory, sub_directory))
24
+
25
+ File.open(filename, 'w+') do |f|
26
+ f.write JSON.generate(data)
27
+ end
28
+ end
29
+
30
+ private
31
+
32
+ def data
33
+ @data ||= if File.exist?(filename)
34
+ JSON.parse(File.read(filename)).transform_keys(&:to_sym)
35
+ else
36
+ template
37
+ end
38
+ end
39
+
40
+ # /home/dave/my_blog/.jekyll-cache/jpt/(cache_dir)/assets/myimage.jpg.json
41
+ # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
42
+ def base_directory
43
+ File.join(PictureTag.site.cache_dir, 'jpt', cache_dir)
44
+ end
45
+
46
+ # /home/dave/my_blog/.jekyll-cache/jpt/(cache_dir)/assets/myimage.jpg.json
47
+ # ^^^^^^^^
48
+ def sub_directory
49
+ File.dirname(@base_name)
50
+ end
51
+
52
+ # /home/dave/my_blog/.jekyll-cache/jpt/somefolder/myimage.jpg.json
53
+ # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
54
+ def filename
55
+ File.join(base_directory, @base_name + '.json')
56
+ end
57
+ end
58
+ end
59
+ end