pelican-webassets 1.0.0

A Pelican plugin so you can use webassets

pelican-webassets

This plugin allows you to use webassets (a popular asset management application for Python web development) to manage your CSS and JavaScript assets for your Pelican powered static website.

webassets comes with many filters like:

• cssmin and yui_css to compress your CSS assets

• libsass and less to compile CSS assets

• closure_js and uglifyjs for your JS assets

as well as many more useful things like

• URL Expiry “cache-busting”, allowing you to set the Expires header for your assets long into the future

• spritemapper to merge multiple images into one and generates CSS positioning for the corresponding slices

• datauri to replace url() references to external files with internal data: URIs

For a more complete list, check out the included filters section in their documentation.

Installing

pelican-webassets is available on pip:

$ pip install pelican-webassets

Then add the plugin to your list of PLUGINS in your pelicanconf.py file to include the plugin in your next pelican build.

PLUGINS = [
    # ...
    'pelican_webassets',
    # ...
]

Using the Plugin

After you’ve installed the package, include one or more {% assets %} tags into your templates to generate the links to your processed assets.

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

The example above uses the libsass and cssmin filters to compile, minify and save style.scss to ASSET_URL (equals {THEME_STATIC_DIR}/) and results in a final output path of:

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

JavaScript

Another JavaScript example uses closure_js to combine, minify and compress js/jQuery.js and js/app.js:

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

into a script element like this:

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

Options

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

WEBASSETS_DEBUG

By default, if pelican is in DEBUG mode, pelican-webassets will not process any assets, helping you with debugging. To override this behavior, set WEBASSETS_DEBUG = True to process files regardless of the DEBUG flag.

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

WEBASSETS_CONFIG

Some filters require extra configuration options to function properly. You can use WEBASSETS_CONFG 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

WEBASSETS_BUNDLES is a list of 3 item tuples consisting of (name, args, kwargs) which will be passed to the webassets’ environment.

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

Allowing you to simplify something like this:

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

into this:

{% assets 'my_bundle' %}

More information about both webassets’ environment configuration and named bundles can be found in the webassets documentation.

WEBASSETS_SOURCE_PATH

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 = [
   'src/scss',
   'src/js'
]

Contributing

Please feel free to help. Buying me Beer, emailing issues, or patches via email, are all warmly welcomed, especially beer.