git pull git://github.com/ametaireau/pelican.git

docs/index.rst

@@ -61,6 +61,7 @@ A French version of the documentation is available at :doc:`fr/index`.
    getting_started
    settings
    themes
+   plugins
    internals
    pelican-themes
    importer

docs/plugins.rst

@@ -0,0 +1,108 @@
+.. _plugins:
+
+Plugins
+#######
+
+Since version 3.0, pelican manages plugins. Plugins are a way to add features
+to pelican without having to directly hack pelican code.
+
+Pelican is shipped with a set of core plugins, but you can easily implement
+your own (and this page describes how).
+
+How to use plugins?
+====================
+
+To load plugins, you have to specify them in your settings file. You have two
+ways to do so.
+Either by specifying strings with the path to the callables::
+
+    PLUGINS = ['pelican.plugins.gravatar',] 
+
+Or by importing them and adding them to the list::
+
+    from pelican.plugins import gravatar
+    PLUGINS = [gravatar, ]
+
+If your plugins are not in an importable path, you can specify a `PLUGIN_PATH`
+in the settings::
+
+    PLUGIN_PATH = "plugins"
+    PLUGINS = ["list", "of", "plugins"]
+
+How to create plugins?
+======================
+
+Plugins are based on the concept of signals. Pelican sends signals and plugins
+subscribe to those signals. The list of signals are defined in a following
+section.
+
+The only rule to follow for plugins is to define a `register` callable, in
+which you map the signals to your plugin logic. Let's take a simple exemple::
+
+    from pelican import signals
+
+    def test(sender):
+        print "%s initialized !!" % sender
+
+    def register():
+        signals.initialized.connect(test)
+
+
+List of signals
+===============
+
+Here is the list of currently implemented signals:
+
+=========================   ============================   =========================================
+Signal                      Arguments                      Description
+=========================   ============================   =========================================
+initialized                 pelican object
+article_generate_context    article_generator, metadata
+article_generator_init      article_generator              invoked in the ArticlesGenerator.__init__
+=========================   ============================   =========================================
+
+The list is currently small, don't hesitate to add signals and make a pull
+request if you need them!
+
+List of plugins
+===============
+
+Not all the list are described here, but a few of them have been extracted from
+pelican core and provided in pelican.plugins. They are described here:
+
+Tag cloud
+---------
+
+Translation
+-----------
+
+Github Activity
+---------------
+
+This plugin makes use of the ``feedparser`` library that you'll need to
+install.
+
+Set the GITHUB_ACTIVITY_FEED parameter to your github activity feed.
+For example, my setting would look like::
+
+     GITHUB_ACTIVITY_FEED = 'https://github.com/kpanic.atom'
+
+On the templates side, you just have to iterate over the ``github_activity``
+variable, as in the example::
+
+     {% if GITHUB_ACTIVITY_FEED %}
+        <div class="social">
+                <h2>Github Activity</h2>
+                <ul>
+
+                {% for entry in github_activity %}
+                    <li><b>{{ entry[0] }}</b><br /> {{ entry[1] }}</li>
+                {% endfor %}
+                </ul>
+        </div><!-- /.github_activity -->
+     {% endif %}
+
+
+
+``github_activity`` is a list of lists. The first element is the title
+and the second element is the raw html from github.

docs/settings.rst

@@ -61,6 +61,7 @@ Setting name (default value)                                            What doe
                                                                         `rst2pdf`.
 `RELATIVE_URLS` (``True``)                                              Defines whether Pelican should use relative URLs or
                                                                         not.
+`PLUGINS` (``[]``)                                                      The list of plugins to load. See :ref:`plugins`.
 `SITENAME` (``'A Pelican Blog'``)                                       Your site name
 `SITEURL`                                                               Base URL of your website. Not defined by default,
                                                                         which means the base URL is assumed to be "/" with a
@@ -375,6 +376,7 @@ 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)
 ================================================    =====================================================
 
 By default, two themes are available. You can specify them using the `-t` option:
@@ -424,7 +426,58 @@ adding the following to your configuration::
 
     CSS_FILE = "wide.css"
 
-.. _pelican-themes: :doc:`pelican-themes`
+Asset management
+----------------
+
+The `WEBASSETS` setting allows to use the `webassets`_ module to manage assets
+(css, js). The module must first be installed::
+
+    pip install webassets
+
+`webassets` allows to concatenate your assets and to use almost all of the
+hype tools of the moment (see the `documentation`_):
+
+* css minifier (`cssmin`, `yuicompressor`, ...)
+* css compiler (`less`, `sass`, ...)
+* js minifier (`uglifyjs`, `yuicompressor`, `closure`, ...)
+
+Others filters include gzip compression, integration of images in css with
+`datauri` and more. Webassets 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.
+
+When using it with Pelican, `webassets` is configured to process assets in the
+``OUTPUT_PATH/theme`` directory. You can use it in your templates with a
+template tag, 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 the version identifier:
+
+.. code-block:: html
+
+    <link href="http://{SITEURL}/theme/css/style.min.css?b3a7c807" rel="stylesheet">
+
+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="{{ ASSETS_URL }}"></script>
+    {% endassets %}
+
+will produce a minified and gzipped js file:
+
+.. code-block:: html
+
+    <script src="http://{SITEURL}/theme/js/packed.js?00703b9d"></script>
+
+.. _webassets: https://github.com/miracle2k/webassets
+.. _documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html
 
 Example settings
 ================

docs/tips.rst

@@ -10,6 +10,26 @@ GitHub comes with an interesting "pages" feature: you can upload things there
 and it will be available directly from their servers. As Pelican is a static
 file generator, we can take advantage of this.
 
+User Pages
+----------
+Github allows you to create user pages in the form of ``username.github.com``. 
+Whatever is created in master branch will be published. For this purposes just 
+the output generated by pelican needs to pushed at github.
+
+So given a repository containing your articles, just run pelican over the posts 
+and deploy the master branch at github::
+
+    $ pelican -s pelican.conf.py ./path/to/posts -o /path/to/output
+
+Now add all the files in the output directory generated by pelican::
+
+    $ git add /path/to/output/*
+    $ git commit -am "Your Message"
+    $ git push origin master
+
+Project Pages
+-------------
+For creating Project pages, a branch called ``gh-pages`` is used for publishing.
 The excellent `ghp-import <https://github.com/davisp/ghp-import>`_ makes this
 really easy. You will have to install it::
 
@@ -31,3 +51,4 @@ Put the following into `.git/hooks/post-commit`::
 
     pelican -s pelican.conf.py . && ghp-import output && git push origin
     gh-pages
+