docpad-plugin-assets
Version:
DocPad plugin to change URL of asset files to contain hash of contents, allowing for effective caching whilst enabling cache busting when contents change
152 lines (80 loc) • 9.42 kB
Markdown
<!-- TITLE/ -->
<h1>Assets Plugin for DocPad</h1>
<!-- /TITLE -->
<!-- BADGES/ -->
<span class="badge-travisci"><a href="http://travis-ci.com/docpad/docpad-plugin-assets" title="Check this project's build status on TravisCI"><img src="https://img.shields.io/travis/com/docpad/docpad-plugin-assets/master.svg" alt="Travis CI Build Status" /></a></span>
<span class="badge-npmversion"><a href="https://npmjs.org/package/docpad-plugin-assets" title="View this project on NPM"><img src="https://img.shields.io/npm/v/docpad-plugin-assets.svg" alt="NPM version" /></a></span>
<span class="badge-npmdownloads"><a href="https://npmjs.org/package/docpad-plugin-assets" title="View this project on NPM"><img src="https://img.shields.io/npm/dm/docpad-plugin-assets.svg" alt="NPM downloads" /></a></span>
<span class="badge-daviddm"><a href="https://david-dm.org/docpad/docpad-plugin-assets" title="View the status of this project's dependencies on DavidDM"><img src="https://img.shields.io/david/docpad/docpad-plugin-assets.svg" alt="Dependency Status" /></a></span>
<span class="badge-daviddmdev"><a href="https://david-dm.org/docpad/docpad-plugin-assets#info=devDependencies" title="View the status of this project's development dependencies on DavidDM"><img src="https://img.shields.io/david/dev/docpad/docpad-plugin-assets.svg" alt="Dev Dependency Status" /></a></span>
<br class="badge-separator" />
<span class="badge-githubsponsors"><a href="https://github.com/sponsors/balupton" title="Donate to this project using GitHub Sponsors"><img src="https://img.shields.io/badge/github-donate-yellow.svg" alt="GitHub Sponsors donate button" /></a></span>
<span class="badge-patreon"><a href="https://patreon.com/bevry" title="Donate to this project using Patreon"><img src="https://img.shields.io/badge/patreon-donate-yellow.svg" alt="Patreon donate button" /></a></span>
<span class="badge-flattr"><a href="https://flattr.com/profile/balupton" title="Donate to this project using Flattr"><img src="https://img.shields.io/badge/flattr-donate-yellow.svg" alt="Flattr donate button" /></a></span>
<span class="badge-liberapay"><a href="https://liberapay.com/bevry" title="Donate to this project using Liberapay"><img src="https://img.shields.io/badge/liberapay-donate-yellow.svg" alt="Liberapay donate button" /></a></span>
<span class="badge-buymeacoffee"><a href="https://buymeacoffee.com/balupton" title="Donate to this project using Buy Me A Coffee"><img src="https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg" alt="Buy Me A Coffee donate button" /></a></span>
<span class="badge-opencollective"><a href="https://opencollective.com/bevry" title="Donate to this project using Open Collective"><img src="https://img.shields.io/badge/open%20collective-donate-yellow.svg" alt="Open Collective donate button" /></a></span>
<span class="badge-crypto"><a href="https://bevry.me/crypto" title="Donate to this project using Cryptocurrency"><img src="https://img.shields.io/badge/crypto-donate-yellow.svg" alt="crypto donate button" /></a></span>
<span class="badge-paypal"><a href="https://bevry.me/paypal" title="Donate to this project using Paypal"><img src="https://img.shields.io/badge/paypal-donate-yellow.svg" alt="PayPal donate button" /></a></span>
<span class="badge-wishlist"><a href="https://bevry.me/wishlist" title="Buy an item on our wishlist for us"><img src="https://img.shields.io/badge/wishlist-donate-yellow.svg" alt="Wishlist browse button" /></a></span>
<!-- /BADGES -->
<!-- DESCRIPTION/ -->
DocPad plugin to change URL of asset files to contain hash of contents, allowing for effective caching whilst enabling cache busting when contents change
<!-- /DESCRIPTION -->
## Usage
Change URL of asset files to contain hash of contents, allowing for effective caching whilst enabling cache busting when contents change.
This plugin enables the function `@asset()`, which takes a single string argument of the asset to manage. For example, if you have some HTML which looks like this:
``` html
<img src="/images/myimage.png" />
```
Then to put the asset under then plugin's control you would change this to:
``` html
<img src="<%- @asset('/images/myimage.png') %>" />
```
And that's it!
By default the plugin will leave the path along and replace the name of the file with it's hash. Continuing on from the above example, with the defaults the output URL will be something like `/images/3992a5c4177710abf7d1e90b91636b26cbac138b.png`. There are two options which you can tweak to change this default output.
- `retainPath`: if set to 'no' then this will remove any leading path from the URL and put the asset in the root directory. In the above case the output URL will be `/3992a5c4177710abf7d1e90b91636b26cbac138b.png`
- `retainName`: if set to 'yes' then this will retain the name of the original file, and append the hash to it. In the above case the output URL will be `/images/myimage-3992a5c4177710abf7d1e90b91636b26cbac138b.png`
### Implementation Notes
Please ensure that all assets use absolute path names, otherwise this plugin might not operate correctly.
<!-- INSTALL/ -->
<h2>Install</h2>
Install this DocPad plugin by entering <code>docpad install assets</code> into your terminal.
<!-- /INSTALL -->
<!-- HISTORY/ -->
<h2>History</h2>
<a href="https://github.com/docpad/docpad-plugin-assets/blob/master/HISTORY.md#files">Discover the release history by heading on over to the <code>HISTORY.md</code> file.</a>
<!-- /HISTORY -->
<!-- CONTRIBUTE/ -->
<h2>Contribute</h2>
<a href="https://github.com/docpad/docpad-plugin-assets/blob/master/Contributing.md#files">Discover how you can contribute by heading on over to the <code>Contributing.md</code> file.</a>
<!-- /CONTRIBUTE -->
<!-- BACKERS/ -->
<h2>Backers</h2>
<h3>Maintainers</h3>
These amazing people are maintaining this project:
<ul><li><a href="https://github.com/mcdee">Jim McDonald</a> — <a href="https://github.com/docpad/docpad-plugin-assets/commits?author=mcdee" title="View the GitHub contributions of Jim McDonald on repository docpad/docpad-plugin-assets">view contributions</a></li></ul>
<h3>Sponsors</h3>
No sponsors yet! Will you be the first?
<span class="badge-githubsponsors"><a href="https://github.com/sponsors/balupton" title="Donate to this project using GitHub Sponsors"><img src="https://img.shields.io/badge/github-donate-yellow.svg" alt="GitHub Sponsors donate button" /></a></span>
<span class="badge-patreon"><a href="https://patreon.com/bevry" title="Donate to this project using Patreon"><img src="https://img.shields.io/badge/patreon-donate-yellow.svg" alt="Patreon donate button" /></a></span>
<span class="badge-flattr"><a href="https://flattr.com/profile/balupton" title="Donate to this project using Flattr"><img src="https://img.shields.io/badge/flattr-donate-yellow.svg" alt="Flattr donate button" /></a></span>
<span class="badge-liberapay"><a href="https://liberapay.com/bevry" title="Donate to this project using Liberapay"><img src="https://img.shields.io/badge/liberapay-donate-yellow.svg" alt="Liberapay donate button" /></a></span>
<span class="badge-buymeacoffee"><a href="https://buymeacoffee.com/balupton" title="Donate to this project using Buy Me A Coffee"><img src="https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg" alt="Buy Me A Coffee donate button" /></a></span>
<span class="badge-opencollective"><a href="https://opencollective.com/bevry" title="Donate to this project using Open Collective"><img src="https://img.shields.io/badge/open%20collective-donate-yellow.svg" alt="Open Collective donate button" /></a></span>
<span class="badge-crypto"><a href="https://bevry.me/crypto" title="Donate to this project using Cryptocurrency"><img src="https://img.shields.io/badge/crypto-donate-yellow.svg" alt="crypto donate button" /></a></span>
<span class="badge-paypal"><a href="https://bevry.me/paypal" title="Donate to this project using Paypal"><img src="https://img.shields.io/badge/paypal-donate-yellow.svg" alt="PayPal donate button" /></a></span>
<span class="badge-wishlist"><a href="https://bevry.me/wishlist" title="Buy an item on our wishlist for us"><img src="https://img.shields.io/badge/wishlist-donate-yellow.svg" alt="Wishlist browse button" /></a></span>
<h3>Contributors</h3>
These amazing people have contributed code to this project:
<ul><li><a href="https://github.com/balupton">Benjamin Lupton</a> — <a href="https://github.com/docpad/docpad-plugin-assets/commits?author=balupton" title="View the GitHub contributions of Benjamin Lupton on repository docpad/docpad-plugin-assets">view contributions</a></li>
<li><a href="https://github.com/mcdee">Jim McDonald</a> — <a href="https://github.com/docpad/docpad-plugin-assets/commits?author=mcdee" title="View the GitHub contributions of Jim McDonald on repository docpad/docpad-plugin-assets">view contributions</a></li></ul>
<a href="https://github.com/docpad/docpad-plugin-assets/blob/master/Contributing.md#files">Discover how you can contribute by heading on over to the <code>Contributing.md</code> file.</a>
<!-- /BACKERS -->
<!-- LICENSE/ -->
<h2>License</h2>
Unless stated otherwise all works are:
<ul><li>Copyright © 2013+ <a href="https://github.com/mcdee">Jim McDonald</a></li></ul>
and licensed under:
<ul><li><a href="http://spdx.org/licenses/MIT.html">MIT License</a></li></ul>
<!-- /LICENSE -->