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
@@ -1,8 +0,0 @@
1
- services:
2
- - docker
3
-
4
- before_install:
5
- - docker build . -t jpt
6
-
7
- script:
8
- - docker run -t jpt
@@ -1,32 +0,0 @@
1
- ---
2
- layout: default
3
- ---
4
-
5
- <link href="{{ site.baseurl }}/assets/style.css" rel="stylesheet" type="text/css">
6
-
7
- <ul class="directory">
8
- <li><a href="{{ site.baseurl }}/">Quick Start</a></li>
9
- <li><a href="{{ site.baseurl }}/installation">Installation</a></li>
10
- <li><a href="{{ site.baseurl }}/usage">Usage</a></li>
11
- <li><a href="{{ site.baseurl }}/global_configuration">Global Settings</a></li>
12
- <li><a href="{{ site.baseurl }}/presets">Writing Presets</a></li>
13
- <li><a href="{{ site.baseurl }}/example_presets">Example Presets</a></li>
14
- <li><a href="{{ site.baseurl }}/output">Output Formats</a></li>
15
- <li><a href="{{ site.baseurl }}/notes">Notes and FAQ</a></li>
16
- <li><a href="{{ site.baseurl }}/contributing">Contributing</a></li>
17
- <li><a href="{{ site.baseurl }}/releases">Release History</a></li>
18
- </ul>
19
-
20
- <hr />
21
-
22
- {{ content }}
23
-
24
- <script>
25
- const navItems = Array.from(document.querySelectorAll('ul.directory li'))
26
- const currentPath = window.location.toString()
27
- const activeItem = navItems.find(function(item) {
28
- return item.firstChild.href == currentPath
29
- })
30
-
31
- activeItem.classList.add('active')
32
- </script>
@@ -1,31 +0,0 @@
1
- @media (max-width: 600px) {
2
- ul.directory {
3
- flex-direction: column;
4
- align-items: center;
5
- }
6
- }
7
-
8
- ul.directory {
9
- display: flex;
10
- flex-wrap: wrap;
11
- justify-content: center;
12
- list-style: none;
13
- padding-left: 0;
14
- flex-grow: 0;
15
- }
16
-
17
- ul.directory li {
18
- margin: .3em;
19
- }
20
-
21
- ul.directory a {
22
- line-height: 2;
23
- padding: 8px 20px;
24
- }
25
-
26
- li.active a {
27
- border-radius: 3px;
28
- background-color: #007edf;
29
- color: #fff;
30
- box-shadow: 2px 2px 3px #999;
31
- }
@@ -1,109 +0,0 @@
1
- ---
2
- ---
3
- # Contributing
4
-
5
- Bug reports, feature requests, and feedback are very welcome, either through github issues or via
6
- email: robert@buchberger.cc
7
-
8
- Pull requests are encouraged! I'm happy to answer questions and provide assistance along the way.
9
- Don't let any of the recommendations/requests in this guide stop you from submitting one.
10
-
11
- ## Setup
12
-
13
- It's pretty standard:
14
-
15
- ```
16
- $ git clone git@github.com:rbuchberger/jekyll_picture_tag.git
17
- $ cd jekyll_picture_tag
18
- $ bundle install
19
- ```
20
-
21
- ## Testing
22
-
23
- You probably only need to use docker if it's inconvenient to install ImageMagick 7.
24
-
25
- ### Bare Metal
26
-
27
- `rake test` runs the test suite (both unit tests and integration tests). Ignore the mini_magick
28
- `method redefined` warnings (unless you know how to fix them?)
29
-
30
- `rake unit` runs just the unit tests, while `rake integration` runs the integration tests. The unit
31
- test coverage isn't stellar, but both unit and integration tests together hit 100%.
32
-
33
- Speaking of coverage, simplecov is set up -- you'll get a measurement of coverage in the test output
34
- and a nice report in the `coverage` directory. I'd like to move to mutation based coverage testing,
35
- but that's a project for another day.
36
-
37
- The tests do output a few images to the `/tmp/` directory, which I'm pretty sure means it won't work
38
- on Windows. This is fixable if there is a need, so if that gets in your way just ask.
39
-
40
- `rake rubocop` checks code formatting, `rake rubocop:auto_correct` will try to fix any rubocop
41
- issues, if possible.
42
-
43
- `rake` will run all tests and rubocop.
44
-
45
- ### Docker
46
-
47
- The following commands will build and run the tests inside a docker image. This is useful if it's
48
- inconvenient to install ImageMagick 7, or to ensure the Travis CI build will succeed:
49
-
50
- ```
51
- $ docker build . -t jpt
52
- $ docker run -t jpt
53
- ```
54
-
55
- ## Docs
56
-
57
- I think one of the biggest opportunities for improvement in this plugin is its documentation. I'd
58
- really love help here, and all you need to know is markdown.
59
-
60
- It runs on github pages, which is based on jekyll. You can preview as you edit:
61
-
62
- 0. Follow setup instructions above
63
- 1. `$ cd docs`
64
- 2. `$ bundle install`
65
- 3. `$ bundle exec jekyll serve`
66
- 4. In a web browser, navigate to `localhost:4000/jekyll_picture_tag/`
67
-
68
- ## Code Guidelines
69
-
70
- * Generally, go for straightforward and readable rather than terse and clever. I'm not actually a
71
- very good programmer; I need simple code that's easy to understand.
72
-
73
- * Refactoring is welcome, especially in the name of the previous point.
74
-
75
- * I'm very reluctant to introduce breaking changes to configuration settings. This rule isn't
76
- absolute, but I'm not going to do it without a good reason.
77
-
78
- * I've been using 80 characters for code and 100 characters for documentation.
79
-
80
- * Don't disable cops without strong justification.
81
-
82
- * I generally try to write tests before writing code, especially when fixing bugs. This
83
- gives us some confidence that what we think we're testing and what we're actually testing aren't
84
- too different.
85
-
86
- ## Hard rules
87
-
88
- These aren't the rules for submitting a pull request, these are the rules for merging into master.
89
- I'm thrilled to receive any help at all, and I'm more than happy to help with meeting these
90
- criteria:
91
-
92
- * Liquid tag syntax can only be extended; no breaking changes. I'm not willing to force
93
- users to dig through their entire site and change every picture tag in order to update to the
94
- latest version.
95
-
96
- * Maintain "no configuration required" - a new user must be able to add JPT to their gemfile, bundle
97
- install, and start writing picture tags in their site without touching a yml file.
98
-
99
- * 100% test coverage (Meaning that when running the unit and integration tests together, every line
100
- of code in the `lib` folder must run at least once.)
101
-
102
- * No failing tests
103
-
104
- * No rubocop warnings
105
-
106
- ### Thanks!
107
-
108
- As I said, don't let any of the rules & guidelines scare you away. They're the rules for merging
109
- into master, not submitting a pull request. I'm thrilled to receive any help at all.
@@ -1,116 +0,0 @@
1
- ---
2
- ---
3
- # /_data/picture.yml
4
-
5
- These are example settings- I mostly made them up off the top of my head. You
6
- probably don't want to just copy-paste them. The full documentation
7
- for these can be found [here]({{ site.baseurl }}/presets).
8
-
9
- ```yml
10
-
11
- # Media presets are just named css media queries, used in several places:
12
- # - To specify alternate source images (for art direction)
13
- # - To build the 'sizes' attribute
14
- # - When given alternate source images, specify which sizes to generate.
15
- media_presets:
16
- wide_desktop: 'min-width: 1801px'
17
- desktop: 'max-width: 1800px'
18
- wide_tablet: 'max-width: 1200px'
19
- tablet: 'max-width: 900px'
20
- mobile: 'max-width: 600px'
21
-
22
- # Markup presets allow you to group settings together, and select one of them by
23
- # name in your jekyll tag. All settings are optional.
24
- markup_presets:
25
-
26
- default:
27
- # What form the output markup should take:
28
- markup: auto
29
-
30
- # Must be an array, and order matters. Defaults to just 'original', which
31
- # does what you'd expect.
32
- formats: [webp, original]
33
-
34
- # Must be an array: which image sizes (width in pixels) to generate (unless
35
- # directed otherwise below). If not specified, will use sensible default
36
- # values.
37
- widths: [200, 400, 800, 1600]
38
-
39
- # Alternate source images (for art direction) are associated with media
40
- # query presets. Here, you can optionally specify a different set of sizes
41
- # to generate for those alternate source images. This is how you avoid
42
- # generating a 1600 pixel wide image that's only shown on narrow screens.
43
- # Must be arrays.
44
- media_widths:
45
- mobile: [200, 400, 600]
46
- tablet: [400, 600, 800]
47
-
48
- # For building the 'sizes' attribute on img and source tags. specifies how
49
- # wide the image will be when a given media query is true. Note that every
50
- # source in a given <picture> tag will have the same associated sizes
51
- # attribute.
52
- sizes:
53
- mobile: 100vw
54
- tablet: 80vw
55
-
56
- # Specifies an optional, unconditional size attribute. Can be given alone,
57
- # or if specified in combination with 'sizes' below, will be given last
58
- # (when no media queries apply).
59
- size: 800px
60
-
61
- # Specify the properties of the fallback image. If not specified, will
62
- # return a 900 pixel wide image in the original format.
63
- fallback_width: 800
64
- fallback_format: original
65
-
66
- # Add HTML attributes. 'parent' will go to the <picture> tag if it's there,
67
- # otherwise the 'img' tag.
68
- attributes:
69
- parent: 'data-downloadable="true"'
70
- picture: 'class="awesome" data-volume="11"'
71
- img: 'class="some-other-class"'
72
- a: 'class="image-link"'
73
-
74
- # This will wrap images in a link to the original source image. Obviously
75
- # your source images will need to be part of the deployed site for this to
76
- # work. If you have issues such as mangled HTML or extra {::nomarkdown}
77
- # tags floating around, see docs/notes.md
78
- link_source: true
79
-
80
- # This is an example of how you would create a 'multiplier' based srcset;
81
- # useful when an image will always be the same size on all screens (icons,
82
- # graphics, thumbnails, etc), but you'd like to supply higher resolution
83
- # images to devices with higher pixel ratios.
84
- icon:
85
- base_width: 20 # How wide the 1x image should be
86
- pixel_ratios: [1, 1.5, 2]
87
- fallback_width: 20
88
- attributes:
89
- img: 'class="icon"'
90
-
91
- # Here's an example of how you'd configure jekyll-picture-tag to work with
92
- # something like lazyload:
93
- # https://github.com/verlok/lazyload
94
- lazy:
95
- # data_auto gives you data-src, data-srcset, and data-sizes instead of src,
96
- # srcset, and sizes:
97
- markup: data_auto
98
- formats: [webp, original]
99
- widths: [200, 400, 600, 800]
100
- noscript: true # add a fallback image inside a <noscript> tag.
101
- attributes:
102
- img: class="lazy"
103
-
104
- # This is an example of how you'd get generated image and a URL, and nothing
105
- # else.
106
- direct:
107
- markup: direct_url
108
- fallback_format: webp # Default original
109
- fallback_width: 600 # Default 800
110
-
111
- # Here's a naked srcset. Doesn't even give you the surrounding quotes.
112
- srcset:
113
- markup: naked_srcset
114
- formats: [webp] # must be an array, even if it only has one item
115
-
116
- ```
@@ -1,173 +0,0 @@
1
- ---
2
- ---
3
- # Global Configuration
4
-
5
- **All configuration is optional**. If you are happy with the defaults, you don't have to touch a
6
- single yaml file.
7
-
8
- Global settings are stored under the `picture:` key in `/_config.yml`.
9
-
10
- **Example config:**
11
-
12
- ```yml
13
- picture:
14
- source: "assets/images/fullsize"
15
- output: "assets/images/generated"
16
- ```
17
-
18
- * **Source Image Directory**
19
-
20
- *Format:* `source: (directory)`
21
-
22
- *Example:* `source: images/`
23
-
24
- *Default:* Jekyll site root.
25
-
26
- To make writing tags easier you can specify a source directory for your assets. Base images in the
27
- tag will be relative to the `source` directory, which is relative to the Jekyll site root.
28
-
29
- {% raw %}
30
- For example, if `source` is set to `assets/images/_fullsize`, the tag
31
- `{% picture enishte/portrait.jpg --alt An unsual picture %}` will look for a file at
32
- {% endraw %}
33
- `assets/images/_fullsize/enishte/portrait.jpg`.
34
-
35
- * **Destination Image Directory**
36
-
37
- *Format:* `output: (directory)`
38
-
39
- *Example:* `output: resized_images/`
40
-
41
- *Default*: `generated/`
42
-
43
- Jekyll Picture Tag saves resized, reformatted images to the `output` directory in your compiled
44
- site. The organization of your `source` directory is maintained.
45
-
46
- This setting is relative to your compiled site, which means `_site` unless you've changed it.
47
-
48
- * **Suppress Warnings**
49
-
50
- *Format:* `suppress_warnings: (true|false)`
51
-
52
- *Example:* `suppress_warnings: true`
53
-
54
- *Default*: `false`
55
-
56
- Jekyll Picture Tag will warn you in a few different scenarios, such as when your base image is
57
- smaller than one of the sizes in your preset. (Note that Jekyll Picture Tag will never resize an
58
- image to be larger than its source). Set this value to `true`, and these warnings will not be shown.
59
-
60
- * **Continue build with missing source images**
61
-
62
- *Format:* `ignore_missing_images: (boolean|environment name|array of environments)`
63
-
64
- *Example:* `ignore_missing_images: [development, testing]`
65
-
66
- *Default:* `false`
67
-
68
- Normally, JPT will raise an error if a source image is missing, causing the entire site build to
69
- fail. This setting allows you to bypass this behavior and continue the build, either for certain
70
- build environments or all the time. I highly encourage you to set this to `development`, and set
71
- the jekyll build environment to `production` when you build for production so you don't shoot
72
- yourself in the foot (publish a site with broken images). You can read more about Jekyll
73
- environments [here](https://jekyllrb.com/docs/configuration/environments/).
74
-
75
- * **Use Relative Urls**
76
-
77
- *Format:* `relative_url: (true|false)`
78
-
79
- *Example:* `relative_url: false`
80
-
81
- *Default*: `true`
82
-
83
- Whether to use relative (`/generated/test(...).jpg`) or absolute
84
- (`https://example.com/generated/test(...).jpg`) urls in your src and srcset attributes.
85
-
86
- * **Use a CDN Url**
87
-
88
- *Format:* `cdn_url: (url)`
89
-
90
- *Example:* `cdn_url: https://cdn.example.com`
91
-
92
- *Default*: none
93
-
94
- Use for images that are hosted at a different domain or subdomain than the Jekyll site root. Overrides
95
- `relative_url`. Keep reading, the next option is important.
96
-
97
- * **CDN build environments**
98
-
99
- *Format:* `cdn_environments: (array of strings)`
100
-
101
- *Example:* `cdn_environments: ['production', 'staging']`
102
-
103
- *Default*: `['production']`
104
-
105
- It's likely that if you're using a CDN, you may not want to use it in your local development environment. This
106
- allows you to build a site with local images while in development, and still push to a CDN when you build for
107
- production by specifying a different [environment](https://jekyllrb.com/docs/configuration/environments/).
108
-
109
- **Note that the default jekyll environment is `development`**, meaning that if you only set `cdn_url` and run
110
- `jekyll serve` or `jekyll build`, nothing will change. You'll either need to run `JEKYLL_ENV=production bundle exec
111
- jekyll build`, or add `development` to this setting.
112
-
113
- * **Kramdown nomarkdown fix**
114
-
115
- *Format:* `nomarkdown: (true|false)`
116
-
117
- *Example:* `nomarkdown: false`
118
-
119
- *Default:* `true`
120
-
121
- Whether or not to surround j-p-t's output with a `{::nomarkdown}..{:/nomarkdown}` block when called
122
- from within a markdown file.
123
-
124
- This setting is overridden by the same setting in a preset. See [the notes]({{ site.baseurl
125
- }}/notes) for more detailed information.
126
-
127
- * **Fast Build**
128
-
129
- *Format:* `fast_build: (true|false|environment|array of environments)`
130
-
131
- *Examples:*
132
-
133
- - `fast_build: true`
134
-
135
- - `fast_build: development`
136
-
137
- - `fast_build: [development, staging]`
138
-
139
- *Default:* `false`
140
-
141
- Makes a tradeoff: Speeds repeated build times for sites with many images, by assuming that the
142
- filename alone is enough to uniquely identify a source image. This doesn't speed up image
143
- generation, just detection of whether or not it's necessary.
144
-
145
- Ordinarily, JPT generates an MD5 hash for every source image, every site build. This ensures that
146
- if you replace one image with another, but keep the filename the same, JPT will correctly generate
147
- images for the new file. If you have many large images and/or limited hardware, this can take some
148
- time and make the development process painful. Enable this setting to skip MD5 hash checking on
149
- existing generated images (most of the time), and just assume that if the filename, format, and
150
- width match then it's the right one. If there are multiple possible matches (resulting from
151
- leftover generated images from previous filename replacements), it'll compute a hash instead of
152
- guessing randomly.
153
-
154
- * **Disable Jekyll Picture Tag**
155
-
156
- *Format:* `disabled: (true|false|environment|array of environments)`
157
-
158
- *Examples:*
159
-
160
- - `disabled: true`
161
-
162
- - `disabled: development`
163
-
164
- - `disabled: [development, staging]`
165
-
166
- *Default:* `false`
167
-
168
- Disable image and markup generation entirely. Useful for debugging, or to speed up site builds
169
- when you're working on something else.
170
-
171
- Hint: If you're going to toggle this on and off frequently, you might just use an environment
172
- variable. Set this to something like `nopics`, and then start the Jekyll server with something
173
- like `JEKYLL_ENV=nopics bundle exec jekyll serve` when you don't want image generation.