Imported Upstream version 7.0.1upstream/7.0.1

1 files changed, 64 insertions, 4 deletions

diff --git a/docs/extending.txt b/docs/extending.txt
index fb216c5..f8b685a 100644
--- a/docs/extending.txt
+++ b/docs/extending.txt
@@ -1,6 +1,6 @@
 .. title: Extending Nikola
 .. slug: extending
-.. date: 2012/03/30 23:00
+.. date: 2012-03-30 23:00:00 UTC-03:00
 .. tags:
 .. link:
 .. description:
@@ -8,7 +8,7 @@
 Extending Nikola
 ================
 
-:Version: 6.4.0
+:Version: 7.0.1
 :Author: Roberto Alsina <ralsina@netmanagers.com.ar>
 
 .. class:: alert alert-info pull-right
@@ -369,6 +369,11 @@ RestExtension Plugins
 
 Implement directives for reStructuredText, see ``media.py`` for a simple example.
 
+MarkdownExtension Plugins
+-------------------------
+
+Implement Markdown extensions, see ``mdx_nikola.py`` for a simple example.
+
 SignalHandler Plugins
 ---------------------
 
@@ -383,15 +388,17 @@ Currently Nikola emits the following signals:
 ``sighandlers_loaded``
     Right after SignalHandler plugin activation.
 ``initialized``
-    Right after plugin activation.
+    When all tasks are loaded.
 ``configured``
     When all the configuration file is processed. Note that plugins are activated before this is emitted.
+``scanned``
+    After posts are scanned.
 ``new_post``
     When a new post is created, using the ``nikola new_post`` command.  The signal
     data contains the path of the file, and the metadata file (if there is one).
 ``deployed``
     When the ``nikola deploy`` command is run, and there is at least one new
-    entry/post since ``last_deploy``.  The signal data is of the form ::
+    entry/post since ``last_deploy``.  The signal data is of the form::
 
         {
          'last_deploy: # datetime object for the last deployed time,
@@ -436,3 +443,56 @@ Here's the relevant code from the tag plugin.
                               self.site.config['TAG_PATH'], self.slugify_name(name) + ".xml"] if
                 _f]
 
+Template Hooks
+==============
+
+Plugins can use a hook system for adding stuff into templates.  In order to use
+it, a plugin must register itself.  The following hooks currently exist:
+
+* ``extra_head`` (not equal to the config option!)
+* ``body_end`` (not equal to the config option!)
+* ``page_header``
+* ``menu``
+* ``menu_alt`` (right-side menu in bootstrap, after ``menu`` in base)
+* ``page_footer``
+
+For example, in order to register a script into ``extra_head``:
+
+.. code-block:: python
+
+    # In set_site
+    site.template_hooks['extra_head'].append('<script src="/assets/js/fancyplugin.js">')
+
+There is also another API available.  It allows use of dynamically generated
+HTML:
+
+.. code-block:: python
+
+    # In set_site
+    def generate_html_bit(name, ftype='js'):
+        return '<script src="/assets/{t}/{n}.{t}">'.format(n=name, t=ftype)
+
+    site.template_hooks['extra_head'].append(generate_html_bit, False, 'fancyplugin', type='js')
+
+
+The second argument to ``append()`` is used to determine whether the function
+needs access to the current template context and the site.  If it it set to
+``True``, the function will also receive ``site`` and ``context`` keyword
+arguments.  Example use:
+
+
+.. code-block:: python
+
+    # In set_site
+    def greeting(addr, endswith='', site=None, context=None):
+        if context['lang'] == 'en':
+            greet = u'Hello'
+        elif context['lang'] == 'es':
+            greet = u'¡Hola'
+
+        t = u' BLOG_TITLE = {0}'.format(site.config['BLOG_TITLE'](context['lang']))
+
+        return u'<h3>{greet} {addr}{endswith}</h3>'.format(greet=greet, addr=addr,
+        endswith=endswith) + t
+
+    site.template_hooks['page_header'].append(greeting, True, u'Nikola Tesla', endswith=u'!')