github/pelican
1
0
Fork 1
mirror of https://github.com/getpelican/pelican.git synced 2025-10-15 20:28:56 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Move webassets doc to the plugins page

Browse source
This commit is contained in:
Simon 2012-11-06 00:04:45 +01:00
commit 4c15ec9f86
2 changed files with 81 additions and 80 deletions
Download patch file Download diff file Expand all files Collapse all files

89
docs/plugins.rst
View file

@ -59,7 +59,7 @@ Signal Arguments Description
============================= ============================ =========================================================================== ============================= ============================ ===========================================================================
initialized pelican object initialized pelican object
finalized pelican object invoked after all the generators are executed and just before pelican exits finalized pelican object invoked after all the generators are executed and just before pelican exits
usefull for custom post processing actions, such as: usefull for custom post processing actions, such as:
- minifying js/css assets. - minifying js/css assets.
- notify/ping search engines with an updated sitemap. - notify/ping search engines with an updated sitemap.
article_generate_context article_generator, metadata article_generate_context article_generator, metadata
@ -75,23 +75,23 @@ pages_generator_init pages_generator invoked in the P
The list is currently small, don't hesitate to add signals and make a pull The list is currently small, don't hesitate to add signals and make a pull
request if you need them! request if you need them!
.. note:: .. note::
The signal ``content_object_init`` can send different type of object as The signal ``content_object_init`` can send different type of object as
argument. If you want to register only one type of object then you will argument. If you want to register only one type of object then you will
need to specify the sender when you are connecting to the signal. need to specify the sender when you are connecting to the signal.
:: ::
from pelican import signals from pelican import signals
from pelican import contents from pelican import contents
def test(sender, instance): def test(sender, instance):
print "%s : %s content initialized !!" % (sender, instance) print "%s : %s content initialized !!" % (sender, instance)
def register(): def register():
signals.content_object_init.connect(test, sender=contents.Article) signals.content_object_init.connect(test, sender=contents.Article)
List of plugins List of plugins
@ -99,6 +99,7 @@ List of plugins
The following plugins are currently included with Pelican under ``pelican.plugins``: The following plugins are currently included with Pelican under ``pelican.plugins``:
* `Asset management`_
* `GitHub activity`_ * `GitHub activity`_
* `Global license`_ * `Global license`_
* `Gravatar`_ * `Gravatar`_
@ -114,6 +115,76 @@ Ideas for plugins that haven't been written yet:
Plugin descriptions 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 GitHub activity
--------------- ---------------

72
docs/settings.rst
View file

@ -52,7 +52,7 @@ Setting name (default value) What doe
the datetime.datetime constructor. the datetime.datetime constructor.
`DELETE_OUTPUT_DIRECTORY` (``False``) Delete the content of the output directory before `DELETE_OUTPUT_DIRECTORY` (``False``) Delete the content of the output directory before
generating new files. generating new files.
`FILES_TO_COPY` (``()``) A list of files to copy from the source (inside the content `FILES_TO_COPY` (``()``) A list of files to copy from the source (inside the content
directory) to the destination (inside the output directory). directory) to the destination (inside the output directory).
For example: ``(('extra/robots.txt', 'robots.txt'),)``. For example: ``(('extra/robots.txt', 'robots.txt'),)``.
`JINJA_EXTENSIONS` (``[]``) A list of any Jinja2 extensions you want to use. `JINJA_EXTENSIONS` (``[]``) A list of any Jinja2 extensions you want to use.
@ -426,7 +426,6 @@ Setting name (default value) What does it do?
value is `static`, but if your theme has value is `static`, but if your theme has
other static paths, you can put them here. other static paths, you can put them here.
`CSS_FILE` (``'main.css'``) Specify the CSS file you want to load. `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" 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 Example settings
================ ================