mirror of
https://github.com/getpelican/pelican.git
synced 2025-10-15 20:28:56 +02:00
Move webassets doc to the plugins page
This commit is contained in:
Simon
parent
4cfb0cd24e
commit
4c15ec9f86
2 changed files with 81 additions and 80 deletions
|
|
@ -99,6 +99,7 @@ List of plugins
|
|||
|
||||
The following plugins are currently included with Pelican under ``pelican.plugins``:
|
||||
|
||||
* `Asset management`_
|
||||
* `GitHub activity`_
|
||||
* `Global license`_
|
||||
* `Gravatar`_
|
||||
|
|
@ -114,6 +115,76 @@ Ideas for plugins that haven't been written yet:
|
|||
Plugin descriptions
|
||||
===================
|
||||
|
||||
Asset management
|
||||
----------------
|
||||
|
||||
This plugin allows you to use the `webassets`_ module to manage assets such as
|
||||
CSS and JS files. The module must first be installed::
|
||||
|
||||
pip install webassets
|
||||
|
||||
The `webassets` module allows you to perform a number of useful asset management
|
||||
functions, including:
|
||||
|
||||
* CSS minifier (`cssmin`, `yuicompressor`, ...)
|
||||
* CSS compiler (`less`, `sass`, ...)
|
||||
* JS minifier (`uglifyjs`, `yuicompressor`, `closure`, ...)
|
||||
|
||||
Others filters include gzip compression, integration of images in CSS via data
|
||||
URIs, and more. `webassets` can also append a version identifier to your asset
|
||||
URL to convince browsers to download new versions of your assets when you use
|
||||
far-future expires headers. Please refer to the `webassets documentation`_ for
|
||||
more information.
|
||||
|
||||
When using with Pelican, `webassets` is configured to process assets in the
|
||||
``OUTPUT_PATH/theme`` directory. You can use `webassets` in your templates by
|
||||
including one or more template tags. For example...
|
||||
|
||||
.. code-block:: jinja
|
||||
|
||||
{% assets filters="cssmin", output="css/style.min.css", "css/inuit.css", "css/pygment-monokai.css", "css/main.css" %}
|
||||
<link rel="stylesheet" href="{{ ASSET_URL }}">
|
||||
{% endassets %}
|
||||
|
||||
... will produce a minified css file with a version identifier:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<link href="http://{SITEURL}/theme/css/style.min.css?b3a7c807" rel="stylesheet">
|
||||
|
||||
These filters can be combined. Here is an example that uses the SASS compiler
|
||||
and minifies the output:
|
||||
|
||||
.. code-block:: jinja
|
||||
|
||||
{% assets filters="sass,cssmin", output="css/style.min.css", "css/style.scss" %}
|
||||
<link rel="stylesheet" href="{{ ASSET_URL }}">
|
||||
{% endassets %}
|
||||
|
||||
Another example for Javascript:
|
||||
|
||||
.. code-block:: jinja
|
||||
|
||||
{% assets filters="uglifyjs,gzip", output="js/packed.js", "js/jquery.js", "js/base.js", "js/widgets.js" %}
|
||||
<script src="{{ ASSET_URL }}"></script>
|
||||
{% endassets %}
|
||||
|
||||
The above will produce a minified and gzipped JS file:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<script src="http://{SITEURL}/theme/js/packed.js?00703b9d"></script>
|
||||
|
||||
Pelican's debug mode is propagated to `webassets` to disable asset packaging
|
||||
and instead work with the uncompressed assets. However, this also means that
|
||||
the LESS and SASS files are not compiled. This should be fixed in a future
|
||||
version of `webassets` (cf. the related `bug report
|
||||
<https://github.com/getpelican/pelican/issues/481>`_).
|
||||
|
||||
.. _webassets: https://github.com/miracle2k/webassets
|
||||
.. _webassets documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html
|
||||
|
||||
|
||||
GitHub activity
|
||||
---------------
|
||||
|
||||
|
|
|
|||
|
|
@ -426,7 +426,6 @@ Setting name (default value) What does it do?
|
|||
value is `static`, but if your theme has
|
||||
other static paths, you can put them here.
|
||||
`CSS_FILE` (``'main.css'``) Specify the CSS file you want to load.
|
||||
`WEBASSETS` (``False``) Asset management with `webassets` (see below)
|
||||
================================================ =====================================================
|
||||
|
||||
|
||||
|
|
@ -487,75 +486,6 @@ adding the following to your configuration::
|
|||
|
||||
CSS_FILE = "wide.css"
|
||||
|
||||
Asset management
|
||||
----------------
|
||||
|
||||
The `WEBASSETS` setting allows you to use the `webassets`_ module to manage
|
||||
assets such as CSS and JS files. The module must first be installed::
|
||||
|
||||
pip install webassets
|
||||
|
||||
The `webassets` module allows you to perform a number of useful asset management
|
||||
functions, including:
|
||||
|
||||
* CSS minifier (`cssmin`, `yuicompressor`, ...)
|
||||
* CSS compiler (`less`, `sass`, ...)
|
||||
* JS minifier (`uglifyjs`, `yuicompressor`, `closure`, ...)
|
||||
|
||||
Others filters include gzip compression, integration of images in CSS via data
|
||||
URIs, and more. `webassets` can also append a version identifier to your asset
|
||||
URL to convince browsers to download new versions of your assets when you use
|
||||
far-future expires headers. Please refer to the `webassets documentation`_ for
|
||||
more information.
|
||||
|
||||
When using with Pelican, `webassets` is configured to process assets in the
|
||||
``OUTPUT_PATH/theme`` directory. You can use `webassets` in your templates by
|
||||
including one or more template tags. For example...
|
||||
|
||||
.. code-block:: jinja
|
||||
|
||||
{% assets filters="cssmin", output="css/style.min.css", "css/inuit.css", "css/pygment-monokai.css", "css/main.css" %}
|
||||
<link rel="stylesheet" href="{{ ASSET_URL }}">
|
||||
{% endassets %}
|
||||
|
||||
... will produce a minified css file with a version identifier:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<link href="http://{SITEURL}/theme/css/style.min.css?b3a7c807" rel="stylesheet">
|
||||
|
||||
These filters can be combined. Here is an example that uses the SASS compiler
|
||||
and minifies the output:
|
||||
|
||||
.. code-block:: jinja
|
||||
|
||||
{% assets filters="sass,cssmin", output="css/style.min.css", "css/style.scss" %}
|
||||
<link rel="stylesheet" href="{{ ASSET_URL }}">
|
||||
{% endassets %}
|
||||
|
||||
Another example for Javascript:
|
||||
|
||||
.. code-block:: jinja
|
||||
|
||||
{% assets filters="uglifyjs,gzip", output="js/packed.js", "js/jquery.js", "js/base.js", "js/widgets.js" %}
|
||||
<script src="{{ ASSET_URL }}"></script>
|
||||
{% endassets %}
|
||||
|
||||
The above will produce a minified and gzipped JS file:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<script src="http://{SITEURL}/theme/js/packed.js?00703b9d"></script>
|
||||
|
||||
Pelican's debug mode is propagated to `webassets` to disable asset packaging
|
||||
and instead work with the uncompressed assets. However, this also means that
|
||||
the LESS and SASS files are not compiled. This should be fixed in a future
|
||||
version of `webassets` (cf. the related `bug report
|
||||
<https://github.com/getpelican/pelican/issues/481>`_).
|
||||
|
||||
.. _webassets: https://github.com/miracle2k/webassets
|
||||
.. _webassets documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html
|
||||
|
||||
Example settings
|
||||
================
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue