Extending Nikola

Command Plugins

When you run nikola --help you will see something like this:

$ nikola help
Nikola is a tool to create static websites and blogs. For full documentation and more
information, please visit https://getnikola.com/


Available commands:
nikola auto                 automatically detect site changes, rebuild
                            and optionally refresh a browser
nikola bootswatch_theme     given a swatch name from bootswatch.com and a
                            parent theme, creates a custom theme
nikola build                run tasks
nikola check                check links and files in the generated site
nikola clean                clean action / remove targets
nikola console              start an interactive python console with access to
                            your site and configuration
nikola deploy               deploy the site
nikola dumpdb               dump dependency DB
nikola forget               clear successful run status from internal DB
nikola help                 show help
nikola ignore               ignore task (skip) on subsequent runs
nikola import_blogger       import a blogger dump
nikola import_feed          import a RSS/Atom dump
nikola import_wordpress     import a WordPress dump
nikola init                 create a Nikola site in the specified folder
nikola list                 list tasks from dodo file
nikola mincss               apply mincss to the generated site
nikola new_post             create a new blog post or site page
nikola run                  run tasks
nikola serve                start the test webserver
nikola strace               use strace to list file_deps and targets
nikola theme                manage themes
nikola version              print the Nikola version number

nikola help                 show help / reference
nikola help <command>       show command usage
nikola help <task-name>     show task usage

That will give you a list of all avail­able com­mands in your ver­sion of Niko­la. Each and ev­ery one of those is a plug­in. Let’s look at a typ­i­cal ex­am­ple:

First, the serve.plugin file:

[Core]
Name = serve
Module = serve

[Documentation]
Author = Roberto Alsina
Version = 0.1
Website = https://getnikola.com
Description = Start test server.

For your own plugin, just change the values in a sensible way. The Module will be used to find the matching Python module, in this case serve.py, from which this is the interesting bit:

from nikola.plugin_categories import Command

# You have to inherit Command for this to be a
# command plugin:

class CommandServe(Command):
    """Start test server."""

    name = "serve"
    doc_usage = "[options]"
    doc_purpose = "start the test webserver"

    cmd_options = (
        {
            'name': 'port',
            'short': 'p',
            'long': 'port',
            'default': 8000,
            'type': int,
            'help': 'Port number (default: 8000)',
        },
        {
            'name': 'address',
            'short': 'a',
            'long': '--address',
            'type': str,
            'default': '127.0.0.1',
            'help': 'Address to bind (default: 127.0.0.1)',
        },
    )

    def _execute(self, options, args):
        """Start test server."""
        out_dir = self.site.config['OUTPUT_FOLDER']
        if not os.path.isdir(out_dir):
            print("Error: Missing '{0}' folder?".format(out_dir))
        else:
            os.chdir(out_dir)
            httpd = HTTPServer((options['address'], options['port']),
                            OurHTTPRequestHandler)
            sa = httpd.socket.getsockname()
            print("Serving HTTP on", sa[0], "port", sa[1], "...")
            httpd.serve_forever()

As mentioned above, a plugin can have options, which the user can see by doing nikola help command and can later use, for example:

$ nikola help serve
Purpose: start the test webserver
Usage:   nikola serve [options]

Options:
-p ARG, --port=ARG        Port number (default: 8000)
-a ARG, ----address=ARG   Address to bind (default: 127.0.0.1)

$ nikola serve -p 9000
Serving HTTP on 127.0.0.1 port 9000 ...

So, what can you do with com­mand­s? Well, any­thing you wan­t, re­al­ly. I have im­ple­ment­ed a sort of plan­et us­ing it. So, be cre­ative, and if you do some­thing in­ter­est­ing, let me know ;-)

TemplateSystem Plugins

Nikola supports Mako and Jinja2. If you prefer some other templating system, then you will have to write a TemplateSystem plugin. Here’s how they work. First, you have to create a .plugin file. Here’s the one for the Mako plugin:

[Core]
Name = mako
Module = mako

[Documentation]
Author = Roberto Alsina
Version = 0.1
Website = https://getnikola.com
Description = Support for Mako templates.

