jekyll-minibundle 2.0.1 → 3.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/CHANGELOG.md +253 -59
- data/LICENSE.txt +1 -1
- data/README.md +332 -111
- data/Rakefile +42 -13
- data/jekyll-minibundle.gemspec +19 -15
- data/lib/jekyll/minibundle.rb +2 -0
- data/lib/jekyll/minibundle/asset_bundle.rb +24 -13
- data/lib/jekyll/minibundle/asset_file_drop.rb +48 -0
- data/lib/jekyll/minibundle/asset_file_properties.rb +20 -12
- data/lib/jekyll/minibundle/asset_file_registry.rb +11 -9
- data/lib/jekyll/minibundle/asset_stamp.rb +2 -0
- data/lib/jekyll/minibundle/asset_tag_markup.rb +22 -24
- data/lib/jekyll/minibundle/bundle_file.rb +48 -24
- data/lib/jekyll/minibundle/development_file.rb +22 -7
- data/lib/jekyll/minibundle/development_file_collection.rb +4 -2
- data/lib/jekyll/minibundle/environment.rb +17 -15
- data/lib/jekyll/minibundle/exceptions.rb +2 -0
- data/lib/jekyll/minibundle/files.rb +13 -0
- data/lib/jekyll/minibundle/hashes.rb +13 -12
- data/lib/jekyll/minibundle/log.rb +8 -8
- data/lib/jekyll/minibundle/mini_bundle_block.rb +51 -17
- data/lib/jekyll/minibundle/mini_stamp_tag.rb +111 -16
- data/lib/jekyll/minibundle/stamp_file.rb +34 -16
- data/lib/jekyll/minibundle/variable_template.rb +148 -0
- data/lib/jekyll/minibundle/variable_template_registry.rb +21 -0
- data/lib/jekyll/minibundle/version.rb +3 -1
- data/test/fixture/site/_bin/remove_comments +1 -0
- data/test/fixture/site/_bin/with_count +2 -1
- data/test/fixture/site/_config.yml +2 -1
- data/test/fixture/site/_layouts/default.html +2 -1
- data/test/integration/minibundle_development_mode_test.rb +268 -82
- data/test/integration/minibundle_production_mode_test.rb +481 -147
- data/test/integration/ministamp_development_mode_test.rb +84 -34
- data/test/integration/ministamp_production_mode_test.rb +187 -34
- data/test/integration/static_files_as_asset_sources_test.rb +16 -14
- data/test/support/assertions.rb +3 -1
- data/test/support/fixture_config.rb +14 -12
- data/test/support/static_file_config.rb +23 -0
- data/test/support/test_case.rb +37 -16
- data/test/unit/asset_bundle_test.rb +23 -14
- data/test/unit/asset_file_drop_test.rb +66 -0
- data/test/unit/asset_file_registry_test.rb +141 -106
- data/test/unit/asset_tag_markup_test.rb +30 -16
- data/test/unit/bundle_file_properties_test.rb +56 -22
- data/test/unit/bundle_file_writing_test.rb +93 -37
- data/test/unit/development_file_properties_test.rb +97 -0
- data/test/unit/development_file_writing_test.rb +50 -0
- data/test/unit/environment_test.rb +8 -6
- data/test/unit/files_test.rb +21 -6
- data/test/unit/hashes_test.rb +15 -13
- data/test/unit/jekyll_static_file_api_test.rb +155 -9
- data/test/unit/mini_bundle_block_test.rb +78 -21
- data/test/unit/mini_stamp_tag_test.rb +42 -9
- data/test/unit/stamp_file_properties_test.rb +57 -21
- data/test/unit/stamp_file_writing_test.rb +78 -31
- data/test/unit/variable_template_test.rb +121 -0
- metadata +57 -22
- data/lib/jekyll/minibundle/asset_file_operations.rb +0 -15
- data/test/support/static_file_api_config.rb +0 -16
- data/test/unit/development_file_collection_properties_test.rb +0 -92
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 997ab9ce6b810501fe2ef0177f8982cf5cae5b7f98871ca84c160e15dd90852a
|
|
4
|
+
data.tar.gz: eeedab2288ea816ffb94568ddc80a5a4a560e4701bb7b5a9c07875100e191338
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 4cc289086a2222a0f1e67df53135143da8248a9989e8ebd02839ab10260e2090ab83198f1b1cf271a6792a566d9b2182b28e62cb89cb62a4b42597a99a10bb60
|
|
7
|
+
data.tar.gz: 90af2278865d5be704c6d36263b9df905d61d28d28914f7584b10640770fb3af7fc129d3c798abcddda57b8d713193df17b4b22ddf9b1c70eb4ffcb0638bb29b
|
data/CHANGELOG.md
CHANGED
|
@@ -1,88 +1,229 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Changelog
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This project adheres to [Semantic Versioning].
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## [Unreleased]
|
|
6
|
+
|
|
7
|
+
## [v3.0.0] - 2020-09-06
|
|
8
|
+
|
|
9
|
+
No functional changes, only minor refactorings since v2.2.0. Dropping
|
|
10
|
+
support for Ruby MRI < 2.4 causes major version bump.
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
* Increase test coverage.
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
|
|
18
|
+
* Hygienic refactorings: use frozen string literals, prefer squiggly
|
|
19
|
+
heredocs over non-squiggly ones, adhere to the RuboCop linter.
|
|
20
|
+
|
|
21
|
+
### Removed
|
|
22
|
+
|
|
23
|
+
* Drop support for Ruby MRI versions below 2.4.
|
|
24
|
+
|
|
25
|
+
## [v2.2.0] - 2017-03-10
|
|
26
|
+
|
|
27
|
+
### Added
|
|
28
|
+
|
|
29
|
+
* Add support for separating asset destination path from the generated
|
|
30
|
+
asset URL. See `render_basename_only` option of `ministamp` tag and
|
|
31
|
+
`destination_baseurl` option of `minibundle` block.
|
|
32
|
+
|
|
33
|
+
### Changed
|
|
34
|
+
|
|
35
|
+
* Treat `ministamp` tag's argument as YAML, resulting either in String
|
|
36
|
+
or Hash type of argument after YAML parsing. If argument is of Hash
|
|
37
|
+
type, render values with Liquid-like templating support, allowing
|
|
38
|
+
rendering Liquid variables. This change is backwards compatible.
|
|
39
|
+
* Escape the URLs generated by `ministamp` tag and `minibundle` block.
|
|
40
|
+
* Quote paths in error messages more consistently.
|
|
41
|
+
* Show better error messages in various situations when asset source
|
|
42
|
+
file does not exist.
|
|
43
|
+
* Compatibility: conform to Jekyll 3.4.2's StaticFile public API.
|
|
44
|
+
|
|
45
|
+
## [v2.1.2] - 2017-02-28
|
|
46
|
+
|
|
47
|
+
### Added
|
|
48
|
+
|
|
49
|
+
* Show bundle destination path in bundling log message.
|
|
50
|
+
|
|
51
|
+
### Fixed
|
|
52
|
+
|
|
53
|
+
* Remove unnecessary '.' path component from asset destination path.
|
|
54
|
+
This manifested when the asset destination had no subdirectory.
|
|
55
|
+
Affects `ministamp` tag and `minibundle` block.
|
|
56
|
+
|
|
57
|
+
Example situation:
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
<link href="{{ site.baseurl }}/{% ministamp _assets/site.css site.css %}" rel="stylesheet">
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Generation result, before the fix:
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
<link href="/./site-6a204bd89f3c8348afd5c77c717a097a.css" rel="stylesheet">
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Generation result, after the fix:
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
<link href="/site-6a204bd89f3c8348afd5c77c717a097a.css" rel="stylesheet">
|
|
73
|
+
```
|
|
74
|
+
* Related to above: Don't let Jekyll's watch mode (auto-regeneration)
|
|
75
|
+
remove asset from generated site directory when asset destination path
|
|
76
|
+
has no subdirectory.
|
|
77
|
+
|
|
78
|
+
## [v2.1.1] - 2017-01-14
|
|
79
|
+
|
|
80
|
+
### Changed
|
|
81
|
+
|
|
82
|
+
* Compatibility: conform to Jekyll 3.3's StaticFile public API.
|
|
83
|
+
|
|
84
|
+
### Fixed
|
|
85
|
+
|
|
86
|
+
* Fix the file permissions of `minibundle` block's output file to
|
|
87
|
+
respect umask setting. Bug report from Alfonse Surigao.
|
|
88
|
+
|
|
89
|
+
## [v2.1.0] - 2016-05-04
|
|
90
|
+
|
|
91
|
+
### Changed
|
|
92
|
+
|
|
93
|
+
* Allow attributes without values. Useful for `async` attribute, for
|
|
94
|
+
example. Pull Request #7 by Sam (@codewisdom).
|
|
95
|
+
|
|
96
|
+
### Fixed
|
|
97
|
+
|
|
98
|
+
* Ensure attribute value conversion to string.
|
|
99
|
+
|
|
100
|
+
## [v2.0.1] - 2016-04-06
|
|
101
|
+
|
|
102
|
+
### Fixed
|
|
103
|
+
|
|
104
|
+
* Fix Jekyll version requirement check to be more reliable.
|
|
105
|
+
|
|
106
|
+
## [v2.0.0] - 2016-04-01
|
|
107
|
+
|
|
108
|
+
### Changed
|
|
6
109
|
|
|
7
|
-
* Drop support for Jekyll versions below 3
|
|
8
110
|
* Remove unused asset cache entries and temporary files when Jekyll
|
|
9
|
-
rebuilds the site
|
|
111
|
+
rebuilds the site.
|
|
10
112
|
* Document a known caveat: the plugin doesn't work with Jekyll's
|
|
11
113
|
incremental rebuild feature.
|
|
12
114
|
|
|
13
|
-
|
|
115
|
+
### Removed
|
|
116
|
+
|
|
117
|
+
* Drop support for Jekyll versions below 3.
|
|
118
|
+
|
|
119
|
+
## [v1.6.0] - 2016-03-26
|
|
120
|
+
|
|
121
|
+
### Changed
|
|
14
122
|
|
|
15
123
|
* Log the last 2000 bytes of minifier's STDOUT output if the minifier
|
|
16
124
|
command fails. Pull Request #6 by Martin Nordholts (@Enselic).
|
|
17
125
|
* Allow prepending base URL for the destination path of `minibundle`
|
|
18
|
-
block
|
|
19
|
-
|
|
126
|
+
block.
|
|
127
|
+
|
|
128
|
+
### Removed
|
|
129
|
+
|
|
130
|
+
* Drop Ruby MRI 1.9 support because Jekyll 3 does not support it.
|
|
131
|
+
|
|
132
|
+
### Fixed
|
|
133
|
+
|
|
20
134
|
* Fix issues in asset reloading in Jekyll's watch (auto-regeneration)
|
|
21
|
-
mode, doing bundling and asset fingerprinting again
|
|
135
|
+
mode, doing bundling and asset fingerprinting again.
|
|
22
136
|
|
|
23
|
-
|
|
137
|
+
## [v1.5.1] - 2015-01-29
|
|
138
|
+
|
|
139
|
+
### Changed
|
|
24
140
|
|
|
25
141
|
* Improve future compatibility with Jekyll. Minibundle has classes
|
|
26
142
|
adhering to `Jekyll::StaticFile` interface, and some method
|
|
27
143
|
implementations of the interface were missing.
|
|
28
|
-
* Small refactorings and test improvements
|
|
144
|
+
* Small refactorings and test improvements.
|
|
145
|
+
|
|
146
|
+
## [v1.5.0] - 2014-07-27
|
|
29
147
|
|
|
30
|
-
|
|
148
|
+
### Added
|
|
31
149
|
|
|
32
150
|
* Support minifier command specification in `_config.yml` and inside
|
|
33
151
|
`minibundle` block. Issue #4 by Phillip Smith (@phillipadsmith).
|
|
34
|
-
* Support enabling development mode from `_config.yml
|
|
35
|
-
* Add argument validation to `minibundle` block and `ministamp` tag
|
|
36
|
-
* Document how to load the gem with Jekyll's `gems` config setting
|
|
152
|
+
* Support enabling development mode from `_config.yml`.
|
|
153
|
+
* Add argument validation to `minibundle` block and `ministamp` tag.
|
|
154
|
+
* Document how to load the gem with Jekyll's `gems` config setting.
|
|
155
|
+
|
|
156
|
+
## [v1.4.6] - 2014-05-10
|
|
37
157
|
|
|
38
|
-
|
|
158
|
+
### Changed
|
|
39
159
|
|
|
40
160
|
* Handle compatibility issues with safe_yaml and logger flexibly. This
|
|
41
161
|
should allow using the plugin with Jekyll 1.0 and 2.0.
|
|
42
162
|
|
|
43
|
-
|
|
163
|
+
## [v1.4.5] - 2014-05-10
|
|
164
|
+
|
|
165
|
+
### Changed
|
|
44
166
|
|
|
45
167
|
* Use SafeYAML to load user input from `minibundle` block for
|
|
46
|
-
consistent behavior with Jekyll and for security
|
|
47
|
-
* Clean log messages: show relative paths when bundling assets
|
|
168
|
+
consistent behavior with Jekyll and for security.
|
|
169
|
+
* Clean log messages: show relative paths when bundling assets.
|
|
170
|
+
|
|
171
|
+
### Fixed
|
|
172
|
+
|
|
48
173
|
* Add missing implementations of `relative_path` and `to_liquid`
|
|
49
174
|
methods from Jekyll's StaticFile API (introduced in Jekyll v1.5.0),
|
|
50
175
|
allowing Minibundle to behave better with other Jekyll
|
|
51
176
|
plugins. Issue #3 by Michael Rose (@mmistakes).
|
|
52
177
|
* Fix Ruby deprecation warnings (use `File.exist?` instead of
|
|
53
|
-
`File.exists?`)
|
|
178
|
+
`File.exists?`).
|
|
179
|
+
|
|
180
|
+
## [v1.4.4] - 2014-01-16
|
|
54
181
|
|
|
55
|
-
|
|
182
|
+
### Changed
|
|
56
183
|
|
|
57
184
|
* Conserve memory when calculating fingerprint for an asset.
|
|
58
185
|
Previously, we read the whole asset file into memory and then
|
|
59
186
|
calculated the MD5 digest. This is bad for big assets. Now, we read
|
|
60
187
|
the file in chunks.
|
|
61
188
|
|
|
62
|
-
|
|
189
|
+
## [v1.4.3] - 2014-01-16
|
|
190
|
+
|
|
191
|
+
### Changed
|
|
192
|
+
|
|
193
|
+
* Loosen version constraints for development gem dependencies.
|
|
194
|
+
* Clarify documentation.
|
|
195
|
+
* Minor internal state handling improvements.
|
|
196
|
+
* Clarify tests, increase test coverage.
|
|
63
197
|
|
|
64
|
-
|
|
65
|
-
* Loosen version constraints for development gem dependencies
|
|
66
|
-
* Clarify documentation
|
|
67
|
-
* Fix some Ruby coding style issues
|
|
68
|
-
* Minor internal state handling improvements
|
|
69
|
-
* Clarify tests, increase test coverage
|
|
198
|
+
### Fixed
|
|
70
199
|
|
|
71
|
-
|
|
200
|
+
* Do not leak read pipe file descriptor upon minifier command failure.
|
|
201
|
+
* Fix some Ruby coding style issues.
|
|
202
|
+
|
|
203
|
+
## [v1.4.2] - 2013-12-28
|
|
204
|
+
|
|
205
|
+
### Changed
|
|
206
|
+
|
|
207
|
+
* Separate tags produced by `minibundle` in development mode with
|
|
208
|
+
newlines.
|
|
209
|
+
* Clarify tests, increase coverage.
|
|
210
|
+
|
|
211
|
+
### Fixed
|
|
72
212
|
|
|
73
213
|
* Ensure touching asset source triggers destination write. This was an
|
|
74
214
|
unintentional edge case earlier. Now the behavior of touching the
|
|
75
215
|
asset source is consistent with when changing the contents of the
|
|
76
216
|
source.
|
|
77
|
-
* Separate tags produced by `minibundle` in development mode with
|
|
78
|
-
newlines
|
|
79
|
-
* Clarify tests, increase coverage
|
|
80
217
|
|
|
81
|
-
|
|
218
|
+
## [v1.4.1] - 2013-12-27
|
|
219
|
+
|
|
220
|
+
### Fixed
|
|
82
221
|
|
|
83
|
-
* Add missing files to gem package
|
|
222
|
+
* Add missing files to gem package.
|
|
84
223
|
|
|
85
|
-
|
|
224
|
+
## [v1.4.0] - 2013-12-27
|
|
225
|
+
|
|
226
|
+
### Fixed
|
|
86
227
|
|
|
87
228
|
* Fix bug causing exception to be thrown when `ministamp` or
|
|
88
229
|
`minibundle` is called twice with same asset source argument. Allow
|
|
@@ -90,43 +231,96 @@
|
|
|
90
231
|
(remove the restriction introduced in 1.3.0). Issue #2 by Austin
|
|
91
232
|
Grigg (@agrigg).
|
|
92
233
|
|
|
93
|
-
|
|
234
|
+
## [v1.3.0] - 2013-12-25
|
|
235
|
+
|
|
236
|
+
### Changed
|
|
237
|
+
|
|
238
|
+
* Upgrade development dependencies.
|
|
239
|
+
|
|
240
|
+
### Fixed
|
|
94
241
|
|
|
95
242
|
* Disallow handling asset source files that are already static files
|
|
96
243
|
in Jekyll. Otherwise, we would potentially get to inconsistencies in
|
|
97
244
|
Jekyll's watch mode. See "Jekyll static file restriction" in
|
|
98
245
|
README.md. Issue #2 by Austin Grigg (@agrigg).
|
|
99
|
-
* Upgrade development dependencies
|
|
100
246
|
|
|
101
|
-
|
|
247
|
+
## [v1.2.0] - 2013-09-29
|
|
248
|
+
|
|
249
|
+
### Changed
|
|
250
|
+
|
|
251
|
+
* If Jekyll's logger is available, use it for nice output when bundling.
|
|
252
|
+
* Upgrade development dependencies.
|
|
253
|
+
* Simplify `BundleFile` class implementation.
|
|
254
|
+
|
|
255
|
+
## [v1.1.0] - 2013-02-27
|
|
102
256
|
|
|
103
|
-
|
|
104
|
-
* Upgrade development dependencies
|
|
105
|
-
* Simplify `BundleFile` class implementation
|
|
257
|
+
### Added
|
|
106
258
|
|
|
107
|
-
|
|
259
|
+
* `ministamp` tag omits fingerprint in development mode.
|
|
108
260
|
|
|
109
|
-
|
|
110
|
-
|
|
261
|
+
### Changed
|
|
262
|
+
|
|
263
|
+
* Clarify documentation.
|
|
111
264
|
* Comply with (Gemnasium) conventions for changelogs. Pull Request #1
|
|
112
265
|
by Teemu Matilainen (@tmatilai).
|
|
113
|
-
* Bug fix: do not bundle assets when nonrelated files change
|
|
114
|
-
* Bug fix: do not bundle assets twice upon startup
|
|
115
|
-
|
|
116
|
-
# 1.0.0 / 2013-02-15
|
|
117
266
|
|
|
118
|
-
|
|
119
|
-
as-is to the destination directory
|
|
120
|
-
* Clarify documentation
|
|
121
|
-
* Increase test coverage
|
|
267
|
+
### Fixed
|
|
122
268
|
|
|
123
|
-
|
|
269
|
+
* Don't bundle assets when nonrelated files change.
|
|
270
|
+
* Don't bundle assets twice upon startup.
|
|
124
271
|
|
|
125
|
-
|
|
126
|
-
* Add semicolons between each JavaScript asset in bundling
|
|
127
|
-
* Show error in page output if asset bundling command failed
|
|
272
|
+
## [v1.0.0] - 2013-02-15
|
|
128
273
|
|
|
129
|
-
|
|
274
|
+
### Added
|
|
130
275
|
|
|
131
|
-
* Add
|
|
132
|
-
|
|
276
|
+
* Add development mode, where `minibundle` block will copy each asset
|
|
277
|
+
as-is to the destination directory.
|
|
278
|
+
|
|
279
|
+
### Changed
|
|
280
|
+
|
|
281
|
+
* Clarify documentation.
|
|
282
|
+
* Increase test coverage.
|
|
283
|
+
|
|
284
|
+
## [v0.2.0] - 2012-12-15
|
|
285
|
+
|
|
286
|
+
### Added
|
|
287
|
+
|
|
288
|
+
* Add semicolons between each JavaScript asset in bundling.
|
|
289
|
+
* Show error in page output if asset bundling command failed.
|
|
290
|
+
|
|
291
|
+
### Changed
|
|
292
|
+
|
|
293
|
+
* Escape the values of custom attributes given in `minibundle` block.
|
|
294
|
+
|
|
295
|
+
## [v0.1.0] - 2012-12-07
|
|
296
|
+
|
|
297
|
+
### Added
|
|
298
|
+
|
|
299
|
+
* Add `ministamp` tag and `minibundle` block for Jekyll.
|
|
300
|
+
* First release.
|
|
301
|
+
|
|
302
|
+
[Semantic Versioning]: https://semver.org/spec/v2.0.0.html
|
|
303
|
+
[Unreleased]: https://github.com/tkareine/jekyll-minibundle/compare/v3.0.0...HEAD
|
|
304
|
+
[v3.0.0]: https://github.com/tkareine/jekyll-minibundle/compare/v2.2.0...v3.0.0
|
|
305
|
+
[v2.2.0]: https://github.com/tkareine/jekyll-minibundle/compare/v2.1.2...v2.2.0
|
|
306
|
+
[v2.1.2]: https://github.com/tkareine/jekyll-minibundle/compare/v2.1.1...v2.1.2
|
|
307
|
+
[v2.1.1]: https://github.com/tkareine/jekyll-minibundle/compare/v2.1.0...v2.1.1
|
|
308
|
+
[v2.1.0]: https://github.com/tkareine/jekyll-minibundle/compare/v2.0.1...v2.1.0
|
|
309
|
+
[v2.0.1]: https://github.com/tkareine/jekyll-minibundle/compare/v2.0.0...v2.0.1
|
|
310
|
+
[v2.0.0]: https://github.com/tkareine/jekyll-minibundle/compare/v1.6.0...v2.0.0
|
|
311
|
+
[v1.6.0]: https://github.com/tkareine/jekyll-minibundle/compare/v1.5.1...v1.6.0
|
|
312
|
+
[v1.5.1]: https://github.com/tkareine/jekyll-minibundle/compare/v1.5.0...v1.5.1
|
|
313
|
+
[v1.5.0]: https://github.com/tkareine/jekyll-minibundle/compare/v1.4.6...v1.5.0
|
|
314
|
+
[v1.4.6]: https://github.com/tkareine/jekyll-minibundle/compare/v1.4.5...v1.4.6
|
|
315
|
+
[v1.4.5]: https://github.com/tkareine/jekyll-minibundle/compare/v1.4.4...v1.4.5
|
|
316
|
+
[v1.4.4]: https://github.com/tkareine/jekyll-minibundle/compare/v1.4.3...v1.4.4
|
|
317
|
+
[v1.4.3]: https://github.com/tkareine/jekyll-minibundle/compare/v1.4.2...v1.4.3
|
|
318
|
+
[v1.4.2]: https://github.com/tkareine/jekyll-minibundle/compare/v1.4.1...v1.4.2
|
|
319
|
+
[v1.4.1]: https://github.com/tkareine/jekyll-minibundle/compare/v1.4.0...v1.4.1
|
|
320
|
+
[v1.4.0]: https://github.com/tkareine/jekyll-minibundle/compare/v1.3.0...v1.4.0
|
|
321
|
+
[v1.3.0]: https://github.com/tkareine/jekyll-minibundle/compare/v1.2.0...v1.3.0
|
|
322
|
+
[v1.2.0]: https://github.com/tkareine/jekyll-minibundle/compare/v1.1.0...v1.2.0
|
|
323
|
+
[v1.1.0]: https://github.com/tkareine/jekyll-minibundle/compare/v1.0.0...v1.1.0
|
|
324
|
+
[v1.0.0]: https://github.com/tkareine/jekyll-minibundle/compare/v0.2.0...v1.0.0
|
|
325
|
+
[v0.2.0]: https://github.com/tkareine/jekyll-minibundle/compare/v0.1.0...v0.2.0
|
|
326
|
+
[v0.1.0]: https://github.com/tkareine/jekyll-minibundle/releases/tag/v0.1.0
|
data/LICENSE.txt
CHANGED
data/README.md
CHANGED
|
@@ -1,68 +1,69 @@
|
|
|
1
1
|
# Jekyll Minibundle plugin
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
for
|
|
3
|
+
[][MinibundleGem]
|
|
4
|
+
[][MinibundleCI]
|
|
5
|
+
|
|
6
|
+
A straightforward asset bundling plugin for [Jekyll], utilizing external
|
|
7
|
+
minification tool of your choice. It provides asset concatenation for
|
|
8
|
+
bundling and asset fingerprinting with MD5 digest for cache busting.
|
|
7
9
|
|
|
8
|
-
There are no runtime dependencies, except for the minification tool
|
|
9
|
-
|
|
10
|
+
There are no runtime dependencies, except for the minification tool used
|
|
11
|
+
for bundling (fingerprinting has no dependencies).
|
|
10
12
|
|
|
11
|
-
The plugin requires Jekyll version 3.
|
|
12
|
-
2.
|
|
13
|
+
The plugin requires Jekyll version 3 or 4. It is tested with Ruby MRI
|
|
14
|
+
2.4 and later.
|
|
13
15
|
|
|
14
16
|
The plugin works with Jekyll's watch mode (auto-regeneration, Jekyll
|
|
15
17
|
option `--watch`), but not with incremental feature enabled (Jekyll
|
|
16
18
|
option `--incremental`).
|
|
17
19
|
|
|
18
|
-
[][MinibundleGem]
|
|
19
|
-
[][MinibundleBuild]
|
|
20
|
-
|
|
21
20
|
## Features
|
|
22
21
|
|
|
23
|
-
There are two features: asset fingerprinting with MD5 digest over
|
|
24
|
-
contents of the asset, and asset bundling combined with the first
|
|
22
|
+
There are two features: asset fingerprinting with [MD5 digest][MD5] over
|
|
23
|
+
the contents of the asset, and asset bundling combined with the first
|
|
25
24
|
feature.
|
|
26
25
|
|
|
27
26
|
Asset bundling consists of concatenation and minification. The plugin
|
|
28
|
-
implements concatenation and leaves choosing the minification tool up
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
Why is this good? A fingerprint in asset's path is
|
|
35
|
-
[recommended way][GoogleWebFundamentalsHttpCaching] to handle
|
|
36
|
-
of static resources, because you can allow browsers and
|
|
37
|
-
proxies to cache the asset for a very long
|
|
38
|
-
digest over the contents of the asset is fast and
|
|
39
|
-
is reasonably unique to be generated automatically.
|
|
27
|
+
implements concatenation and leaves choosing the minification tool up to
|
|
28
|
+
you. [UglifyJS][UglifyJS2] is a good and fast minifier, for example. The
|
|
29
|
+
plugin connects to the minifier with standard unix pipe, feeding asset
|
|
30
|
+
file contents to it in desired order via standard input, and reads the
|
|
31
|
+
result from standard output.
|
|
32
|
+
|
|
33
|
+
Why is this good? A fingerprint in asset's path is
|
|
34
|
+
the [recommended way][GoogleWebFundamentalsHttpCaching] to handle
|
|
35
|
+
caching of static resources, because you can allow browsers and
|
|
36
|
+
intermediate proxies to cache the asset for a very long
|
|
37
|
+
time. Calculating MD5 digest over the contents of the asset is fast and
|
|
38
|
+
the resulting digest is reasonably unique to be generated automatically.
|
|
40
39
|
|
|
41
40
|
Asset bundling is good for reducing the number of requests to the
|
|
42
41
|
backend upon page load. The minification of stylesheets and JavaScript
|
|
43
|
-
sources makes asset sizes smaller and thus faster to load over
|
|
44
|
-
network.
|
|
42
|
+
sources makes asset sizes smaller and thus faster to load over network.
|
|
45
43
|
|
|
46
44
|
## Usage
|
|
47
45
|
|
|
48
46
|
The plugin ships as a [RubyGem][MinibundleGem]. To install:
|
|
49
47
|
|
|
50
|
-
|
|
51
|
-
$ gem install jekyll-minibundle
|
|
52
|
-
```
|
|
48
|
+
1. Add the following line to the [Gemfile] of your site:
|
|
53
49
|
|
|
54
|
-
|
|
55
|
-
|
|
50
|
+
``` ruby
|
|
51
|
+
gem 'jekyll-minibundle'
|
|
52
|
+
```
|
|
56
53
|
|
|
57
|
-
|
|
58
|
-
[configuration file][JekyllConf] of your Jekyll site project
|
|
59
|
-
(`_config.yml`):
|
|
54
|
+
2. Run `bundle install`.
|
|
60
55
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
56
|
+
3. Instruct Jekyll to load the gem by adding this line to the
|
|
57
|
+
[configuration file][JekyllConf] of your site (`_config.yml`):
|
|
58
|
+
|
|
59
|
+
``` yaml
|
|
60
|
+
plugins:
|
|
61
|
+
- jekyll/minibundle
|
|
62
|
+
```
|
|
64
63
|
|
|
65
|
-
|
|
64
|
+
(Use the `gems` key instead of `plugins` for Jekyll older than v3.5.0.)
|
|
65
|
+
|
|
66
|
+
An alternative to using the `plugins` configuration option is to add
|
|
66
67
|
`_plugins/minibundle.rb` file to your site project with this line:
|
|
67
68
|
|
|
68
69
|
``` ruby
|
|
@@ -70,90 +71,168 @@ require 'jekyll/minibundle'
|
|
|
70
71
|
```
|
|
71
72
|
|
|
72
73
|
You must allow Jekyll to use custom plugins. That is, do not enable
|
|
73
|
-
Jekyll's `safe`
|
|
74
|
+
Jekyll's `safe` configuration option.
|
|
74
75
|
|
|
75
76
|
### Asset fingerprinting
|
|
76
77
|
|
|
77
|
-
If you just want to have
|
|
78
|
-
`ministamp` tag:
|
|
78
|
+
If you just want to have an MD5 fingerprint in your asset's path, use
|
|
79
|
+
`ministamp` [Liquid] tag in a Liquid template file. For example:
|
|
79
80
|
|
|
80
|
-
```
|
|
81
|
-
<link href="{{ site.baseurl }}{% ministamp _assets/site.css assets/site.css %}"
|
|
81
|
+
``` liquid
|
|
82
|
+
<link rel="stylesheet" href="{{ site.baseurl }}/{% ministamp _assets/site.css assets/site.css %}" media="screen, projection">
|
|
82
83
|
```
|
|
83
84
|
|
|
84
|
-
|
|
85
|
-
file
|
|
85
|
+
When it's time to render the `ministamp` tag, the plugin copies the
|
|
86
|
+
source file (`_assets/site.css`, the first tag argument) to the
|
|
87
|
+
specified destination path (`assets/site.css`, the second tag argument)
|
|
88
|
+
in Jekyll's site destination directory. The filename will contain a
|
|
89
|
+
fingerprint.
|
|
90
|
+
|
|
91
|
+
The tag outputs the asset destination path, encoded for HTML, into
|
|
92
|
+
Liquid's template rendering outcome. For example, when `site.baseurl` is
|
|
93
|
+
empty:
|
|
86
94
|
|
|
87
95
|
``` html
|
|
88
|
-
<link href="/assets/site-390be921ee0eff063817bb5ef2954300.css"
|
|
96
|
+
<link rel="stylesheet" href="/assets/site-390be921ee0eff063817bb5ef2954300.css" media="screen, projection">
|
|
89
97
|
```
|
|
90
98
|
|
|
91
|
-
Jekyll's output directory will have the asset file at that path.
|
|
92
|
-
|
|
93
99
|
This feature is useful when combined with asset generation tools
|
|
94
|
-
external to Jekyll. For example, you can configure [
|
|
95
|
-
|
|
100
|
+
external to Jekyll. For example, you can configure [Sass] to take input
|
|
101
|
+
files from `_assets/styles/*.scss` and to produce output to
|
|
96
102
|
`_tmp/site.css`. Then, you use `ministamp` tag to copy the file with a
|
|
97
|
-
fingerprint to Jekyll's
|
|
103
|
+
fingerprint to Jekyll's site destination directory:
|
|
98
104
|
|
|
99
|
-
```
|
|
100
|
-
<link href="{{ site.baseurl }}{% ministamp _tmp/site.css assets/site.css %}"
|
|
105
|
+
``` liquid
|
|
106
|
+
<link rel="stylesheet" href="{{ site.baseurl }}/{% ministamp _tmp/site.css assets/site.css %}">
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
#### `ministamp` call syntax
|
|
110
|
+
|
|
111
|
+
The argument for `ministamp` tag must be in [YAML] syntax, and parsing
|
|
112
|
+
the argument as YAML must result either in a String or a Hash. What you
|
|
113
|
+
saw previously was the argument being parsed as a String; it's
|
|
114
|
+
effectively a shorthand version of passing the argument as a Hash with
|
|
115
|
+
certain keys. That is, in the following call:
|
|
116
|
+
|
|
117
|
+
``` liquid
|
|
118
|
+
{% ministamp _tmp/site.css assets/site.css %}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
the argument is a String: `"_tmp/site.css assets/site.css"`. The call is
|
|
122
|
+
equivalent to the following call with Hash argument:
|
|
123
|
+
|
|
124
|
+
``` liquid
|
|
125
|
+
{% ministamp { source_path: _tmp/site.css, destination_path: assets/site.css } %}
|
|
101
126
|
```
|
|
102
127
|
|
|
128
|
+
The Hash argument allows expressing more options and quoting
|
|
129
|
+
`source_path` and `destination_path` values, if needed.
|
|
130
|
+
|
|
131
|
+
The supported keys for the Hash argument are:
|
|
132
|
+
|
|
133
|
+
| Key | Required? | Value type | Value example | Default value | Description |
|
|
134
|
+
| --- | --- | --- | --- | --- | --- |
|
|
135
|
+
| `source_path` | yes | string | `'_tmp/site.css'` | - | The source path of the asset file, relative to the site directory. |
|
|
136
|
+
| `destination_path` | yes | string | `'assets/site.css'` | - | The destination path of the asset file, relative to Jekyll's site destination directory. If the value begins with `/` and `render_basename_only` is `false`, `ministamp`'s output will begin with `/`. |
|
|
137
|
+
| `render_basename_only` | no | boolean | `true` | `false` | If `true`, `ministamp`'s rendered URL will be the basename of the asset destination path. See [Separating asset destination path from generated URL](#separating-asset-destination-path-from-generated-url) for more. |
|
|
138
|
+
|
|
139
|
+
With Hash argument, the plugin processes `source_path` and
|
|
140
|
+
`destination_path` values through a tiny template engine. This allows
|
|
141
|
+
you to use Liquid's variables as input to `ministamp` tag. An example
|
|
142
|
+
with Liquid's [`assign`][LiquidAssignTag] tag:
|
|
143
|
+
|
|
144
|
+
``` liquid
|
|
145
|
+
{% assign asset_dir = 'assets' %}
|
|
146
|
+
<link rel="stylesheet" href="{% ministamp { source_path: _tmp/site.css, destination_path: '{{ asset_dir }}/site.css' } %}">
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The above would use `assets/site.css` as the destination path.
|
|
150
|
+
|
|
151
|
+
Note that you must quote `destination_path`'s value, otherwise YAML does
|
|
152
|
+
not recognize it as a proper string.
|
|
153
|
+
|
|
154
|
+
To refer to Jekyll's configuration options ([`_config.yml`][JekyllConf])
|
|
155
|
+
in the template, prefix the variable name with `site.`. For example, to
|
|
156
|
+
refer to `baseurl` option, use syntax `{{ site.baseurl }}` in the
|
|
157
|
+
template.
|
|
158
|
+
|
|
159
|
+
See [Variable templating](#variable-templating) for details about the
|
|
160
|
+
template syntax.
|
|
161
|
+
|
|
103
162
|
### Asset bundling
|
|
104
163
|
|
|
105
164
|
This is a straightforward way to bundle assets with any minification
|
|
106
165
|
tool that supports reading input from STDIN and writing the output to
|
|
107
|
-
STDOUT. You write the configuration for input sources directly into
|
|
108
|
-
|
|
109
|
-
appear. The
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
Place `minibundle` block
|
|
114
|
-
|
|
166
|
+
STDOUT. You write the configuration for input sources directly into the
|
|
167
|
+
content file where you want the markup tag for the bundle file to
|
|
168
|
+
appear. The markup tag contains the path to the bundle file, and the
|
|
169
|
+
Jekyll's site destination directory will have the bundle file at that
|
|
170
|
+
path. The path will contain an MD5 fingerprint.
|
|
171
|
+
|
|
172
|
+
Place `minibundle` [Liquid] block into the Liquid template file where
|
|
173
|
+
you want the block's generated markup to appear. Write bundling
|
|
174
|
+
configuration inside the block in [YAML] syntax. For example, to bundle
|
|
115
175
|
a set of JavaScript sources:
|
|
116
176
|
|
|
117
177
|
``` text
|
|
118
178
|
{% minibundle js %}
|
|
119
179
|
source_dir: _assets/scripts
|
|
120
180
|
destination_path: assets/site
|
|
121
|
-
baseurl: {{ site.baseurl }}
|
|
181
|
+
baseurl: '{{ site.baseurl }}/'
|
|
122
182
|
assets:
|
|
123
183
|
- dependency
|
|
124
184
|
- app
|
|
125
185
|
attributes:
|
|
126
186
|
id: my-scripts
|
|
187
|
+
async:
|
|
127
188
|
{% endminibundle %}
|
|
128
189
|
```
|
|
129
190
|
|
|
130
|
-
Then, specify the command for launching your favorite minifier in
|
|
191
|
+
Then, specify the command for launching your favorite minifier in
|
|
192
|
+
`_config.yml`:
|
|
131
193
|
|
|
132
194
|
``` yaml
|
|
133
|
-
baseurl:
|
|
195
|
+
baseurl: ''
|
|
134
196
|
|
|
135
197
|
minibundle:
|
|
136
198
|
minifier_commands:
|
|
137
|
-
js: node_modules/.bin/uglifyjs
|
|
199
|
+
js: node_modules/.bin/uglifyjs
|
|
138
200
|
```
|
|
139
201
|
|
|
140
|
-
|
|
202
|
+
When it's time to render the `minibundle` block, the plugin launches the
|
|
203
|
+
minifier and connects to it with a Unix pipe. The plugin feeds the
|
|
204
|
+
contents of the asset files in `source_dir` directory as input to the
|
|
205
|
+
minifier (STDIN). The feeding order is the order of the files in the
|
|
206
|
+
`assets` key in the block configuration. The plugin expects the minifier
|
|
207
|
+
to produce output (STDOUT) and writes it to the file at
|
|
208
|
+
`destination_path` in Jekyll's site destination directory. The filename
|
|
209
|
+
will contain a fingerprint.
|
|
210
|
+
|
|
211
|
+
The block outputs `<link>` (for `css` type) or `<script>` (for `js`
|
|
212
|
+
type) HTML element into Liquid's template rendering outcome. Continuing
|
|
213
|
+
the example above, the block's output will be:
|
|
141
214
|
|
|
142
215
|
``` html
|
|
143
|
-
<script src="/assets/site-8e764372a0dbd296033cb2a416f064b5.js" type="text/javascript" id="my-scripts"></script>
|
|
216
|
+
<script src="/assets/site-8e764372a0dbd296033cb2a416f064b5.js" type="text/javascript" id="my-scripts" async></script>
|
|
144
217
|
```
|
|
145
218
|
|
|
146
|
-
You can pass custom attributes, like `id="my-scripts"`
|
|
147
|
-
generated markup with `attributes` map inside the
|
|
219
|
+
You can pass custom attributes, like `id="my-scripts"` and `async`
|
|
220
|
+
above, to the generated markup with `attributes` map inside the
|
|
221
|
+
`minibundle` block.
|
|
222
|
+
|
|
223
|
+
As shown above for the `baseurl` key, you can use Liquid template syntax
|
|
224
|
+
inside the contents of the block. Liquid renders block contents before
|
|
225
|
+
`minibundle` block gets the turn to render itself. Just ensure that
|
|
226
|
+
block contents will result in valid YAML.
|
|
148
227
|
|
|
149
|
-
For bundling CSS assets,
|
|
150
|
-
|
|
228
|
+
For bundling CSS assets, use `css` as the argument to the `minibundle`
|
|
229
|
+
block:
|
|
151
230
|
|
|
152
231
|
``` text
|
|
153
232
|
{% minibundle css %}
|
|
154
233
|
source_dir: _assets/styles
|
|
155
234
|
destination_path: assets/site
|
|
156
|
-
baseurl: {{ site.baseurl }}
|
|
235
|
+
baseurl: '{{ site.baseurl }}/'
|
|
157
236
|
assets:
|
|
158
237
|
- reset
|
|
159
238
|
- common
|
|
@@ -168,9 +247,25 @@ And then specify the minifier command in `_config.yml`:
|
|
|
168
247
|
minibundle:
|
|
169
248
|
minifier_commands:
|
|
170
249
|
css: _bin/remove_whitespace
|
|
171
|
-
js: node_modules/.bin/uglifyjs
|
|
250
|
+
js: node_modules/.bin/uglifyjs
|
|
172
251
|
```
|
|
173
252
|
|
|
253
|
+
#### `minibundle` call syntax
|
|
254
|
+
|
|
255
|
+
Use `css` or `js` as the argument to the opening tag, for example `{% minibundle css %}`.
|
|
256
|
+
|
|
257
|
+
The block contents must be in [YAML] syntax. The supported keys are:
|
|
258
|
+
|
|
259
|
+
| Key | Value type | Value example | Default value | Description |
|
|
260
|
+
| --- | --- | --- | --- | --- |
|
|
261
|
+
| `source_dir` | string | - | `'_assets'` | The source directory of `assets`, relative to the site directory. You can use period (`.`) to select the site directory itself. |
|
|
262
|
+
| `assets` | array of strings | `['deps/one', 'deps/two', 'app']` | `[]` | Array of assets relative to `source_dir` directory, without type extension. These are the asset files to be bundled, in order, into one bundle destination file. |
|
|
263
|
+
| `destination_path` | string | - | `'assets/site'` | The destination path of the bundle file, without type extension, relative to Jekyll's site destination directory. If the value begins with `/` and `baseurl` is empty, `baseurl` will be set to `'/'` implicitly. |
|
|
264
|
+
| `baseurl` | string | `'{{ site.baseurl }}/'` | `''` | If nonempty, the bundle destination URL inside `minibundle`'s rendered HTML element will be this value prepended to the destination path of the bundle file. Ignored if `destination_baseurl` is nonempty. |
|
|
265
|
+
| `destination_baseurl` | string | `'{{ site.cdn_baseurl }}/'` | `''` | If nonempty, the bundle destination URL inside `minibundle`'s rendered HTML element will be this value prepended to the basename of the bundle destination path. See [Separating asset destination path from generated URL](#separating-asset-destination-path-from-generated-url) for more. |
|
|
266
|
+
| `attributes` | map of keys to string values | `{id: my-link, media: screen}` | `{}` | Custom HTML element attributes to be added to `minibundle`'s rendered HTML element. |
|
|
267
|
+
| `minifier_cmd` | string | `'node_modules/.bin/uglifyjs'` | - | Minifier command specific to this bundle. See [Minifier command specification](#minifier-command-specification) for more. |
|
|
268
|
+
|
|
174
269
|
### Minifier command specification
|
|
175
270
|
|
|
176
271
|
You can specify minifier commands in three places:
|
|
@@ -181,24 +276,24 @@ You can specify minifier commands in three places:
|
|
|
181
276
|
minibundle:
|
|
182
277
|
minifier_commands:
|
|
183
278
|
css: _bin/remove_whitespace
|
|
184
|
-
js: node_modules/.bin/uglifyjs
|
|
279
|
+
js: node_modules/.bin/uglifyjs
|
|
185
280
|
```
|
|
186
281
|
|
|
187
282
|
2. as environment variables:
|
|
188
283
|
|
|
189
284
|
``` bash
|
|
190
285
|
export JEKYLL_MINIBUNDLE_CMD_CSS=_bin/remove_whitespace
|
|
191
|
-
export JEKYLL_MINIBUNDLE_CMD_JS="node_modules/.bin/uglifyjs
|
|
286
|
+
export JEKYLL_MINIBUNDLE_CMD_JS="node_modules/.bin/uglifyjs"
|
|
192
287
|
```
|
|
193
288
|
|
|
194
|
-
3. inside the minibundle block with `minifier_cmd`
|
|
289
|
+
3. inside the `minibundle` block with `minifier_cmd` option, allowing
|
|
195
290
|
blocks to have different commands from each other:
|
|
196
291
|
|
|
197
292
|
``` text
|
|
198
293
|
{% minibundle js %}
|
|
199
294
|
source_dir: _assets/scripts
|
|
200
295
|
destination_path: assets/site
|
|
201
|
-
minifier_cmd: node_modules/.bin/uglifyjs
|
|
296
|
+
minifier_cmd: node_modules/.bin/uglifyjs
|
|
202
297
|
assets:
|
|
203
298
|
- dependency
|
|
204
299
|
- app
|
|
@@ -209,50 +304,73 @@ You can specify minifier commands in three places:
|
|
|
209
304
|
|
|
210
305
|
These ways of specification are listed in increasing order of
|
|
211
306
|
specificity. Should multiple commands apply to a block, the most
|
|
212
|
-
specific one wins. For example, the `minifier_cmd`
|
|
213
|
-
|
|
307
|
+
specific one wins. For example, the `minifier_cmd` option inside `{%
|
|
308
|
+
minibundle js }%` block overrides the setting in
|
|
214
309
|
`$JEKYLL_MINIBUNDLE_CMD_JS` environment variable.
|
|
215
310
|
|
|
216
311
|
### Recommended directory layout
|
|
217
312
|
|
|
218
313
|
It's recommended that you exclude the files you use as asset sources
|
|
219
314
|
from Jekyll itself. Otherwise, you end up with duplicate files in the
|
|
220
|
-
|
|
315
|
+
site destination directory.
|
|
221
316
|
|
|
222
317
|
For example, in the following snippet we're using `assets/src.css` as
|
|
223
318
|
asset source to `ministamp` tag:
|
|
224
319
|
|
|
225
|
-
```
|
|
226
|
-
<!-- BAD: unless assets dir is excluded, both src.css and dest.css will be copied to
|
|
227
|
-
<link href="{{ site.baseurl }}{% ministamp assets/src.css assets/dest.css %}"
|
|
320
|
+
``` liquid
|
|
321
|
+
<!-- BAD: unless assets dir is excluded, both src.css and dest.css will be copied to site destination directory -->
|
|
322
|
+
<link rel="stylesheet" href="{{ site.baseurl }}/{% ministamp assets/src.css assets/dest.css %}" media="screen, projection">
|
|
228
323
|
```
|
|
229
324
|
|
|
230
|
-
By default, Jekyll includes this file to the
|
|
231
|
-
result, there will be both `src.css` and
|
|
232
|
-
`_site/assets/` directory, which you probably
|
|
325
|
+
By default, Jekyll includes this file to the site destination
|
|
326
|
+
directory. As a result, there will be both `src.css` and
|
|
327
|
+
`dest-<md5>.css` files in `_site/assets/` directory, which you probably
|
|
328
|
+
do not want.
|
|
233
329
|
|
|
234
|
-
In order to avoid this, exclude the asset source file from
|
|
235
|
-
|
|
236
|
-
|
|
330
|
+
In order to avoid this, exclude the asset source file from Jekyll.
|
|
331
|
+
Because Jekyll's site generation excludes underscore directories (that
|
|
332
|
+
is, directories whose name begins with underscore character), consider
|
|
333
|
+
using the following directory layout:
|
|
237
334
|
|
|
238
335
|
* `_assets/` for JavaScript and CSS assets handled by the plugin that
|
|
239
336
|
are in version control
|
|
240
|
-
* `_tmp/` for temporary JavaScript and CSS assets handled by the
|
|
241
|
-
|
|
242
|
-
files)
|
|
337
|
+
* `_tmp/` for temporary JavaScript and CSS assets handled by the plugin
|
|
338
|
+
that are not in version control (for example, Sass output files)
|
|
243
339
|
* `assets/` for images and other assets handled by Jekyll directly
|
|
244
340
|
|
|
341
|
+
However, Jekyll's watch mode (auto-regeneration) does monitor files
|
|
342
|
+
inside underscore directories. If such a file is modified, the watch
|
|
343
|
+
mode triggers site generation. For Minibundle's functionality, this is
|
|
344
|
+
beneficial: it allows the plugin to check if assets need to be updated
|
|
345
|
+
to the site destination directory.
|
|
346
|
+
|
|
347
|
+
The `exclude` [Jekyll configuration][JekyllConf] option affects Jekyll's
|
|
348
|
+
watch mode. Given the recommended directory layout above, if you set the
|
|
349
|
+
following in `_config.yml`:
|
|
350
|
+
|
|
351
|
+
``` yaml
|
|
352
|
+
exclude:
|
|
353
|
+
- _assets
|
|
354
|
+
- _tmp
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
Then Jekyll won't see if files inside those directories have changed and
|
|
358
|
+
the plugin won't get the chance to update assets to the site destination
|
|
359
|
+
directory. So, don't explicitly exclude `_assets` and `_tmp`
|
|
360
|
+
directories.
|
|
361
|
+
|
|
245
362
|
See [Jekyll configuration][JekyllConf] for more about excluding files
|
|
246
363
|
and directories.
|
|
247
364
|
|
|
248
365
|
### Development mode
|
|
249
366
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
`minibundle` block
|
|
255
|
-
|
|
367
|
+
If you set `$JEKYLL_MINIBUNDLE_MODE` environment variable to
|
|
368
|
+
`development`, then the plugin will copy asset files as is to Jekyll's
|
|
369
|
+
site destination directory and omit fingerprinting.
|
|
370
|
+
|
|
371
|
+
The development mode changes `minibundle` block's `destination_path`
|
|
372
|
+
option to be the base directory for files mentioned in `assets`
|
|
373
|
+
option. This is useful in development workflow, where you need the
|
|
256
374
|
filenames and line numbers of the original asset sources.
|
|
257
375
|
|
|
258
376
|
``` bash
|
|
@@ -266,27 +384,130 @@ minibundle:
|
|
|
266
384
|
mode: development
|
|
267
385
|
```
|
|
268
386
|
|
|
269
|
-
Should both be defined, the setting from the environment variable
|
|
270
|
-
|
|
387
|
+
Should both be defined, the setting from the environment variable wins.
|
|
388
|
+
|
|
389
|
+
### Variable templating
|
|
390
|
+
|
|
391
|
+
The template engine used by `ministamp` tag's Hash argument has syntax
|
|
392
|
+
resembling the ones of [Liquid] and [Mustache], with `{{` and `}}` tags
|
|
393
|
+
surrounding the variable to be substituted into the output string. For
|
|
394
|
+
example, given Liquid variable `var = 'foo'`, the template `begin{{ var
|
|
395
|
+
}}end` results in `beginfooend`.
|
|
396
|
+
|
|
397
|
+
The engine supports variable substitution only. It does not support
|
|
398
|
+
other expressions. If you need to, you can write complex expressions in
|
|
399
|
+
Liquid, store the result to a variable, and use the variable in the
|
|
400
|
+
template.
|
|
401
|
+
|
|
402
|
+
If you need literal `{` or `}` characters in the template, you can
|
|
403
|
+
escape them with backslash. For example, `\{` results in `{` in the
|
|
404
|
+
output. To output backslash character itself, write it twice: `\\`
|
|
405
|
+
results in `\` in the output.
|
|
406
|
+
|
|
407
|
+
Inside variable subsitution (between `{{` and `}}`), anything before the
|
|
408
|
+
closing `}}` tag is interpreted as part of the variable name, except
|
|
409
|
+
that the engine removes any leading and trailing whitespace from the
|
|
410
|
+
name. For example, in the template `{{ var } }}`, `var }` is treated as
|
|
411
|
+
the name of the variable.
|
|
412
|
+
|
|
413
|
+
A reference to undefined variable results in empty string. For example,
|
|
414
|
+
`begin{{ nosuch }}end` will output `beginend` if there's no variable
|
|
415
|
+
named `nosuch`.
|
|
416
|
+
|
|
417
|
+
### Separating asset destination path from generated URL
|
|
418
|
+
|
|
419
|
+
Use `render_basename_only: true` option of `ministamp` tag and
|
|
420
|
+
`destination_baseurl` option of `minibundle` block to separate the
|
|
421
|
+
destination path of the asset file from the generated URL of the
|
|
422
|
+
asset. This allows you to serve the asset from a separate domain, for
|
|
423
|
+
example.
|
|
424
|
+
|
|
425
|
+
Example usage, with the following content in `_config.yml`:
|
|
426
|
+
|
|
427
|
+
``` yaml
|
|
428
|
+
cdn_baseurl: 'https://cdn.example.com'
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
For `ministamp` tag:
|
|
432
|
+
|
|
433
|
+
``` liquid
|
|
434
|
+
<link rel="stylesheet" href="{{ site.cdn_baseurl }}/css/{% ministamp { source_path: '_tmp/site.css', destination_path: assets/site.css, render_basename_only: true } %}">
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
The asset file will be in Jekyll's site destination directory with path
|
|
438
|
+
`assets/site-ff9c63f843b11f9c3666fe46caaddea8.css`, and Liquid's
|
|
439
|
+
rendering will result in:
|
|
440
|
+
|
|
441
|
+
``` html
|
|
442
|
+
<link rel="stylesheet" href="https://cdn.example.com/css/site-ff9c63f843b11f9c3666fe46caaddea8.css">
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
For `minibundle` block:
|
|
446
|
+
|
|
447
|
+
``` liquid
|
|
448
|
+
{% minibundle js %}
|
|
449
|
+
source_dir: _assets/scripts
|
|
450
|
+
destination_path: assets/site
|
|
451
|
+
destination_baseurl: '{{ site.cdn_baseurl }}/js/'
|
|
452
|
+
assets:
|
|
453
|
+
- dependency
|
|
454
|
+
- app
|
|
455
|
+
{% endminibundle %}
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
The bundle file will be in Jekyll's site destination directory with path
|
|
459
|
+
`assets/site-4782a1f67803038d4f8351051e67deb8.js`, and Liquid's
|
|
460
|
+
rendering will result in:
|
|
461
|
+
|
|
462
|
+
``` html
|
|
463
|
+
<script type="text/javascript" src="https://cdn.example.com/js/site-4782a1f67803038d4f8351051e67deb8.js"></script>
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
### Capturing Liquid output
|
|
467
|
+
|
|
468
|
+
Use Liquid's [`capture`][LiquidCaptureBlock] block to store output
|
|
469
|
+
rendered inside the block to a variable, as a string. Then you can
|
|
470
|
+
process the string as you like.
|
|
471
|
+
|
|
472
|
+
For example:
|
|
473
|
+
|
|
474
|
+
``` liquid
|
|
475
|
+
{% capture site_css %}{% ministamp _assets/site.css assets/site.css %}{% endcapture %}
|
|
476
|
+
<link rel="stylesheet" href="{{ site_css | remove_first: "assets/" }}">
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
Liquid's rendering outcome:
|
|
480
|
+
|
|
481
|
+
``` html
|
|
482
|
+
<link rel="stylesheet" href="site-390be921ee0eff063817bb5ef2954300.css">
|
|
483
|
+
```
|
|
271
484
|
|
|
272
485
|
## Example site
|
|
273
486
|
|
|
274
|
-
See the
|
|
487
|
+
See the sources of [an example site][JekyllMinibundleExampleSite].
|
|
275
488
|
|
|
276
489
|
## Known caveats
|
|
277
490
|
|
|
278
|
-
The plugin does not work with Jekyll's incremental rebuild feature
|
|
279
|
-
option `--incremental`).
|
|
491
|
+
The plugin does not work with Jekyll's incremental rebuild feature
|
|
492
|
+
(Jekyll option `--incremental`).
|
|
280
493
|
|
|
281
494
|
## License
|
|
282
495
|
|
|
283
|
-
MIT. See
|
|
496
|
+
MIT. See [LICENSE.txt].
|
|
284
497
|
|
|
285
|
-
[
|
|
286
|
-
[
|
|
287
|
-
[GoogleWebFundamentalsHttpCaching]: https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/http-caching#invalidating-and-updating-cached-responses
|
|
288
|
-
[MinibundleGem]: https://rubygems.org/gems/jekyll-minibundle
|
|
289
|
-
[MinibundleBuild]: https://travis-ci.org/tkareine/jekyll-minibundle
|
|
290
|
-
[Jekyll]: https://jekyllrb.com/
|
|
498
|
+
[Gemfile]: https://bundler.io/gemfile.html
|
|
499
|
+
[GoogleWebFundamentalsHttpCaching]: https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/http-caching#invalidating_and_updating_cached_responses
|
|
291
500
|
[JekyllConf]: https://jekyllrb.com/docs/configuration/
|
|
501
|
+
[JekyllMinibundleExampleSite]: https://github.com/tkareine/jekyll-minibundle-example
|
|
502
|
+
[Jekyll]: https://jekyllrb.com/
|
|
503
|
+
[LICENSE.txt]: https://raw.githubusercontent.com/tkareine/jekyll-minibundle/master/LICENSE.txt
|
|
504
|
+
[LiquidAssignTag]: https://shopify.github.io/liquid/tags/variable/#assign
|
|
505
|
+
[LiquidCaptureBlock]: https://shopify.github.io/liquid/tags/variable/#capture
|
|
506
|
+
[Liquid]: https://shopify.github.io/liquid/
|
|
507
|
+
[MD5]: https://en.wikipedia.org/wiki/MD5
|
|
508
|
+
[MinibundleCI]: https://github.com/tkareine/jekyll-minibundle/actions?workflow=CI
|
|
509
|
+
[MinibundleGem]: https://rubygems.org/gems/jekyll-minibundle
|
|
510
|
+
[Mustache]: https://mustache.github.io/
|
|
511
|
+
[Sass]: https://sass-lang.com/
|
|
292
512
|
[UglifyJS2]: https://github.com/mishoo/UglifyJS2
|
|
513
|
+
[YAML]: https://yaml.org/
|