jekyll_picture_tag 1.10.0 → 1.13.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 +79 -0
  3. data/docs/Gemfile +4 -2
  4. data/docs/Gemfile.lock +14 -12
  5. data/docs/_config.yml +6 -10
  6. data/docs/devs/contributing/code.md +44 -0
  7. data/docs/devs/contributing/docs.md +13 -0
  8. data/docs/devs/contributing/index.md +15 -0
  9. data/docs/devs/contributing/setup.md +13 -0
  10. data/docs/devs/contributing/testing.md +41 -0
  11. data/docs/devs/index.md +7 -0
  12. data/docs/{releases.md → devs/releases.md} +37 -13
  13. data/docs/index.md +42 -26
  14. data/docs/users/configuration/cdn.md +35 -0
  15. data/docs/users/configuration/directories.md +34 -0
  16. data/docs/users/configuration/disable.md +24 -0
  17. data/docs/users/configuration/fast_build.md +28 -0
  18. data/docs/users/configuration/ignore_missing.md +23 -0
  19. data/docs/users/configuration/index.md +29 -0
  20. data/docs/users/configuration/kramdown_fix.md +20 -0
  21. data/docs/users/configuration/relative_urls.md +15 -0
  22. data/docs/users/configuration/suppress_warnings.md +16 -0
  23. data/docs/users/index.md +7 -0
  24. data/docs/users/installation.md +52 -0
  25. data/docs/users/liquid_tag/argument_reference/alternate_images.md +18 -0
  26. data/docs/users/liquid_tag/argument_reference/attributes.md +42 -0
  27. data/docs/users/liquid_tag/argument_reference/base_image.md +12 -0
  28. data/docs/users/liquid_tag/argument_reference/crop.md +48 -0
  29. data/docs/users/liquid_tag/argument_reference/link.md +16 -0
  30. data/docs/users/liquid_tag/argument_reference/preset.md +17 -0
  31. data/docs/users/liquid_tag/argument_reference/readme.md +9 -0
  32. data/docs/users/liquid_tag/examples.md +93 -0
  33. data/docs/users/liquid_tag/index.md +31 -0
  34. data/docs/users/notes/git_lfs.md +7 -0
  35. data/docs/users/notes/github_pages.md +5 -0
  36. data/docs/users/notes/html_attributes.md +5 -0
  37. data/docs/users/notes/index.md +6 -0
  38. data/docs/users/notes/input_checking.md +6 -0
  39. data/docs/users/notes/kramdown_bug.md +41 -0
  40. data/docs/users/notes/managing_images.md +21 -0
  41. data/docs/{migration.md → users/notes/migration.md} +0 -0
  42. data/docs/users/presets/cropping.md +61 -0
  43. data/docs/users/presets/default.md +23 -0
  44. data/docs/users/presets/examples.md +79 -0
  45. data/docs/users/presets/fallback_image.md +28 -0
  46. data/docs/users/presets/html_attributes.md +26 -0
  47. data/docs/users/presets/image_formats.md +21 -0
  48. data/docs/users/presets/image_quality.md +105 -0
  49. data/docs/users/presets/index.md +101 -0
  50. data/docs/users/presets/link_source.md +16 -0
  51. data/docs/users/presets/markup_formats/fragments.md +48 -0
  52. data/docs/users/presets/markup_formats/javascript_friendly.md +57 -0
  53. data/docs/users/presets/markup_formats/readme.md +43 -0
  54. data/docs/users/presets/markup_formats/standard_html.md +25 -0
  55. data/docs/users/presets/media_queries.md +36 -0
  56. data/docs/users/presets/nomarkdown_override.md +17 -0
  57. data/docs/users/presets/pixel_ratio_srcsets.md +32 -0
  58. data/docs/users/presets/quality_width_graph.png +0 -0
  59. data/docs/users/presets/width_height_attributes.md +34 -0
  60. data/docs/users/presets/width_srcsets.md +85 -0
  61. data/jekyll_picture_tag.gemspec +4 -5
  62. data/lib/jekyll_picture_tag.rb +3 -4
  63. data/lib/jekyll_picture_tag/cache.rb +3 -0
  64. data/lib/jekyll_picture_tag/cache/base.rb +59 -0
  65. data/lib/jekyll_picture_tag/cache/generated.rb +20 -0
  66. data/lib/jekyll_picture_tag/cache/source.rb +19 -0
  67. data/lib/jekyll_picture_tag/defaults/presets.yml +1 -0
  68. data/lib/jekyll_picture_tag/images.rb +3 -0
  69. data/lib/jekyll_picture_tag/images/generated_image.rb +127 -0
  70. data/lib/jekyll_picture_tag/{img_uri.rb → images/img_uri.rb} +1 -0
  71. data/lib/jekyll_picture_tag/images/source_image.rb +103 -0
  72. data/lib/jekyll_picture_tag/instructions/arg_splitter.rb +3 -2
  73. data/lib/jekyll_picture_tag/instructions/configuration.rb +1 -1
  74. data/lib/jekyll_picture_tag/instructions/preset.rb +24 -4
  75. data/lib/jekyll_picture_tag/instructions/set.rb +5 -1
  76. data/lib/jekyll_picture_tag/output_formats/basic.rb +16 -14
  77. data/lib/jekyll_picture_tag/output_formats/img.rb +11 -0
  78. data/lib/jekyll_picture_tag/output_formats/picture.rb +22 -0
  79. data/lib/jekyll_picture_tag/router.rb +3 -2
  80. data/lib/jekyll_picture_tag/srcsets/basic.rb +10 -1
  81. data/lib/jekyll_picture_tag/utils.rb +14 -0
  82. data/lib/jekyll_picture_tag/version.rb +1 -1
  83. data/readme.md +9 -7
  84. metadata +78 -45
  85. data/docs/_layouts/directory.html +0 -32
  86. data/docs/assets/style.css +0 -31
  87. data/docs/contributing.md +0 -109
  88. data/docs/example_presets.md +0 -116
  89. data/docs/global_configuration.md +0 -173
  90. data/docs/installation.md +0 -45
  91. data/docs/notes.md +0 -91
  92. data/docs/output.md +0 -63
  93. data/docs/presets.md +0 -361
  94. data/docs/usage.md +0 -143
  95. data/lib/jekyll_picture_tag/generated_image.rb +0 -161
  96. data/lib/jekyll_picture_tag/source_image.rb +0 -87
