jekyll-minibundle 2.1.2 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8c11f2890adfcdd3cc6902ddf8f1449f3e1b1721
-  data.tar.gz: 8676586c08adf47c8962dcee2214cfba11eeff55
+  metadata.gz: 774c41fc9b64c1637821907e5cbd27b1cc57fb3c
+  data.tar.gz: 507bd31ab11d4c7b3c7944116af11ff63fd27f0c
 SHA512:
-  metadata.gz: 3915fc23411307ba14bf2e700fe40ab7197aa155397027b6bcd65a3cb31efaa631df9aea43545b5584bf55e0ed63f33376e5e0f6a3344db4a3d55fa627cd37e3
-  data.tar.gz: d159b2a770dd15d261bdf6b2a6661a866ea73f3a76188d2a85bb62e061f875809558f53d46e0726e494ca2a0cad68ce7a12c006a5d0488c3f9b673f81588db61
+  metadata.gz: 95c4db067065b679412388f72629cf3eafa12cf99c1d6bad244715b2917fca09f41e13f97e6d3ee28d7fc2df191a7532576fe999327cc2c2f7e6100ea6488ff8
+  data.tar.gz: 26b81832194d0e5d86dc1d99ecdb6de65e463c8ef228190b7b84e98dfdf63ae908e4be5f59bd1ba1a4bdb488ada439cf9b29079604d5e08776819aa21f4985bd

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+# 2.2.0 / 2017-03-10
+
+* Treat `ministamp` tag's argument as YAML, resulting either in String
+  or Hash type of argument after YAML parsing. If argument is of Hash
+  type, render values with Liquid-like templating support, allowing
+  rendering Liquid variables. This change is backwards compatible.
+
+* Add support for separating asset destination path from the generated
+  asset URL. See `render_basename_only` option of `ministamp` tag and
+  `destination_baseurl` option of `minibundle` block.
+
+* Escape the URLs generated by `ministamp` tag and `minibundle` block.
+
+* Quote paths in error messages more consistently.
+
+* Show better error messages in various situations when asset source
+  file does not exist.
+
+* Compatibility: conform to Jekyll 3.4.2's StaticFile public API.
+
 # 2.1.2 / 2017-02-28
 
 * Bug fix: remove unnecessary '.' path component from asset destination
