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,7 @@
1
+ # Git LFS
2
+
3
+ I'm Putting this here because it bit me: If you want to use git LFS, make sure that your hosting
4
+ provider makes those images available during the build process. Netlify, for example, does not.
5
+ You won't find this out until you have gone through the entire migration process and try to deploy
6
+ for the first time.
7
+
@@ -0,0 +1,5 @@
1
+ # Github Pages?
2
+
3
+ Github Pages only allows a very short whitelist of plugins, which sadly does not include JPT. You
4
+ can either run it locally, then commit and push the generated files (rather than the source
5
+ files), or just host it some other way. I recommend Netlify.
@@ -0,0 +1,5 @@
1
+ # HTML attributes
2
+
3
+ Jekyll Picture Tag has comprehensive attribute support for all generated HTML. You can add
4
+ attributes both through the [liquid tag]({{ site.baseurl }}/usage), and the [preset]({{
5
+ site.baseurl }}/presets) (scroll down a bit).
@@ -0,0 +1,6 @@
1
+ ---
2
+ sort: 5
3
+ ---
4
+ # Notes and FAQ
5
+
6
+ {% include list.liquid %}
@@ -0,0 +1,6 @@
1
+ # Getting cryptic build errors?
2
+
3
+ Jekyll Picture Tag is very trusting. It doesn't do much checking of your inputs, and it does not
4
+ fail gracefully if you for example pass it a string when it expects an array. It's on the to-do
5
+ list, but for now if you get cryptic errors then double-check your settings and tag arguments.
6
+
@@ -0,0 +1,41 @@
1
+ # Extra {::nomarkdown} tags or mangled HTML?
2
+
3
+ ## TLDR up front
4
+
5
+ There's a bug involving `<picture>` tags wrapped in `<a>` tags which is not in
6
+ my power to fix.
7
+
8
+ * If you're getting extra `{::nomarkdown}` tags floating around your images, add `nomarkdown:
9
+ false` to either the relevant preset or under `picture` in `_config.yml`.
10
+
11
+ * If you're getting mangled HTML when trying to wrap images with anchor tags, add `nomarkdown:
12
+ true` to the preset.
13
+
14
+ ## What's going on here:
15
+
16
+ Kramdown is Jekyll's default markdown parser. Kramdown gets grumpy when you give it a block level
17
+ element (such as a `<picture>`) surrounded by a span level element (such as an `<a>`), and horribly
18
+ mangles it. The fix for this is to tell Kramdown to chill with a `{::nomarkdown}..{:/nomarkdown}`
19
+ wrapper.
20
+
21
+ Jekyll Picture Tag can be called from many different places: a markdown file, an HTML file, an HTML
22
+ layout for a markdown file, and an HTML include, to name a few. JPT tries its best to determine
23
+ whether its output will be parsed by Kramdown or not, but Jekyll itself doesn't make this
24
+ particularly easy which results in some false positives. (The one I'm most aware of is when a
25
+ markdown file uses an HTML layout which includes a picture tag.)
26
+
27
+ Unfortunately, I don't see an easy way to fix this. We've gotten this far mostly by trial and error.
28
+ I'll continue to work on improving the autodetection, but you can override this behavior explicitly.
29
+
30
+ ## The fix:
31
+
32
+ By default, JPT will add a `{::nomarkdown}` tag if all of the following are true:
33
+ * It thinks it's called from a markdown page
34
+ * The image will be wrapped in an anchor tag (i.e. `link_source_image:` or a `--link` parameter)
35
+ * This behavior hasn't been explicitly disabled.
36
+
37
+ You can disable nomarkdown tags globally by setting `nomarkdown: false` under the `picture:` key in
38
+ `_config.yml`.
39
+
40
+ You can enable or disable markdown tags per preset by adding `nomarkdown: true|false` to them.
41
+ **This setting overrides everything else, both JPT autodetection and the global setting.**
@@ -0,0 +1,21 @@
1
+ # Managing Generated Images
2
+
3
+ Jekyll Picture Tag creates resized versions of your images when you build the
4
+ site. It uses a caching system to speed up site compilation, and re-uses images
5
+ as much as possible. Filenames take the following format:
6
+
7
+ `(original name without extension)-(width)-(id-string).(filetype)`
8
+
9
+ Try to use a base image that is larger than the largest resized image you need.
10
+ Jekyll Picture Tag will warn you if a base image is too small, and won't upscale
11
+ images.
12
+
13
+ By specifying a `source` directory that is ignored by Jekyll you can prevent
14
+ huge base images from being copied to the compiled site. For example, `source:
15
+ assets/images/_fullsize` and `output: generated` will result in a compiled site
16
+ that contains resized images but not the originals. Note that this will break
17
+ source image linking, if you wish to enable it. (Can't link to images that
18
+ aren't public!)
19
+
20
+ The `output` directory is never deleted by Jekyll. You may want to empty it once
21
+ in awhile, to clear out unused images.
@@ -0,0 +1,61 @@
1
+ ---
2
+ sort: 5
3
+ ---
4
+
5
+ # Cropping
6
+
7
+ **Check the warning in the
8
+ [installation guide]({{ site.baseurl }}/users/installation)
9
+ before using this feature.**
10
+
11
+ ## Crop & Media Crop
12
+
13
+ _Format:_
14
+
15
+ ```yaml
16
+ crop: (geometery)
17
+ media_crop:
18
+ (media_preset): (geometry)
19
+ (media_preset): (geometry)
20
+ (...)
21
+ ```
22
+
23
+ _Example:_
24
+
25
+ ```yaml
26
+ crop: 16:9
27
+ media_crop:
28
+ tablet: 3:2
29
+ mobile: 1:1
30
+ ```
31
+
32
+ Crop geometry, given either generally or for specific media presets. The
33
+ hierarchy is: `tag argument` > `media_crop:` > `crop:`.
34
+
35
+ This setting accepts the same arguments as the `crop geometry`
36
+ [tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop).
37
+
38
+ ## Gravity & Media Gravity
39
+
40
+ ```yaml
41
+ gravity: (gravity)
42
+ media_gravity:
43
+ (media_preset): (gravity)
44
+ (media_preset): (gravity)
45
+ (...)
46
+ ```
47
+
48
+ _Example:_
49
+
50
+ ```yaml
51
+ gravity: north
52
+ media_gravity:
53
+ tablet: east
54
+ mobile: southwest
55
+ ```
56
+
57
+ Crop gravity, given either generally or for specific media presets. The hierarchy is:
58
+ `tag argument` > `media_gravity:` > `gravity:` > `center` (default).
59
+
60
+ This setting accepts the same arguments as the `crop gravity`
61
+ [tag parameter]({{ site.baseurl }}/users/liquid_tag/argument_reference/crop).
@@ -0,0 +1,23 @@
1
+ ---
2
+ sort: 13
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
+ ```
@@ -0,0 +1,79 @@
1
+ ---
2
+ sort: 12
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,43 @@
1
+ ---
2
+ sort: 6
3
+ ---
4
+
5
+ # Image Quality
6
+
7
+ ## Quality
8
+
9
+ _Format:_ `quality: 0 <= integer <= 100`
10
+
11
+ _Example:_ `quality: 80`
12
+
13
+ _Default:_ `75`
14
+
15
+ Specify an image compression level for all image formats (where it makes
16
+ sense, anyway).
17
+
18
+ ## Format Quality
19
+
20
+ _Format:_
21
+
22
+ ```yaml
23
+ format_quality:
24
+ (format): 0 <= integer <= 100
25
+ (...)
26
+ ```
27
+
28
+ _Example:_
29
+
30
+ ```yaml
31
+ format_quality:
32
+ jpg: 75
33
+ png: 65
34
+ webp: 55
35
+ ```
36
+
37
+ _Default:_ quality setting
38
+
39
+ Specify quality settings for various image formats, allowing you to take
40
+ advantage of webp's better compression algorithm without trashing your jpg
41
+ images (for example). If you don't give a setting for a particular format
42
+ it'll fall back to the `quality` setting above, and if you don't set _that_
43
+ it'll default to 75.
@@ -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 %}