@@ -1,12 +1,15 @@
1
1
  ---
2
- id: quickstart
3
2
  ---
4
3
 
5
- # Quick start / Demo
4
+ # Jekyll Picture Tag
5
+
6
+ Responsive Images, Done Correctly.
7
+
8
+ ## Quick start / Demo
6
9
 
7
10
  **All configuration is optional.** Here's the simplest possible use case:
8
11
 
9
- 1. [Install]({{ site.baseurl }}/installation)
12
+ 1. [Install]({{ site.baseurl }}/users/installation)
10
13
 
11
14
  2. Write this: {% raw %} `{% picture test.jpg %}` {% endraw %}
12
15
 
@@ -31,24 +34,31 @@ id: quickstart
31
34
  Create `_data/picture.yml`, add the following:
32
35
 
33
36
  ```yml
34
- markup_presets:
37
+ presets:
35
38
  default:
36
39
  formats: [webp, original]
37
40
  ```
38
41
 
42
+ **Note:** Order matters! `[webp, jpg]` will offer webp-images first. The
43
+ browser will pick the *first* format it can work with. So if the order is
44
+ reversed `[jpg, webp]` it will use the jpg image before the webp.
39
45
 
40
46
  ### Here's a more complete demonstration:
41
47
 
42
- [Presets]({{ site.baseurl }}/presets) are named collections of settings, and come in 2 kinds: Media
43
- Presets are named CSS media queries, and Markup Presets determine the output text and images. You
44
- choose one with the second [tag parameter]({{ site.baseurl }}/usage), or omit for the `default` (as
45
- in these examples). They are located in `_data/picture.yml`. Here's an example:
48
+ [Presets]({{ site.baseurl }}/users/presets) are named collections of settings.
49
+ You choose one with the second [tag
50
+ parameter]({{site.baseurl}}/users/liquid_tag), or omit for the `default` (as in
51
+ these examples). They are located in `_data/picture.yml`. Alongside `presets`,
52
+ we also set named `media_queries` for easy reference. Here's an example:
53
+
46
54
 