You will have to re­place “mako” with your tem­plate sys­tem’s name, and oth­er da­ta in the ob­vi­ous ways.

The “Mod­ule” op­tion is the name of the mod­ule, which has to look some­thing like this, a stub for a hy­po­thet­i­cal sys­tem called “Tem­plater”:

from nikola.plugin_categories import TemplateSystem

# You have to inherit TemplateSystem

class TemplaterTemplates(TemplateSystem):
    """Wrapper for Templater templates."""

    # name has to match Name in the .plugin file
    name = "templater"

    # A list of directories where the templates will be
    # located. Most template systems have some sort of
    # template loading tool that can use this.
    def set_directories(self, directories, cache_folder):
        """Sets the list of folders where templates are located and cache."""
        pass

    # You *must* implement this, even if to return []
    # It should return a list of all the files that,
    # when changed, may affect the template's output.
    # usually this involves template inheritance and
    # inclusion.
    def template_deps(self, template_name):
        """Returns filenames which are dependencies for a template."""
        return []

    def render_template(self, template_name, output_name, context):
        """Renders template to a file using context.

        This must save the data to output_name *and* return it
        so that the caller may do additional processing.
        """
        pass

    # The method that does the actual rendering.
    # template_name is the name of the template file,
    # context is a dictionary containing the data the template
    # uses for rendering.
    def render_template_to_string(self, template, context):
        """Renders template to a string using context. """
        pass

    def inject_directory(self, directory):
        """Injects the directory with the lowest priority in the
        template search mechanism."""
        pass

You can see a re­al ex­am­ple in the Jin­ja plug­in

Task Plugins

If you want to do something that depends on the data in your site, you probably want to do a Task plugin, which will make it be part of the nikola build command. These are the currently available tasks, all provided by plugins:

$ nikola list
Scanning posts....done!
build_bundles
build_less
copy_assets
copy_files
post_render
redirect
render_archive
render_galleries
render_galleries_clean
render_indexes
render_listings
render_pages
render_posts
render_rss
render_site
render_sources
render_tags
sitemap

These have access to the site object which contains your timeline and your configuration.

The critical bit of Task plugins is their gen_tasks method, which yields doit tasks.

The details of how to handle dependencies, etc., are a bit too much for this document, so I’ll just leave you with an example, the copy_assets task. First the task_copy_assets.plugin file, which you should copy and edit in the logical ways:

[Core]
Name = copy_assets
Module = task_copy_assets

[Documentation]
Author = Roberto Alsina
Version = 0.1
Website = https://getnikola.com
Description = Copy theme assets into output.

And the task_copy_assets.py file, in its entirety:

import os

from nikola.plugin_categories import Task
from nikola import utils

# Have to inherit Task to be a task plugin
class CopyAssets(Task):
    """Copy theme assets into output."""

    name = "copy_assets"

    # This yields the tasks
    def gen_tasks(self):
        """Create tasks to copy the assets of the whole theme chain.

        If a file is present on two themes, use the version
        from the "youngest" theme.
        """

        # I put all the configurations and data the plugin uses
        # in a dictionary because utils.config_changed will
        # make it so that if these change, this task will be
        # marked out of date, and run again.

        kw = {
            "themes": self.site.THEMES,
            "output_folder": self.site.config['OUTPUT_FOLDER'],
            "filters": self.site.config['FILTERS'],
        }

        tasks = {}
        for theme_name in kw['themes']:
            src = os.path.join(utils.get_theme_path(theme_name), 'assets')
            dst = os.path.join(kw['output_folder'], 'assets')
            for task in utils.copy_tree(src, dst):
                if task['name'] in tasks:
                    continue
                tasks[task['name']] = task
                task['uptodate'] = task.get('uptodate', []) + \
                    [utils.config_changed(kw)]
                task['basename'] = self.name
                # If your task generates files, please do this.
                yield utils.apply_filters(task, kw['filters'])

PageCompiler Plugins

These plug­ins im­ple­ment markup lan­guages, they take sources for posts or pages and cre­ate HTML or oth­er out­put files. A good ex­am­ple is the mis­a­ka plug­in.

They must provide:

compile_html

Func­tion that builds a file.

