Readme.rst 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108
  1. Asset management
  2. ----------------
  3. This plugin allows you to use the `Webassets`_ module to manage assets such as
  4. CSS and JS files. The module must first be installed::
  5. pip install webassets
  6. The Webassets module allows you to perform a number of useful asset management
  7. functions, including:
  8. * CSS minifier (``cssmin``, ``yui_css``, ...)
  9. * CSS compiler (``less``, ``sass``, ...)
  10. * JS minifier (``uglifyjs``, ``yui_js``, ``closure``, ...)
  11. Others filters include CSS URL rewriting, integration of images in CSS via data
  12. URIs, and more. Webassets can also append a version identifier to your asset
  13. URL to convince browsers to download new versions of your assets when you use
  14. far-future expires headers. Please refer to the `Webassets documentation`_ for
  15. more information.
  16. When used with Pelican, Webassets is configured to process assets in the
  17. ``OUTPUT_PATH/theme`` directory. You can use Webassets in your templates by
  18. including one or more template tags. The Jinja variable ``{{ ASSET_URL }}`` can
  19. be used in templates and is relative to the ``theme/`` url. The
  20. ``{{ ASSET_URL }}`` variable should be used in conjunction with the
  21. ``{{ SITEURL }}`` variable in order to generate URLs properly. For example:
  22. .. code-block:: jinja
  23. {% assets filters="cssmin", output="css/style.min.css", "css/inuit.css", "css/pygment-monokai.css", "css/main.css" %}
  24. <link rel="stylesheet" href="{{ SITEURL }}/{{ ASSET_URL }}">
  25. {% endassets %}
  26. ... will produce a minified css file with a version identifier that looks like:
  27. .. code-block:: html
  28. <link href="http://{SITEURL}/theme/css/style.min.css?b3a7c807" rel="stylesheet">
  29. These filters can be combined. Here is an example that uses the SASS compiler
  30. and minifies the output:
  31. .. code-block:: jinja
  32. {% assets filters="sass,cssmin", output="css/style.min.css", "css/style.scss" %}
  33. <link rel="stylesheet" href="{{ SITEURL }}/{{ ASSET_URL }}">
  34. {% endassets %}
  35. Another example for Javascript:
  36. .. code-block:: jinja
  37. {% assets filters="uglifyjs", output="js/packed.js", "js/jquery.js", "js/base.js", "js/widgets.js" %}
  38. <script src="{{ SITEURL }}/{{ ASSET_URL }}"></script>
  39. {% endassets %}
  40. The above will produce a minified JS file:
  41. .. code-block:: html
  42. <script src="http://{SITEURL}/theme/js/packed.js?00703b9d"></script>
  43. Pelican's debug mode is propagated to Webassets to disable asset packaging
  44. and instead work with the uncompressed assets.
  45. If you need to create named bundles (for example, if you need to compile SASS
  46. files before minifying with other CSS files), you can use the ``ASSET_BUNDLES``
  47. variable in your settings file. This is an ordered sequence of 3-tuples, where
  48. the 3-tuple is defined as ``(name, args, kwargs)``. This tuple is passed to the
  49. `environment's register() method`_. The following will compile two SCSS files
  50. into a named bundle, using the ``pyscss`` filter:
  51. .. code-block:: python
  52. ASSET_BUNDLES = (
  53. ('scss', ['colors.scss', 'main.scss'], {'filters': 'pyscss'}),
  54. )
  55. Many of Webasset's available compilers have additional configuration options
  56. (i.e. 'Less', 'Sass', 'Stylus', 'Closure_js'). You can pass these options to
  57. Webassets using the ``ASSET_CONFIG`` in your settings file.
  58. The following will handle Google Closure's compilation level and locate
  59. LessCSS's binary:
  60. .. code-block:: python
  61. ASSET_CONFIG = (('closure_compressor_optimization', 'WHITESPACE_ONLY'),
  62. ('less_bin', 'lessc.cmd'), )
  63. If you wish to place your assets in locations other than the theme output
  64. directory, you can use ``ASSET_SOURCE_PATHS`` in your settings file to provide
  65. webassets with a list of additional directories to search, relative to the
  66. theme's top-level directory. Note that as of Pelican 3.5.0, this setting is
  67. required, as the ``StaticGenerator`` generator now runs last in sequence:
  68. .. code-block:: python
  69. ASSET_SOURCE_PATHS = (
  70. 'vendor/css',
  71. 'scss',
  72. )
  73. .. _Webassets: https://github.com/miracle2k/webassets
  74. .. _Webassets documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html
  75. .. _environment's register() method: http://webassets.readthedocs.org/en/latest/environment.html#registering-bundles