47
55
  ```yml
48
- media_presets:
56
+ # _data/picture.yml
57
+
58
+ media_queries:
49
59
  mobile: 'max-width: 600px'
50
60
 
51
- markup_presets:
61
+ presets:
52
62
  default:
53
63
  widths: [600, 900, 1200]
54
64
  formats: [webp, original]
@@ -57,9 +67,9 @@ markup_presets:
57
67
  size: 500px
58
68
  ```
59
69
 
60
- Imagemagick can easily crop images to an aspect ratio, though you should **read the whole
61
- installation guide before using this feature**. With the above preset, if you write this:
62
-
70
+ Imagemagick can easily crop images to an aspect ratio, though you should **read
71
+ the whole installation guide before using this feature**. With the above preset,
72
+ if you write this:
63
73
 
64
74
  {% raw %}
65
75
  `{% picture test.jpg 3:2 mobile: test2.jpg 1:1 --alt Alternate Text %}`
@@ -72,43 +82,49 @@ You'll get something like this:
72
82
 
73
83
  <picture>
74
84
  <source
75
- sizes="(max-width: 600px) 80vw, 600px"
85
+ type="image/webp"
76
86
  media="(max-width: 600px)"
87
+ sizes="(max-width: 600px) 80vw, 600px"
77
88
  srcset="
78
89
  /generated/test2-600-21bb6fGUW.webp 600w,
79
90
  /generated/test2-900-21bb6fGUW.webp 900w,
80
91
  /generated/test2-1200-21bb6fGUW.webp 1200w
81
- "
82
- type="image/webp">
92
+ ">
83
93
  <source
94
+ type="image/webp"
84
95
  sizes="(max-width: 600px) 80vw, 600px"
85
96
  srcset="
86
97
  /generated/test-600-195f7d192.webp 600w,
87
98
  /generated/test-900-195f7d192.webp 900w,
88
99
  /generated/test-1200-195f7d192.webp 1200w
89
- "
90
- type="image/webp">
100
+ ">
91
101
  <source
92
- sizes="(max-width: 600px) 80vw, 600px"
102
+ type="image/jpeg"
93
103
  media="(max-width: 600px)"
104
+ sizes="(max-width: 600px) 80vw, 600px"
94
105
  srcset="
95
106
  /generated/test2-600-21bb6fGUW.jpg 600w,
96
107
  /generated/test2-900-21bb6fGUW.jpg 900w,
97
108
  /generated/test2-1200-21bb6fGUW.jpg 1200w
98
- "
99
- type="image/jpeg">
109
+ ">
100
110
  <source
111
+ type="image/jpeg"
101
112
  sizes="(max-width: 600px) 80vw, 600px"
102
113
  srcset="
103
114
  /generated/test-600-195f7d192.jpg 600w,
104
115
  /generated/test-900-195f7d192.jpg 900w,
105
116
  /generated/test-1200-195f7d192.jpg 1200w
106
- "
107
- type="image/jpeg">
117
+ ">
108
118
  <img src="/generated/test-800-195f7dGUW.jpg" alt="Alternate Text">
109
119
  </picture>