@@ -23,31 +43,36 @@
   ```
 
 * Bug fix (related to above): don't let Jekyll's watch mode
-  (auto-regenration) remove asset from generated site directory when
+  (auto-regeneration) remove asset from generated site directory when
   asset destination path has no subdirectory.
-* Show bundle destination path in bundling log message
+
+* Show bundle destination path in bundling log message.
 
 # 2.1.1 / 2017-01-14
 
 * Fix the file permissions of `minibundle` block's output file to
   respect umask setting. Bug report from Alfonse Surigao.
-* Compatibility: conform to Jekyll 3.3's StaticFile public API
+
+* Compatibility: conform to Jekyll 3.3's StaticFile public API.
 
 # 2.1.0 / 2016-05-04
 
 * Allow attributes without values. Useful for `async` attribute, for
   example. Pull Request #7 by Sam (@codewisdom).
-* Ensure attribute value conversion to string
+
+* Ensure attribute value conversion to string.
 
 # 2.0.1 / 2016-04-06
 
-* Fix Jekyll version requirement check to be more reliable
+* Fix Jekyll version requirement check to be more reliable.
 
 # 2.0.0 / 2016-04-01
 
-* Drop support for Jekyll versions below 3
+* Drop support for Jekyll versions below 3.
+
 * Remove unused asset cache entries and temporary files when Jekyll
-  rebuilds the site
+  rebuilds the site.
+
 * Document a known caveat: the plugin doesn't work with Jekyll's
   incremental rebuild feature.
 
@@ -55,26 +80,33 @@
 
 * Log the last 2000 bytes of minifier's STDOUT output if the minifier
   command fails. Pull Request #6 by Martin Nordholts (@Enselic).
+
 * Allow prepending base URL for the destination path of `minibundle`
-  block
-* Drop Ruby MRI 1.9 support because Jekyll 3 does not support it
+  block.
+
+* Drop Ruby MRI 1.9 support because Jekyll 3 does not support it.
+
 * Fix issues in asset reloading in Jekyll's watch (auto-regeneration)
-  mode, doing bundling and asset fingerprinting again
+  mode, doing bundling and asset fingerprinting again.
 
 # 1.5.1 / 2015-01-29
 
 * Improve future compatibility with Jekyll. Minibundle has classes
   adhering to `Jekyll::StaticFile` interface, and some method
   implementations of the interface were missing.
-* Small refactorings and test improvements
+
+* Small refactorings and test improvements.
 
 # 1.5.0 / 2014-07-27
 
 * Support minifier command specification in `_config.yml` and inside
   `minibundle` block. Issue #4 by Phillip Smith (@phillipadsmith).
-* Support enabling development mode from `_config.yml`
-* Add argument validation to `minibundle` block and `ministamp` tag
-* Document how to load the gem with Jekyll's `gems` config setting
+
+* Support enabling development mode from `_config.yml`.
+
+* Add argument validation to `minibundle` block and `ministamp` tag.
+
+* Document how to load the gem with Jekyll's `gems` config setting.
 
 # 1.4.6 / 2014-05-10
 
@@ -84,14 +116,17 @@
 # 1.4.5 / 2014-05-10
 
 * Use SafeYAML to load user input from `minibundle` block for
-  consistent behavior with Jekyll and for security
-* Clean log messages: show relative paths when bundling assets
+  consistent behavior with Jekyll and for security.
+
+* Clean log messages: show relative paths when bundling assets.
+
 * Add missing implementations of `relative_path` and `to_liquid`
   methods from Jekyll's StaticFile API (introduced in Jekyll v1.5.0),
   allowing Minibundle to behave better with other Jekyll
   plugins. Issue #3 by Michael Rose (@mmistakes).
+
 * Fix Ruby deprecation warnings (use `File.exist?` instead of
-  `File.exists?`)
+  `File.exists?`).
 
 # 1.4.4 / 2014-01-16
 
@@ -102,12 +137,17 @@
 
 # 1.4.3 / 2014-01-16
 
-* Do not leak read pipe file descriptor upon minifier command failure
-* Loosen version constraints for development gem dependencies
-* Clarify documentation
-* Fix some Ruby coding style issues
-* Minor internal state handling improvements
-* Clarify tests, increase test coverage
+* Do not leak read pipe file descriptor upon minifier command failure.
+
+* Loosen version constraints for development gem dependencies.
+
+* Clarify documentation.
+
+* Fix some Ruby coding style issues.
+
+* Minor internal state handling improvements.
+
+* Clarify tests, increase test coverage.
 
 # 1.4.2 / 2013-12-28
 
@@ -115,13 +155,15 @@
   unintentional edge case earlier. Now the behavior of touching the
   asset source is consistent with when changing the contents of the
   source.
+
 * Separate tags produced by `minibundle` in development mode with
-  newlines
-* Clarify tests, increase coverage
+  newlines.
+
+* Clarify tests, increase coverage.
 
 # 1.4.1 / 2013-12-27
 
-* Add missing files to gem package
+* Add missing files to gem package.
 
 # 1.4.0 / 2013-12-27
 
@@ -137,37 +179,49 @@
   in Jekyll. Otherwise, we would potentially get to inconsistencies in
   Jekyll's watch mode. See "Jekyll static file restriction" in
   README.md. Issue #2 by Austin Grigg (@agrigg).
-* Upgrade development dependencies
+
+* Upgrade development dependencies.
 
 # 1.2.0 / 2013-09-29
 
-* If Jekyll's logger is available, use it for nice output when bundling
-* Upgrade development dependencies
-* Simplify `BundleFile` class implementation
+* If Jekyll's logger is available, use it for nice output when bundling.
+
+* Upgrade development dependencies.
+
+* Simplify `BundleFile` class implementation.
 
 # 1.1.0 / 2013-02-27
 
-* `ministamp` tag omits fingerprint in development mode
-* Clarify documentation
+* `ministamp` tag omits fingerprint in development mode.
+
+* Clarify documentation.
+
 * Comply with (Gemnasium) conventions for changelogs. Pull Request #1
   by Teemu Matilainen (@tmatilai).
-* Bug fix: do not bundle assets when nonrelated files change
-* Bug fix: do not bundle assets twice upon startup
+
+* Bug fix: do not bundle assets when nonrelated files change.
+
+* Bug fix: do not bundle assets twice upon startup.
 
 # 1.0.0 / 2013-02-15
 
 * Add development mode, where `minibundle` block will copy each asset
-  as-is to the destination directory
-* Clarify documentation
-* Increase test coverage
+  as-is to the destination directory.
+
+* Clarify documentation.
+
+* Increase test coverage.
 
 # 0.2.0 / 2012-12-15
 
-* Escape the values of custom attributes given in `minibundle` block
-* Add semicolons between each JavaScript asset in bundling
-* Show error in page output if asset bundling command failed
+* Escape the values of custom attributes given in `minibundle` block.
+
+* Add semicolons between each JavaScript asset in bundling.
+
+* Show error in page output if asset bundling command failed.
 
 # 0.1.0 / 2012-12-07
 
-* Add `ministamp` tag and `minibundle` block for Jekyll
-* First release
+* Add `ministamp` tag and `minibundle` block for Jekyll.
+
+* First release.

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2012-2016 Tuomas Kareinen
+Copyright (c) 2012-2017 Tuomas Kareinen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -60,7 +60,7 @@ Then, instruct Jekyll to load the gem by adding this line to the
 gems: ['jekyll/minibundle']
 ```
 
