jekyll-minibundle 2.0.1 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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/
|