110
120
  ```
111
121
 
112
- In other words, you have the art direction, format switching, and resolution switching problems
113
- *solved*, with a one-liner and a nicely readable config file that is 1/3 as long as the output
114
- markup. Lighthouse is happy, and you don't even need to crop things yourself.
122
+ In other words, you have the art direction, format switching, and resolution
123
+ switching problems *solved*, with a one-liner and a nicely readable config file
124
+ that is 1/3 as long as the output markup. Lighthouse is happy, and you don't
125
+ even need to crop things yourself.
126
+
127
+ That isn't a complete demonstration of Jekyll Picture Tag's feature set; it can
128
+ (among other things) add width & height attributes to prevent page reflow, add a
129
+ link to the source image (or anywhere else), and adjust image quality. See the
130
+ docs for more.
@@ -0,0 +1,35 @@
1
+ ---
2
+ sort: 5
3
+ ---
4
+
5
+ # CDN
6
+
7
+ Use for images that are hosted at a different domain or subdomain than the
8
+ Jekyll site root. Overrides `relative_url`.
9
+
10
+ ## URL
11
+
12
+ *Format:* `cdn_url: (url)`
13
+
14
+ *Example:* `cdn_url: https://cdn.example.com`
15
+
16
+ *Default*: none
17
+
18
+ ## Environments
19
+
20
+ It's likely that if you're using a CDN, you may not want to use it in your local
21
+ development environment. This allows you to build a site with local images while
22
+ in development, and still push to a CDN when you build for production by
23
+ specifying a different
24
+ [environment](https://jekyllrb.com/docs/configuration/environments/).
25
+
26
+ *Format:* `cdn_environments: (array of strings)`
27
+
28
+ *Example:* `cdn_environments: ['production', 'staging']`
29
+
30
+ *Default*: `['production']`
31
+
32
+ **Note that the default jekyll environment is `development`**, meaning that if
33
+ you only set `cdn_url` and run `jekyll serve` or `jekyll build`, nothing will
34
+ change. Either run `JEKYLL_ENV=production bundle exec jekyll build`, or add
35
+ `development` to this setting.
@@ -0,0 +1,34 @@
1
+ ---
2
+ sort: 1
3
+ ---
4
+
5
+ # Directories
6
+
7
+ Define where JPT should look for source images, and where it should place
8
+ generated images.
9
+
10
+ ## Source
11
+
12
+ *Format:* `source: (directory)`
13
+
14
+ *Example:* `source: images/`
15
+
16
+ *Default:* Jekyll site root.
17
+
18
+ Base directory for your source images, relative to the Jekyll site root. For
19
+ example, if set to `images/_fullsize`:
20
+
21
+ this tag: {% raw %} `{% picture enishte/portrait.jpg %}` {% endraw %}
22
+ will use this path: `images/_fullsize/enishte/portrait.jpg`.
23
+
24
+ ## Output
25
+
26
+ *Format:* `output: (directory)`
27
+
28
+ *Example:* `output: resized_images/`
29
+
30
+ *Default*: `generated/`
31
+
32
+ Save resized, reformatted images to this directory in your compiled site. The
33
+ `source` directory structure is maintained. Relative to your compiled site
34
+ directory, which means `_site/` unless you've changed it.
@@ -0,0 +1,24 @@
1
+ ---
2
+ sort: 7
3
+ ---
4
+
5
+ # Disable Jekyll Picture Tag
6
+
7
+ *Format:* `disabled: (true|false|environment|array of environments)`
8
+
9
+ *Examples:*
10
+
11
+ - `disabled: true`
12
+
13
+ - `disabled: development`
14
+
15
+ - `disabled: [development, staging]`
16
+
17
+ *Default:* `false`
18
+
19
+ Disable image and markup generation entirely. Useful for debugging, or to speed
20
+ up site builds when you're working on something else.
21
+
22
+ Hint: If you're going to toggle this frequently, you might use a Jekyll
23
+ Environment. Set this to something like `nopics`, and then start Jekyll with
24
+ `JEKYLL_ENV=nopics bundle exec jekyll serve`.
@@ -0,0 +1,28 @@
1
+ ---
2
+ sort: 4
3
+ ---
4
+
5
+ # Fast Build
6
+
7
+ *Format:* `fast_build: (boolean|environment|environments)`
8
+
9
+ *Examples:*
10
+
11
+ - `fast_build: true`
12
+
13
+ - `fast_build: development`
14
+
15
+ - `fast_build: [development, staging]`
16
+
17
+ *Default:* `false`
18
+
19
+ *Might* make your builds faster (depending on hardware and how many images you
20
+ have) by making a tradeoff: assuming that the filename alone is enough to
21
+ uniquely identify a source image. This doesn't speed up image generation, just
22
+ detection of whether or not it's necessary.
23
+
24
+ Ordinarily, JPT computes an MD5 hash for every source image, every site build.
25
+ This ensures that if you replace one image with another, but keep the filename
26
+ the same, JPT will correctly generate images for the new file. Enable this
27
+ setting to skip MD5 hash checking and just assume that if the filename, format,
28
+ and width match then it's the right one.
@@ -0,0 +1,23 @@
1
+ ---
2
+ sort: 3
3
+ ---
4
+
5
+ # Ignore Missing Source Images
6
+
7
+ *Format:* `ignore_missing_images: (boolean|environment|environments)`
8
+
9
+ *Examples:*
10
+ - `ignore_missing_images: true`
11
+ - `ignore_missing_images: development`
12
+ - `ignore_missing_images: [development, testing]`
13
+
14
+ *Default:* `false`
15
+
16
+ Normally, JPT will raise an error if a source image is missing, causing the
17
+ entire site build to fail. This setting allows you to bypass this behavior and
18
+ continue the build, either for certain build environments or all the time.
19
+
20
+ I highly encourage you to set this to `development`, and set the Jekyll build
21
+ environment to `production` when you build for production so you don't shoot
22
+ yourself in the foot. You can read more about Jekyll environments
23
+ [here](https://jekyllrb.com/docs/configuration/environments/).
@@ -0,0 +1,29 @@
1
+ ---
2
+ sort: 1
3
+ ---
4
+ # Global Configuration
5
+
6
+ **All configuration is optional**. If you are happy with the defaults, you don't
7
+ have to touch a single yml file.
8
+
9
+ Global settings are stored under the `picture:` key in `/_config.yml`.
10
+
11
+ **Example:**
12
+
13
+ ```yml
14
+ # _config.yml
15
+
16
+ (...)
17
+
18
+ picture:
19
+ source: "assets/images/fullsize"
20
+ output: "assets/images/generated"
21
+ suppress_warnings: true
22
+ (...)
23
+
24
+ (...)
25
+ ```
26
+
27
+ ## Reference
28
+
29
+ {% include list.liquid %}
@@ -0,0 +1,20 @@
1
+ ---
2
+ sort: 8
3
+ ---
4
+
5
+ # Kramdown Fix
6
+
7
+ *Format:* `nomarkdown: (true|false)`
8
+
9
+ *Example:* `nomarkdown: false`
10
+
11
+ *Default:* `true`
12
+
13
+ Whether or not to surround j-p-t's output with a
14
+ `{::nomarkdown}..{:/nomarkdown}` block when called from within a markdown file.
15
+ When false, JPT will never add the wrapper. When true, JPT will add it only when
16
+ it believes it's necessary, though it's not 100% accurate at making this
17
+ determination.
18
+
19
+ This setting is overridden by the same setting in a preset. See [this note]({{
20
+ site.baseurl }}/users/notes/kramdown_bug) for more detailed information.
@@ -0,0 +1,15 @@
1
+ ---
2
+ sort: 6
3
+ ---
4
+
5
+ # Use Relative Urls
6
+
7
+ *Format:* `relative_url: (true|false)`
8
+
9
+ *Example:* `relative_url: false`
10
+
11
+ *Default*: `true`
12
+
13
+ Whether to use relative (`/generated/test(...).jpg`) or absolute
14
+ (`https://example.com/generated/test(...).jpg`) urls in your src and srcset
15
+ attributes.
@@ -0,0 +1,16 @@
1
+ ---
2
+ sort: 2
3
+ ---
4
+
5
+ # Suppress Warnings
6
+
7
+ *Format:* `suppress_warnings: (true|false)`
8
+
9
+ *Example:* `suppress_warnings: true`
10
+
11
+ *Default*: `false`
12
+
13
+ Jekyll Picture Tag will warn you in a few different scenarios, such as when your
14
+ base image is smaller than one of the sizes in your preset. (Note that Jekyll
15
+ Picture Tag will never resize an image to be larger than its source). Set this
16
+ value to `true`, and these warnings will not be shown.
@@ -0,0 +1,7 @@
1
+ ---
2
+ sort: 1
3
+ ---
4
+
5
+ # Usage
6
+
7
+ {% include list.liquid %}
@@ -0,0 +1,52 @@
1
+ ---
2
+ ---
3
+
4
+ # Installation
5
+
6
+ 1. Add `jekyll_picture_tag` to your Gemfile in the `:jekyll_plugins` group.
7
+ (Note that it's NOT `jekyll-picture-tag`):
8
+ ```ruby
9
+ # Gemfile
10
+
11
+ gem 'jekyll'
12
+
13
+ group :jekyll_plugins do
14
+ gem 'jekyll_picture_tag', ~> '1'
15
+ end
16
+ ```
17
+ 2. Run `$ bundle install`
18
+ 3. See if you have ImageMagick with `$ convert --version`. You should see
19
+ something like this:
20
+ ```bash
21
+ ~ $ convert --version
22
+ Version: ImageMagick 7.0.8-14 Q16 x86_64 2018-10-31 https://imagemagick.org
23
+ Copyright: © 1999-2018 ImageMagick Studio LLC License: https://imagemagick.org/script/license.php
24
+ Features: Cipher DPC HDRI OpenMP Delegates (built-in): bzlib fontconfig freetype jng jp2 jpeg lcms
25
+ lzma pangocairo png tiff webp xml zlib
26
+ ```
27
+ If you get a 'command not found' error, you'll need to install it. Most
28
+ package managers know about ImageMagick, otherwise it can be found
29
+ [here](https://imagemagick.org/script/download.php).
30
+
31
+ ```note
32
+ You need a 'webp' delegate if you want to generate webp files. Any image
33
+ format you want to handle will require an appropriate delegate; You may have
34
+ to install additional packages to accomplish this. Usually it's just named
35
+ 'webp'.
36
+ ```
37
+
38
+ ```warning
39
+ Cropping to an aspect ratio depends on ImageMagick 7+. Ubuntu, somewhat
40
+ annoyingly, only offers version 6 in its official repositories. This matters
41
+ even if you don't run Ubuntu, because many build & deployment services you might
42
+ use (including Netlify and Travis CI) do.
43
+ ```
44
+
45
+ If you'd like to use both the cropping feature and such a service, or it's
46
+ inconvenient to install version 7 in your development environment, you will
47
+ likely want to build your site in a docker container. The Alpine Linux repos
48
+ include version 7, so you'll want an Alpine Linux based image rather than an
49
+ Ubuntu based one. Conveniently this includes the [offical Jekyll
50
+ image](https://hub.docker.com/r/jekyll/jekyll).
51
+
52
+ Once I work out how to actually do that, I'll add some guidance here.
@@ -0,0 +1,18 @@
1
+ ---
2
+ sort: 4
3
+ ---
4
+
5
+ # Alternate images
6
+
7
+ _Format:_ `(media_query): (filename) [crop] [gravity] (...)`
8
+
9
+ _Example:_ `tablet: img_cropped.jpg mobile: img_cropped_more.jpg`
10
+
11
+ Optionally specify any number of alternate base images for given
12
+ [media_queries]({{ site.baseurl }}/users/presets/media_queries). This is called
13
+ [art direction](http://usecases.responsiveimages.org/#art-direction), and is one
14
+ of JPT's strongest features.
15
+
16
+ Give your images in order of ascending specificity (The first image is the
17
+ most general). They will be provided to the browser in reverse order, and it
18
+ will select the first one with an applicable media query.