-An alternative to using the `gems` configuration setting is to add
+An alternative to using the `gems` configuration option is to add
 `_plugins/minibundle.rb` file to your site project with this line:
 
 ``` ruby
@@ -68,38 +68,94 @@ require 'jekyll/minibundle'
 ```
 
 You must allow Jekyll to use custom plugins. That is, do not enable
-Jekyll's `safe` setting.
+Jekyll's `safe` option.
 
 ### Asset fingerprinting
 
 If you just want to have an MD5 fingerprint in your asset's path, use
-`ministamp` [Liquid][Liquid] tag. For example:
+`ministamp` [Liquid][Liquid] tag in a Liquid template file. For example:
 
-``` html
-<link href="{{ site.baseurl }}{% ministamp _assets/site.css assets/site.css %}" rel="stylesheet" media="screen, projection">
+``` liquid
+<link rel="stylesheet" href="{{ site.baseurl }}/{% ministamp _assets/site.css assets/site.css %}" media="screen, projection">
 ```
 
 When it's time to render the `ministamp` tag, the plugin copies the
 source file (`_assets/site.css`, the first tag argument) to the
 specified destination path (`assets/site.css`, the second tag argument)
-in Jekyll's output directory. The filename will contain a fingerprint.
+in Jekyll's site destination directory. The filename will contain a
+fingerprint.
 
-Tag output, when `site.baseurl` is `/`:
+The tag outputs the asset destination path, encoded for HTML, into
+Liquid's template rendering outcome. For example, when `site.baseurl` is
+empty:
 
 ``` html
