diff options
Diffstat (limited to 'docs/extending.txt')
| -rw-r--r-- | docs/extending.txt | 68 |
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'!') |