pelican-webassets 0.1.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 your Expires headers 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

The pelican-webassets package is ready to be installed via a simple pip command:

$ 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="http://{SITEURL}/{THEME_STATIC_DIR}/css/style.min.css?b3a7c807" rel="stylesheet">

JavaScript

Another example using JavaScript, 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="http://{SITEURL}/{THEME_STATIC_DIR}/js/packed.js?00703b9d"></script>

Options

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.

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 environment’s register() method.

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' %}

WEBASSETS_DEBUG

By default, webassets will disable asset packaging if Pelican is in DEBUG mode. You can change this by overriding the WEBASSETS_DEBUG value.

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

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'
]

Want to Help?

Please feel free to help. Issues, pull requests, even patches via email, all are warmly welcomed.