Web Assets: A Plugin for Pelican

This Pelican plugin allows you to use the webassets module to perform a number of useful asset management functions on your web site, such as:

• CSS minification (cssmin, yui_css, ...)
• CSS compiling (less, sass, ...)
• JS building (uglifyjs, yui_js, closure, ...)

Some other interesting abilities of webassets include:

• URL Expiry or "cache-busting", allowing you to set the cache headers for your assets long into the future, saving bandwidth and reducing page load-times
• a spritemapper function to automatically combine multiple icons into one large image with corresponding position slices
• a datauri function to minimize the number of HTTP requests by replacing url() references in your stylesheets with internal in-line data URIs

For the complete list of what webassets can do, check out the included filters section in the webassets documentation.

Installation

Getting started with webassets couldn't be easier thanks to pip:

python -m pip install pelican-webassets

For more detailed plugin installation instructions, please refer to the Pelican Plugin Documentation.

💡 Keep in Mind: Each function you use in your {% asset filters %} arguments (more on this later) will need to be installed separately. For example, if you wanted to use the libsass filter, you will need to pip install libsass. You can even create a custom filter if you wanted.

Usage

With the plugin installed, include one or more {% assets %} tags into your web site's templates to generate everything your web page will need. For example, something like this in your template…

{% assets filters="libsass,cssmin", output="css/style.min.css", "css/style.scss" %}
  <link rel="stylesheet" href="{{SITEURL}}/{{ASSET_URL}}">
{% endassets %}

… will tell webassets to use libsass and cssmin to compile and minify the css/style.scss file in your theme, and save the compiled stylesheet as css/style.min.css in the output of your finished website, along with the link element like this in your web page:

<link href="{SITEURL}/{THEME_STATIC_DIR}/css/style.min.css?b3a7c807" rel="stylesheet">

🌠 The More You Know: The ASSET_URL variable is the concatenation of your Pelican THEME_STATIC_DIR setting, the output argument, and the "cache-busting" variable we already talked about.

JavaScript Example

As another example, we can use the webassets closure_js function to combine, minify, and compress two files in your web site's theme, js/jQuery.js and js/widgets.js:

{% assets filters="closure_js", output="js/packed.js", "js/jQuery.js", "js/widgets.js" %}
 <script src="{{SITEURL}}/{{ASSET_URL}}"></script>
{% endassets %}

The resulting output will be a single script tag and its corresponding file in your web site's generated output:

<script src="{SITEURL}/{THEME_STATIC_DIR}/js/packed.js?00703b9d"></script>

Configuration

Being a very small wrapper around the webassets module, there are only a few options that you may need.

WEBASSETS_DEBUG

By default, if Pelican is in DEBUG mode (pelican -D ...), this plugin will put webassets in DEBUG mode, to help you with debugging. To override this behavior, set WEBASSETS_DEBUG = False to always process files regardless of Pelican's DEBUG flag, or True to always force webassets into DEBUG mode.

# put webassets into DEBUG mode if Pelican is
WEBASSETS_DEBUG = logger.getEffectiveLevel() <= logging.DEBUG

WEBASSETS_CONFIG

Some webassets filters require extra configuration options to function properly. You can use WEBASSETS_CONFIG to specify these options in a list of (key, value) tuples that are passed along to the webassets environment.

WEBASSETS_CONFIG = [
  ("closure_compressor_optimization", "ADVANCED_OPTIMIZATIONS"),
  ("libsass_style", "compressed")
]

WEBASSETS_BUNDLES

Bundles are a convenient way to group a collection of assets together along with the information on how to properly process the files. The WEBASSETS_BUNDLES option allows us to make these Bundles by taking a list of (name, args, kwargs) arguments that will be passed to the webassets environment.

WEBASSETS_BUNDLES = (
     ("my_bundle", ("colors.scss", "style.scss"),
     {"output": "style.min.css", "filters": ["libsass", "cssmin"]}),
)

Allowing you to simplify something like this in your web site's templates…

{% assets filters="libsass,cssmin", output="style.min.css", "colors.scss", "style.scss" %}

… into this:

{% assets 'my_bundle' %}

WEBASSETS_SOURCE_PATHS

If your raw assets are in directories other than your THEME_STATIC_PATHS, you can supply additional directories to search in with WEBASSETS_SOURCE_PATHS.

WEBASSETS_SOURCE_PATHS = ["stylehseets", "javascript"]

Contributing

Contributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on existing issues.

To start contributing to this plugin, review the Contributing to Pelican documentation, beginning with the Contributing Code section.

License

This project is licensed under the AGPL-3.0 license