create_post

Func­tion that cre­ates an emp­ty file with some meta­da­ta in it.

If the compiler produces something other than HTML files, it should also implement extension which returns the preferred extension for the output file.

These plugins can also be used to extract metadata from a file. To do so, the plugin may implement read_metadata that will return a dict containing the metadata contained in the file.

RestExtension Plugins

Im­ple­ment di­rec­tives for re­Struc­tured­Tex­t, see me­di­a.py for a sim­ple ex­am­ple.

If your out­put de­pends on a con­fig val­ue, you need to make your post record a de­pen­den­cy on a pseu­do-­path, like this:

####MAGIC####CONFIG:OPTIONNAME

Then, whenever the OPTIONNAME option is changed in conf.py, the file will be rebuilt.

If your directive depends or may depend on the whole timeline (like the post-list directive, where adding new posts to the site could make it stale), you should record a dependency on the pseudo-path ####­MAG­IC####­TIME­LINE.

MarkdownExtension Plugins

Im­ple­ment Mark­down ex­ten­sion­s, see mdx_niko­la.py for a sim­ple ex­am­ple.

Note that Python mark­down ex­ten­sions are of­ten al­so avail­able as sep­a­rate pack­ages. This is on­ly meant to ship ex­ten­sions along with Niko­la.

SignalHandler Plugins

These plugins extend the SignalHandler class and connect to one or more signals via blinker.

The easiest way to do this is to reimplement set_site() and just connect to whatever signals you want there.

Cur­rent­ly Niko­la emits the fol­low­ing sig­nal­s:

sighandlers_loaded

Right af­ter Sig­nal­Han­dler plug­in ac­ti­va­tion.

initialized

When all tasks are load­ed.

configured

When all the con­fig­u­ra­tion file is pro­cessed. Note that plug­ins are ac­ti­vat­ed be­fore this is emit­ted.

scanned

Af­ter posts are scanned.

new_post / new_page

When a new post is created, using the nikola new_post/nikola new_page commands. The signal data contains the path of the file, and the metadata file (if there is one).

existing_post / existing_page

When a new post fails to be created due to a title conflict. Contains the same data as new_post.

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:

{
 'last_deploy: # datetime object for the last deployed time,
 'new_deploy': # datetime object for the current deployed time,
 'clean': # whether there was a record of a last deployment,
 'deployed': # all files deployed after the last deploy,
 'undeployed': # all files not deployed since they are either future posts/drafts
}

compiled

When a post/­page is com­piled from its source to htm­l, be­fore any­thing else is done with it. The sig­nal da­ta is in the for­m:

{
 'source': # the path to the source file
 'dest': # the path to the cache file for the post/page
 'post': # the Post object for the post/page
}

One ex­am­ple is the de­ploy_hooks plug­in.

ConfigPlugin Plugins

Does noth­ing speci­fic, can be used to mod­i­fy the site ob­ject (and thus the con­fig).

Put all the magic you want in set_site(), and don’t forget to run the one from super(). Example plugin: navstories

PostScanner Plugins

Get posts and sto­ries from “some­where” to be added to the time­line. The on­ly cur­rent­ly ex­ist­ing plug­in of this kind reads them from disk.

Template-based Shortcodes

Another way to define a new shortcode is to add a template file to the shortcodes directory of your site. The template file must have the shortcode name as the basename and the extension .tmpl. For example, if you want to add a new shortcode named foo, create the template file as shortcodes/foo.tmpl.

When the shortcode is encountered, the matching template will be rendered with its context provided by the arguments given in the shortcode. Keyword arguments are passed directly, i.e. the key becomes the variable name in the template namespace with a matching string value. Non-keyword arguments are passed as string values in a tuple named _args. As for normal shortcodes with a handler function, site and data will be added to the keyword arguments.

Ex­am­ple:

The fol­low­ing short­code:

{{% foo bar="baz" spam %}}

With a template in shortcodes/foo.tmpl with this content (using Jinja2 syntax in this example):

<div class="{{ _args[0] if _args else 'ham' }}">{{ bar }}</div>

Will re­sult in this out­put:

<div class="spam">baz</div>