-<link href="/assets/site-390be921ee0eff063817bb5ef2954300.css" rel="stylesheet" media="screen, projection">
+<link rel="stylesheet" href="/assets/site-390be921ee0eff063817bb5ef2954300.css" media="screen, projection">
 ```
 
 This feature is useful when combined with asset generation tools
 external to Jekyll. For example, you can configure [Sass][Sass] to take
 input files from `_assets/styles/*.scss` and to produce output to
 `_tmp/site.css`. Then, you use `ministamp` tag to copy the file with a
-fingerprint to Jekyll's output directory:
+fingerprint to Jekyll's site destination directory:
 
-``` html
-<link href="{{ site.baseurl }}{% ministamp _tmp/site.css assets/site.css %}" rel="stylesheet">
+``` liquid
+<link rel="stylesheet" href="{{ site.baseurl }}/{% ministamp _tmp/site.css assets/site.css %}">
+```
+
+#### `ministamp` call syntax
+
+The argument for `ministamp` tag must be in [YAML][YAML] syntax, and
+parsing the argument as YAML must result either in a String or a
+Hash. What you saw previously was the argument being parsed as a String;
+it's effectively a shorthand version of passing the argument as a Hash
+with certain keys. That is, in the following call:
+
+``` liquid
+{% ministamp _tmp/site.css assets/site.css %}
+```
+
+the argument is a String: `"_tmp/site.css assets/site.css"`. The call is
+equivalent to the following call with Hash argument:
+
+``` liquid
+{% ministamp { source_path: _tmp/site.css, destination_path: assets/site.css } %}
 ```
 
+The Hash argument allows expressing more options and quoting
+`source_path` and `destination_path` values, if needed.
+
+The supported keys for the Hash argument are:
+
+| Key | Required? | Value type | Value example | Default value | Description |
+| --- | --- | --- | --- | --- | --- |
+| `source_path` | yes | string | `'_tmp/site.css'` | - | The source path of the asset file, relative to the site directory. |
+| `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 `/`. |
+| `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. |
+
+With Hash argument, the plugin processes `source_path` and
+`destination_path` values through a tiny template engine. This allows
+you to use Liquid's variables as input to `ministamp` tag. An example
+with Liquid's [`assign`][LiquidAssignTag] tag:
+
+``` liquid
+{% assign asset_dir = 'assets' %}
+<link rel="stylesheet" href="{% ministamp { source_path: _tmp/site.css, destination_path: '{{ asset_dir }}/site.css' } %}">
+```
+
+The above would use `assets/site.css` as the destination path.
+
+Note that you must quote `destination_path`'s value, otherwise YAML does
+not recognize it as a proper string.
+
+To refer to Jekyll's configuration options ([`_config.yml`][JekyllConf])
+in the template, prefix the variable name with `site.`. For example, to
+refer to `baseurl` option, use syntax `{{ site.baseurl }}` in the
+template.
+
+See [Variable templating](#variable-templating) for details about the
+template syntax.
+
 ### Asset bundling
 
 This is a straightforward way to bundle assets with any minification
@@ -107,19 +163,19 @@ tool that supports reading input from STDIN and writing the output to
 STDOUT. You write the configuration for input sources directly into the
 content file where you want the markup tag for the bundle file to
 appear. The markup tag contains the path to the bundle file, and the
-Jekyll's output directory will have the bundle file at that path. The
-path will contain an MD5 fingerprint.
+Jekyll's site destination directory will have the bundle file at that
+path. The path will contain an MD5 fingerprint.
 
-Place `minibundle` [Liquid][Liquid] block into your content file where
-you want the generated markup to appear. Write bundling configuration
-inside the block in [YAML][YAML] syntax. For example, to bundle a set of
-JavaScript sources:
+Place `minibundle` [Liquid][Liquid] block into the Liquid template file
+where you want the block's generated markup to appear. Write bundling
+configuration inside the block in [YAML][YAML] syntax. For example, to
+bundle a set of JavaScript sources:
 
 ``` text
 {% minibundle js %}
 source_dir: _assets/scripts
 destination_path: assets/site
-baseurl: {{ site.baseurl }}
+baseurl: '{{ site.baseurl }}/'
 assets:
   - dependency
   - app
@@ -133,7 +189,7 @@ Then, specify the command for launching your favorite minifier in
 `_config.yml`:
 
 ``` yaml
-baseurl: /
+baseurl: ''
 
 minibundle:
   minifier_commands:
@@ -146,10 +202,12 @@ contents of the asset files in `source_dir` directory as input to the
 minifier (STDIN). The feeding order is the order of the files in the
 `assets` key in the block configuration. The plugin expects the minifier
 to produce output (STDOUT) and writes it to the file at
-`destination_path` in Jekyll's output directory. The filename will
-contain a fingerprint.
+`destination_path` in Jekyll's site destination directory. The filename
+will contain a fingerprint.
 
-Block output in the content file:
+The block outputs `<link>` (for `css` type) or `<script>` (for `js`
+type) HTML element into Liquid's template rendering outcome. Continuing
+the example above, the block's output will be:
 
 ``` html
 <script src="/assets/site-8e764372a0dbd296033cb2a416f064b5.js" type="text/javascript" id="my-scripts" async></script>
@@ -159,6 +217,11 @@ You can pass custom attributes, like `id="my-scripts"` and `async`
 above, to the generated markup with `attributes` map inside the
 `minibundle` block.
 
+As shown above for the `baseurl` key, you can use Liquid template syntax
+inside the contents of the block. Liquid renders block contents before
+`minibundle` block gets the turn to render itself. Just ensure that
+block contents will result in valid YAML.
+
 For bundling CSS assets, use `css` as the argument to the `minibundle`
 block:
 
@@ -166,7 +229,7 @@ block:
 {% minibundle css %}
 source_dir: _assets/styles
 destination_path: assets/site
-baseurl: {{ site.baseurl }}
+baseurl: '{{ site.baseurl }}/'
 assets:
   - reset
   - common
@@ -184,6 +247,21 @@ minibundle:
     js: node_modules/.bin/uglifyjs -
 ```
 
+#### `minibundle` call syntax
+
+Use `css` or `js` as the argument to the opening tag, for example `{% minibundle css %}`.
+
+The block contents must be in [YAML][YAML] syntax. The supported keys are:
+
+| Key | Value type | Value example | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `source_dir` | string | - | `'_assets'` | The source directory of `assets`, relative to the site directory. |
+| `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. |
+| `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. |
+| `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. |
+| `assets` | array of strings | `['dependency', 'app']` | `[]` | Array of the basenames of assets in `source_dir` directory, without type extension. These are the asset files to be bundled, in order, into one bundle destination file. |
+| `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. |
+
 ### Minifier command specification
 
 You can specify minifier commands in three places:
@@ -204,7 +282,7 @@ You can specify minifier commands in three places:
    export JEKYLL_MINIBUNDLE_CMD_JS="node_modules/.bin/uglifyjs -"
    ```
 
-3. inside the minibundle block with `minifier_cmd` setting, allowing
+3. inside the `minibundle` block with `minifier_cmd` option, allowing
    blocks to have different commands from each other:
 
    ``` text
@@ -222,31 +300,33 @@ You can specify minifier commands in three places:
 
 These ways of specification are listed in increasing order of
 specificity. Should multiple commands apply to a block, the most
-specific one wins. For example, the `minifier_cmd` setting inside
-`minibundle js` block overrides the setting in
+specific one wins. For example, the `minifier_cmd` option inside `{%
+minibundle js }%` block overrides the setting in
 `$JEKYLL_MINIBUNDLE_CMD_JS` environment variable.
 
 ### Recommended directory layout
 
 It's recommended that you exclude the files you use as asset sources
 from Jekyll itself. Otherwise, you end up with duplicate files in the
-output directory.
+site destination directory.
 
 For example, in the following snippet we're using `assets/src.css` as
 asset source to `ministamp` tag:
 
-``` html
-<!-- BAD: unless assets dir is excluded, both src.css and dest.css will be copied to output directory -->
-<link href="{{ site.baseurl }}{% ministamp assets/src.css assets/dest.css %}" rel="stylesheet" media="screen, projection">
+``` liquid
+<!-- BAD: unless assets dir is excluded, both src.css and dest.css will be copied to site destination directory -->
+<link rel="stylesheet" href="{{ site.baseurl }}/{% ministamp assets/src.css assets/dest.css %}" media="screen, projection">
 ```
 
-By default, Jekyll includes this file to the output directory. As a
-result, there will be both `src.css` and `dest-<md5>.css` files in
-`_site/assets/` directory, which you probably do not want.
+By default, Jekyll includes this file to the site destination
+directory. As a result, there will be both `src.css` and
+`dest-<md5>.css` files in `_site/assets/` directory, which you probably
+do not want.
 
-In order to avoid this, exclude the asset source file from
-Jekyll. Because Jekyll excludes directories beginning with underscore
-character (`_`), consider using the following directory layout:
+In order to avoid this, exclude the asset source file from Jekyll.
+Because Jekyll's site generation excludes underscore directories (that
+is, directories whose name begins with underscore character), consider
+using the following directory layout:
 
 * `_assets/` for JavaScript and CSS assets handled by the plugin that
   are in version control
@@ -254,6 +334,27 @@ character (`_`), consider using the following directory layout:
   that are not in version control (for example, Sass output files)
 * `assets/` for images and other assets handled by Jekyll directly
 
+However, Jekyll's watch mode (auto-regeneration) does monitor files
+inside underscore directories. If such a file is modified, the watch
+mode triggers site generation. For Minibundle's functionality, this is
+beneficial: it allows the plugin to check if assets need to be updated
+to the site destination directory.
+
+The `exclude` [Jekyll configuration][JekyllConf] option affects Jekyll's
+watch mode. Given the recommended directory layout above, if you set the
+following in `_config.yml`:
+
+``` yaml
+exclude:
+  - _assets
+  - _tmp
+```
+
+Then Jekyll won't see if files inside those directories have changed and
+the plugin won't get the chance to update assets to the site destination
+directory. So, don't explicitly exclude `_assets` and `_tmp`
+directories.
+
 See [Jekyll configuration][JekyllConf] for more about excluding files
 and directories.
 
@@ -261,9 +362,11 @@ and directories.
 
 If you set `$JEKYLL_MINIBUNDLE_MODE` environment variable to
 `development`, then the plugin will copy asset files as is to Jekyll's
-output directory and omit fingerprinting. The `destination_path` setting
-in `minibundle` block sets the destination directory for bundled
-files. This is useful in development workflow, where you need the
+site destination directory and omit fingerprinting.
+
+The development mode changes `minibundle` block's `destination_path`
+option to be the base directory for files mentioned in `assets`
+option. This is useful in development workflow, where you need the
 filenames and line numbers of the original asset sources.
 
 ``` bash
@@ -279,22 +382,100 @@ minibundle:
 
 Should both be defined, the setting from the environment variable wins.
 
+### Variable templating
+
+The template engine used by `ministamp` tag's Hash argument has syntax
+resembling the ones of [Liquid][Liquid] and [Mustache][Mustache], with
+`{{` and `}}` tags surrounding the variable to be substituted into the
+output string. For example, given Liquid variable `var = 'foo'`, the
+template `begin{{ var }}end` results in `beginfooend`.
+
+The engine supports variable substitution only. It does not support
+other expressions. If you need to, you can write complex expressions in
+Liquid, store the result to a variable, and use the variable in the
+template.
+
+If you need literal `{` or `}` characters in the template, you can
+escape them with backslash. For example, `\{` results in `{` in the
+output. To output backslash character itself, write it twice: `\\`
+results in `\` in the output.
+
+Inside variable subsitution (between `{{` and `}}`), anything before the
+closing `}}` tag is interpreted as part of the variable name, except
+that the engine removes any leading and trailing whitespace from the
+name. For example, in the template `{{ var } }}`, `var }` is treated as
+the name of the variable.
+
+A reference to undefined variable results in empty string. For example,
+`begin{{ nosuch }}end` will output `beginend` if there's no variable
+named `nosuch`.
+
+### Separating asset destination path from generated URL
+
+Use `render_basename_only: true` option of `ministamp` tag and
+`destination_baseurl` option of `minibundle` block to separate the
+destination path of the asset file from the generated URL of the
+asset. This allows you to serve the asset from a separate domain, for
+example.
+
+Example usage, with the following content in `_config.yml`:
+
+``` yaml
+cdn_baseurl: 'https://cdn.example.com'
+```
+
+For `ministamp` tag:
+
+``` liquid
+<link rel="stylesheet" href="{{ site.cdn_baseurl }}/css/{% ministamp { source_path: '_tmp/site.css', destination_path: assets/site.css, render_basename_only: true } %}">
+```
+
+The asset file will be in Jekyll's site destination directory with path
+`assets/site-ff9c63f843b11f9c3666fe46caaddea8.css`, and Liquid's
+rendering will result in:
+
+``` html
+<link rel="stylesheet" href="https://cdn.example.com/css/site-ff9c63f843b11f9c3666fe46caaddea8.css">
+```
+
+For `minibundle` block:
+
+``` liquid
+{% minibundle js %}
+source_dir: _assets/scripts
+destination_path: assets/site
+destination_baseurl: '{{ site.cdn_baseurl }}/js/'
+assets:
+  - dependency
+  - app
+{% endminibundle %}
+```
+
+The bundle file will be in Jekyll's site destination directory with path
+`assets/site-4782a1f67803038d4f8351051e67deb8.js`, and Liquid's
+rendering will result in:
+
+``` html
+<script type="text/javascript" src="https://cdn.example.com/js/site-4782a1f67803038d4f8351051e67deb8.js"></script>
+```
+
 ### Capturing Liquid output
 
-Use Liquid's `capture` block to store output rendered inside the block
-to a variable, as a string. Then you can process the string.
+Use Liquid's [`capture`][LiquidCaptureBlock] block to store output
+rendered inside the block to a variable, as a string. Then you can
+process the string as you like.
 
 For example:
 
-``` html
-{% capture sitecss %}{% ministamp _assets/site.css assets/site.css %}{% endcapture %}
-<link href="{{ site.cdnbaseurl }}{{ sitecss | remove_first: "assets/"}}" rel="stylesheet" media="screen, projection">
+``` liquid
+{% capture site_css %}{% ministamp _assets/site.css assets/site.css %}{% endcapture %}
+<link rel="stylesheet" href="{{ site_css | remove_first: "assets/" }}">
 ```
 
-Output, provided `site.cdnbaseurl` is set to `https://cdn.example.com/`:
+Liquid's rendering outcome:
 
 ``` html
-<link href="https://cdn.example.com/site-390be921ee0eff063817bb5ef2954300.css" rel="stylesheet" media="screen, projection">
+<link rel="stylesheet" href="site-390be921ee0eff063817bb5ef2954300.css">
 ```
 
 ## Example site
@@ -303,12 +484,8 @@ See the sources of [an example site][JekyllMinibundleExampleSite].
 
 ## Known caveats
 
-1. The plugin does not work with Jekyll's incremental rebuild feature
-   (Jekyll option `--incremental`).
-
-2. `ministamp` tag does not interpret Liquid variables, as the tag just
-   takes in string literals. Improving this would require new syntax for
-   tag arguments.
+The plugin does not work with Jekyll's incremental rebuild feature
+(Jekyll option `--incremental`).
 
 ## License
 
@@ -320,9 +497,12 @@ MIT. See `LICENSE.txt`.
 [JekyllMinibundleExampleSite]: https://github.com/tkareine/jekyll-minibundle-example
 [Jekyll]: https://jekyllrb.com/
 [Liquid]: https://shopify.github.io/liquid/
+[LiquidAssignTag]: https://shopify.github.io/liquid/tags/variable/#assign
+[LiquidCaptureBlock]: https://shopify.github.io/liquid/tags/variable/#capture
 [MD5]: https://en.wikipedia.org/wiki/MD5
 [MinibundleBuild]: https://travis-ci.org/tkareine/jekyll-minibundle
 [MinibundleGem]: https://rubygems.org/gems/jekyll-minibundle
+[Mustache]: https://mustache.github.io/
 [Sass]: http://sass-lang.com/
 [UglifyJS2]: https://github.com/mishoo/UglifyJS2
 [YAML]: http://www.yaml.org/