Skip to main content

A Pelican plugin so you can use webassets

Project description

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pelican-webassets, version 0.1.0
Filename, size File type Python version Upload date Hashes
Filename, size pelican_webassets-0.1.0-py3-none-any.whl (4.4 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pelican-webassets-0.1.0.tar.gz (4.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page