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 available commands in your version of Nikola. Each and every one of those is a plugin. Let's look at a typical example:

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 commands? Well, anything you want, really. I have implemented a sort of planet using it. So, be creative, and if you do something interesting, 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 replace "mako" with your template system's name, and other data in the obvious ways.

The "Module" option is the name of the module, which has to look something like this, a stub for a hypothetical system called "Templater":

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 real example in the Jinja plugin

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 plugins implement markup languages, they take sources for posts or pages and create HTML or other output files. A good example is the misaka plugin or the built-in compiler plugins.

They must provide:

compile

Function that builds a file.

create_post

Function that creates an empty file with some metadata 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 must set supports_metadata to True and implement read_metadata that will return a dict containing the metadata contained in the file. Optionally, it may list metadata_conditions (see MetadataExtractor Plugins below)

MetadataExtractor Plugins

Plugins that extract metadata from posts. If they are based on post content, they must implement _extract_metadata_from_text (takes source of a post returns a dict of metadata). They may also implement split_metadata_from_text, extract_text. If they are based on filenames, they only need extract_filename. If support_write is set to True, write_metadata must be implemented.

Every extractor must be configured properly. The name, source (from the MetaSource enum in metadata_extractors) and priority (MetaPriority) fields are mandatory. There might also be a list of conditions (tuples of MetaCondition, arg), used to check if an extractor can provide metadata, a compiled regular expression used to split metadata (split_metadata_re, may be None, used by default split_metadata_from_text), a list of requirements (3-tuples: import name, pip name, friendly name), map_from (name of METADATA_MAPPING to use, if any) and supports_write (whether the extractor supports writing metadata in the desired format).

For more details, see the definition in plugin_categories.py and default extractors in metadata_extractors.py.

RestExtension Plugins

Implement directives for reStructuredText, see media.py for a simple example.

If your output depends on a config value, you need to make your post record a dependency on a pseudo-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 ####MAGIC####TIMELINE.

MarkdownExtension Plugins

Implement Markdown extensions, see mdx_nikola.py for a simple example.

Note that Python markdown extensions are often also available as separate packages. This is only meant to ship extensions along with Nikola.

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.

Currently Nikola emits the following signals:

sighandlers_loaded

Right after SignalHandler plugin activation.

initialized

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 / 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 compiled from its source to html, before anything else is done with it. The signal data is in the form:

{
 '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 example is the deploy_hooks plugin.

ConfigPlugin Plugins

Does nothing specific, can be used to modify the site object (and thus the config).

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 pages from "somewhere" to be added to the timeline. The only currently existing plugin of this kind reads them from disk.

# In set_site
site.register_path_handler('tag_rss', self.tag_rss_path)

# And these always take name and lang as arguments and return a list of
# path elements.
def tag_rss_path(self, name, lang):
    return [_f for _f in [self.site.config['TRANSLATIONS'][lang],
                          self.site.config['TAG_PATH'], self.slugify_name(name, lang) + ".xml"] if
            _f]

# In set_site
site.template_hooks['extra_head'].append('<script src="/assets/js/fancyplugin.js">')

# In set_site
def generate_html_bit(name, ftype='js'):
    """Generate HTML for an asset."""
    return '<script src="/assets/{t}/{n}.{t}">'.format(n=name, t=ftype)

site.template_hooks['extra_head'].append(generate_html_bit, False, 'fancyplugin', ftype='js')

# In set_site
def greeting(addr, endswith='', site=None, context=None):
    """Greet someone."""
    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'!')

{{% foo %}}  # No arguments
    {{% foo bar %}}  # One argument, containing "bar"
    {{% foo bar baz=bat %}}  # Two arguments, one containing "bar", one called "baz" containing "bat"

    {{% foo %}}Some text{{% /foo %}}  # one argument called "data" containing "Some text"

{{% foo bar baz=bat beep %}}Some text{{% /foo %}}

foo_handler("bar", "beep", baz="bat", data="Some text", site=whatever)

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.

Example:

The following shortcode:

{{% 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 result in this output

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

The Build Command

Nikola's goal is similar, deep at heart, to a Makefile. Take sources, compile them into something, in this case a website. Instead of a Makefile, Nikola uses doit

Doit has the concept of "tasks". The 1 minute summary of tasks is that they have:

actions

What the task does. For example, convert a markdown document into HTML.

dependencies

If this file changes, then we need to redo the actions. If this configuration option changes, redo it, etc.

targets

Files that the action generates. No two actions can have the same targets.

basename:name

Each task is identified by either a name or a basename:name pair.

So, what Nikola does, when you use the build command, is to read the configuration conf.py from the current folder, instantiate the Nikola class, and have it generate a whole list of tasks for doit to process. Then doit will decide which tasks need doing, and do them, in the right order.

The place where the tasks are generated is in Nikola.gen_tasks, which collects tasks from all the plugins inheriting BaseTask, massages them a bit, then passes them to doit.

So, if you want things to happen on build you want to create a Task plugin, or extend one of the existing ones.

Posts and Pages

Nikola has a concept of posts and pages. Both are more or less the same thing, except posts are added into RSS feeds and pages are not. All of them are in a list called "the timeline" formed by objects of class Post.

When you are creating a task that needs the list of posts and/or pages (for example, the RSS creation plugin) on task execution time, your plugin should call self.site.scan_posts() in gen_tasks to ensure the timeline is created and available in self.site.timeline. You should not modify the timeline, because it will cause consistency issues.

Your plugin can use the timeline to generate "stuff" (technical term). For example, Nikola comes with plugins that use the timeline to create a website (surprised?).

The workflow included with nikola is as follows (incomplete!):

1. The post is assigned a compiler based on its extension and the COMPILERS option.

2. The compiler is applied to the post data and a "HTML fragment" is produced. That fragment is stored in a cache (the posts plugin).

3. The configured theme has templates (and a template engine), which are applied to the post's HTML fragment and metadata (the pages plugin).

4. The original sources for the post are copied to some accessible place (the sources plugin).

5. If the post is tagged, some pages and RSS feeds for each tag are updated (the tags plugin).

6. If the post is new, it's included in the blog's RSS feed (the rss plugin).

7. The post is added in the right place in the index pages for the blog (the indexes plugin).

8. CSS/JS/Images for the theme are put in the right places (the copy_assets and bundles plugins).

9. A File describing the whole site is created (the sitemap plugin).

You can add whatever you want to that list: just create a plugin for it.

You can also expand Nikola's capabilities at several points:

compilers

Nikola supports a variety of markups. If you want to add another one, you need to create a Compiler plugin.

templates

Nikola's themes can use Jinja2 or Mako templates. If you prefer another template system, you have to create a TemplateSystem plugin.

themes

To change how the generated site looks, you can create custom themes.

And of course, you can also replace or extend each of the existing plugins.

Nikola Architecture

All You Need to Know

After you have Nikola installed:

Create an empty site (with a setup wizard):

nikola init mysite

You can create a site with demo files in it with nikola init --demo mysite

The rest of these commands have to be executed inside the new mysite folder.

Create a post:

nikola new_post

Edit the post:

The filename should be in the output of the previous command. You can also use nikola new_post -e to open an editor automatically.

Build the site:

nikola build

Start the test server and open a browser:

nikola serve -b

That should get you going. If you want to know more, this manual will always be here for you.

DON'T READ THIS MANUAL. IF YOU NEED TO READ IT I FAILED, JUST USE THE THING.

On the other hand, if anything about Nikola is not as obvious as it should be, by all means tell me about it :-)

What's Nikola and what can you do with it?

Nikola is a static website and blog generator. The very short explanation is that it takes some texts you wrote, and uses them to create a folder full of HTML files. If you upload that folder to a server, you will have a rather full-featured website, done with little effort.

Its original goal is to create blogs, but it supports most kind of sites, and can be used as a CMS, as long as what you present to the user is your own content instead of something the user generates.

Nikola can do:

• A blog (example)

• Your company's site

• Your personal site

• A software project's site (example)

• A book's site

Since Nikola-based sites don't run any code on the server, there is no way to process user input in forms.

Nikola can't do:

• Twitter

• Facebook

• An Issue tracker

• Anything with forms, really (except for comments!)

Keep in mind that "static" doesn't mean boring. You can have animations or whatever fancy CSS3/HTML5 thingie you like. It only means all that HTML is generated already before being uploaded. On the other hand, Nikola sites will tend to be content-heavy. What Nikola is good at is at putting what you write out there.

Getting Help

Get help here!

TL;DR:

• You can file bugs at the issue tracker

• You can discuss Nikola at the nikola-discuss google group

• You can subscribe to the Nikola Blog

• You can follow Nikola on Twitter

Why Static?

Most "modern" websites are dynamic in the sense that the contents of the site live in a database, and are converted into presentation-ready HTML only when a user wants to see the page. That's great. However, it presents some minor issues that static site generators try to solve.

In a static site, the whole site, every page, everything, is created before the first user even sees it and uploaded to the server as a simple folder full of HTML files (and images, CSS, etc).

So, let's see some reasons for using static sites:

Security

Dynamic sites are prone to experience security issues. The solution for that is constant vigilance, keeping the software behind the site updated, and plain old good luck. The stack of software used to provide a static site, like those Nikola generates, is much smaller (Just a web server).

A smaller software stack implies less security risk.

Obsolescence

If you create a site using (for example) WordPress, what happens when WordPress releases a new version? You have to update your WordPress. That is not optional, because of security and support issues. If I release a new version of Nikola, and you don't update, nothing happens. You can continue to use the version you have now forever, no problems.

Also, in the longer term, the very foundations of dynamic sites shift. Can you still deploy a blog software based on Django 0.96? What happens when your host stops supporting the PHP version you rely on? And so on.

You may say those are long term issues, or that they won't matter for years. Well, I believe things should work forever, or as close to it as we can make them. Nikola's static output and its input files will work as long as you can install Python 3.4 or newer under Linux, Windows, or OS X and can find a server that sends files over HTTP. That's probably 10 or 15 years at least.

Also, static sites are easily handled by the Internet Archive.

Cost and Performance

On dynamic sites, every time a reader wants a page, a whole lot of database queries are made. Then a whole pile of code chews that data, and HTML is produced, which is sent to the user. All that requires CPU and memory.

On a static site, the highly optimized HTTP server reads the file from disk (or, if it's a popular file, from disk cache), and sends it to the user. You could probably serve a bazillion (technical term) page views from a phone using static sites.

Lock-in

On server-side blog platforms, sometimes you can't export your own data, or it's in strange formats you can't use in other services. I have switched blogging platforms from Advogato to PyCs to two homebrew systems, to Nikola, and have never lost a file, a URL, or a comment. That's because I have always had my own data in a format of my choice.

With Nikola, you own your files, and you can do anything with them.

Components

Nikola provides the following features:

• Blog support, including:

  • Indexes

  • RSS and Atom feeds

  • Tags and categories, with pages and feeds

  • Author pages and feeds (not generated if ENABLE_AUTHOR_PAGES is set to False or there is only one author)

  • Archives with custom granularity (yearly or monthly)

  • Comments

• Static pages (not part of the blog)

• Math rendering (via MathJax)

• Custom output paths for generated pages

• Pretty URLs (without .html) that don’t need web server support

• Easy page template customization

• Internationalization support (my own blog is English and Spanish)

• Sitemap generation (for search engines)

• Custom deployment (if it’s a command, you can use it)

• GitHub Pages deployment

• Themes, easy appearance customization

• Multiple input formats, including reStructuredText and Markdown

• Easy-to-create image galleries

• Image thumbnail generation

• Support for displaying source code listings

• Custom search

• Asset (CSS/JS) bundling

• gzip compression (for sending via your web server)

• Open Graph, Twitter Cards

• Hyphenation

• Custom post processing filters (eg. for minifying files or better typography)

Getting Started

To set Nikola up and create your first site, read the Getting Started Guide.

Creating a Blog Post

To create a new post, the easiest way is to run nikola new_post. You will be asked for a title for your post, and it will tell you where the post's file is located.

By default, that file will contain also some extra information about your post ("the metadata"). It can be placed in a separate file by using the -2 option, but it's generally easier to keep it in a single location.

The contents of your post have to be written (by default) in reStructuredText but you can use a lot of different markups using the -f option.

Currently, Nikola supports reStructuredText, Markdown, Jupyter Notebooks, HTML as input, can also use Pandoc for conversion, and has support for BBCode, CreoleWiki, txt2tags, Textile and more via plugins — for more details, read the input format documentation. You can learn reStructuredText syntax with the reST quickstart.

Please note that Nikola does not support encodings other than UTF-8. Make sure to convert your input files to that encoding to avoid issues. It will prevent bugs, and Nikola will write UTF-8 output anyway.

You can control what markup compiler is used for each file extension with the COMPILERS option. The default configuration expects them to be placed in posts but that can be changed (see below, the POSTS and PAGES options)

This is how it works:

$ nikola new_post
Creating New Post
-----------------

Title: How to make money
Scanning posts....done!
INFO: new_post: Your post's text is at: posts/how-to-make-money.rst

The content of that file is as follows:

.. title: How to make money
.. slug: how-to-make-money
.. date: 2012-09-15 19:52:05 UTC
.. tags:
.. link:
.. description:
.. type: text

Write your post here.

You can edit these files with your favorite text editor, and once you are happy with the contents, generate the pages using nikola build.

The post page is generated by default using the post.tmpl template, which you can use to customize the output. You can also customize paths and the template filename itself — see How does Nikola decide where posts should go?

ADDITIONAL_METADATA = {
    'author': 'John Doe'
}

.. name: value

.. title: How to make money
.. slug: how-to-make-money
.. date: 2012-09-15 19:52:05 UTC

{
    "nikola": {
        "title": "How to make money",
        "slug": "how-to-make-money",
        "date": "2012-09-15 19:52:05 UTC"
    }
}

---
title: How to make money
slug: how-to-make-money
date: 2012-09-15 19:52:05 UTC
---

+++
title = "How to make money"
slug =  "how-to-make-money"
date = "2012-09-15 19:52:05 UTC"
+++

How to make money
=================

:slug: how-to-make-money
:date: 2012-09-15 19:52:05 UTC

title: How to make money
slug: how-to-make-money
date: 2012-09-15 19:52:05 UTC

<html>
    <head>
        <title>My super title</title>
        <meta name="tags" content="thats, awesome" />
        <meta name="date" content="2012-07-09 22:28" />
        <meta name="modified" content="2012-07-10 20:14" />
        <meta name="category" content="yeah" />
        <meta name="authors" content="Conan Doyle" />
        <meta name="summary" content="Short version for index and feeds" />
    </head>
    <body>
        This is the content of my super blog post.
    </body>
</html>

METADATA_MAPPING = {
    "rest_docinfo": {"summary": "description", "modified": "updated"},
    "markdown_metadata": {"summary": "description", "modified": "updated"}
    "html_metadata": {"summary": "description", "modified": "updated"}
}

METADATA_MAPPING = {
    "yaml": {"lastmod": "updated"},
    "toml": {"lastmod": "updated"}
}

METADATA_VALUE_MAPPING = {
    "yaml": {"keywords": lambda value: ', '.join(value)},  # yaml: 'keywords' list -> str
    "nikola": {
        "widgets": lambda value: value.split(', '),  # nikola: 'widgets' comma-separated string -> list
        "tags": str.lower  # nikola: force lowercase 'tags' (input would be string)
     }
}

TRANSLATIONS_PATTERN = "{path}.{lang}.{ext}"

# POSTS and PAGES contains (wildcard, destination, template) tuples.
#
# The wildcard is used to generate a list of post source files
# (whatever/thing.rst, for example).
#
# That fragment could have an associated metadata file (whatever/thing.meta),
# and optionally translated files (example for Spanish, with code "es"):
#     whatever/thing.es.rst and whatever/thing.es.meta
#
#     This assumes you use the default TRANSLATIONS_PATTERN.
#
# From those files, a set of HTML fragment files will be generated:
# cache/whatever/thing.html (and maybe cache/whatever/thing.html.es)
#
# These files are combined with the template to produce rendered
# pages, which will be placed at
# output/TRANSLATIONS[lang]/destination/pagename.html
#
# where "pagename" is the "slug" specified in the metadata file.
# The page might also be placed in /destination/pagename/index.html
# if PRETTY_URLS are enabled.
#
# The difference between POSTS and PAGES is that POSTS are added
# to feeds, indexes, tag lists and archives and are considered part
# of a blog, while PAGES are just independent HTML pages.
#
# Finally, note that destination can be translated, i.e. you can
# specify a different translation folder per language. Example:
#     PAGES = (
#         ("pages/*.rst", {"en": "pages", "de": "seiten"}, "page.tmpl"),
#         ("pages/*.md", {"en": "pages", "de": "seiten"}, "page.tmpl"),
#     )

POSTS = (
    ("posts/*.rst", "posts", "post.tmpl"),
    ("posts/*.txt", "posts", "post.tmpl"),
    ("posts/*.html", "posts", "post.tmpl"),
)
PAGES = (
    ("pages/*.rst", "pages", "page.tmpl"),
    ("pages/*.txt", "pages", "page.tmpl"),
    ("pages/*.html", "pages", "page.tmpl"),
)

$ nikola help new_post
Purpose: create a new blog post or site page
Usage:   nikola new_post [options] [path]

Options:
  -p, --page                Create a page instead of a blog post. (see also: `nikola new_page`)
  -t ARG, --title=ARG       Title for the post.
  -a ARG, --author=ARG      Author of the post.
  --tags=ARG                Comma-separated tags for the post.
  -1                        Create the post with embedded metadata (single file format)
  -2                        Create the post with separate metadata (two file format)
  -e                        Open the post (and meta file, if any) in $EDITOR after creation.
  -f ARG, --format=ARG      Markup format for the post (use --available-formats for list)
  -F, --available-formats   List all available input formats
  -s                        Schedule the post based on recurrence rule
  -i ARG, --import=ARG      Import an existing file instead of creating a placeholder
  -d, --date-path           Create post with date path (eg. year/month/day, see NEW_POST_DATE_PATH_FORMAT in config)

# Use date-based path when creating posts?
# Can be enabled on a per-post basis with `nikola new_post -d`.
# NEW_POST_DATE_PATH = False

# What format to use when creating posts with date paths?
# Default is '%Y/%m/%d', other possibilities include '%Y' or '%Y/%m'.
# NEW_POST_DATE_PATH_FORMAT = '%Y/%m/%d'

.. TEASER_END

<!-- TEASER_END -->

.. TEASER_END: click to read the rest of the article

import re
TEASER_REGEXP = re.compile('<!--\s*(more|TEASER_END|END_TEASER)(:(.+))?\s*-->', re.IGNORECASE)

# A HTML fragment with the Read more... link.
# The following tags exist and are replaced for you:
# {link}        A link to the full post page.
# {read_more}   The string “Read more” in the current language.
# {{            A literal { (U+007B LEFT CURLY BRACKET)
# }}            A literal } (U+007D RIGHT CURLY BRACKET)
# READ_MORE_LINK = '<p class="more"><a href="{link}">{read_more}…</a></p>'

Featured Posts

Some themes, bootblog4 in particular, support featured posts. To mark a post as featured, simply set the status meta field to featured. All featured posts are available in index templates in a featured list, but only if this is the main blog index.

For bootblog4, you can display up to three posts as featured: one can be shown in a large gray box (jumbotron), and two more can appear in small white cards. In order to enable this feature, you need to add THEME_CONFIG to your configuration, and set it up properly:

THEME_CONFIG = {
    DEFAULT_LANG: {
        # Show the latest featured post in a large box, with the previewimage as its background.
        'featured_large': True,
        # Show the first (remaining) two featured posts in small boxes.
        'featured_small': True,
        # Show featured posts on mobile.
        'featured_on_mobile': True,
        # Show image in `featured_large` on mobile.
        # `featured_small` displays them only on desktop.
        'featured_large_image_on_mobile': False,
        # Strip HTML from featured post text.
        'featured_strip_html': True,
        # Contents of the sidebar, If empty, the sidebar is not displayed.
        'sidebar': ''
    }
}

You can pick betweeen (up to) 1, 2, or 3 featured posts. You can mix featured_large and featured_small, rest assured that Nikola will always display the latest posts no matter what setup you choose. If only one posts qualifies for the small cards, one card taking up all the width will appear.

Both featured box formats display an image to the right. You can set it by changing the previewimage meta value to the full path to the image (eg. .. previewimage: /images/featured1.png). This works best with images in portrait orientation.

Note that, due to space constraints, only the large box may show the image on mobile, below the text (this behavior can be disbled). Small boxes never display images on mobile. In particular: xs and sm display only the large image, and only if configured; md displays only the large image, lg displays all three images.

The boxes display only the teaser. We recommend keeping it short so you don’t get an ugly scrollbar.

Finally, here’s an example (you’ll need to imagine a scrollbar in the right box yourself):

SCHEDULE_RULE = 'RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR;BYHOUR=7;BYMINUTE=0;BYSECOND=0'

$ nikola new_post --schedule
# Creates a new post to be posted on Monday, 7am.
$ nikola new_post -s
# Creates a new post to be posted on Wednesday, 7am.
$ nikola new_post -s
# Creates a new post to be posted on Friday, 7am.
.
.
.

ERROR: Nikola: You have tags that are too similar: Nikola and nikola
ERROR: Nikola: Tag Nikola is used in: posts/second-post.rst
ERROR: Nikola: Tag nikola is used in: posts/1.rst

Creating a Page

Pages are the same as posts, except that:

• They are not added to the front page

• They don't appear on the RSS feed

• They use the page.tmpl template instead of post.tmpl by default

The default configuration expects the page's metadata and text files to be on the pages folder, but that can be changed (see PAGES option above).

You can create the page's files manually or use the new_post command with the -p option, which will place the files in the folder that has use_in_feed set to False.

In some places (including default directories and templates), pages are called stories for historic reasons. Both are synonyms for the same thing: pages that are not blog posts.

Supported input formats

Nikola supports multiple input formats. Out of the box, we have compilers available for:

• reStructuredText (default and pre-configured)

• Markdown

• Jupyter Notebook

• HTML

• PHP

• anything Pandoc supports (including Textile, DocBook, LaTeX, MediaWiki, TWiki, OPML, Emacs Org-Mode, txt2tags, Microsoft Word .docx, EPUB, Haddock markup)

Plus, we have specialized compilers in the Plugins Index for:

• AsciiDoc

• BBCode

• CommonMark

• IRC logs

• Markmin

• MediaWiki (smc.mw)

• Misaka

• ODT

• Emacs Org-Mode

• reST with HTML 5 output

• Textile

• txt2tags

• CreoleWiki

• WordPress posts

MARKDOWN_EXTENSIONS = ['fenced_code', 'codehilite', 'extra']

Shortcodes

This feature is "inspired" (copied wholesale) from Hugo so I will steal part of their docs too.

A shortcode is a simple snippet inside a content file that Nikola will render using a predefined template or custom code from a plugin.

To use them from plugins, please see Extending Nikola

{{% name parameters %}}

{{% highlight python %}} A bunch of code here {{% /highlight %}}

:sc:`{{% shortcode here %}}`

This uses the bar variable: ${bar}

{{% foo bar=bla %}}

This uses the bar variable: bla

{{% template %}}
<ul>
% for foo in bar:
<li>${foo}</li>
% endfor
</ul>
{{% /template %}}

The Global Context and Data files

There is a GLOBAL_CONTEXT field in your conf.py where you can put things you want to make available to your templates.

It will also contain things you put in a data/ directory within your site. You can use JSON, YAML or TOML files (with the appropriate file extensions: json/js, yaml/yml, toml/tml) that decode to Python dictionaries. For example, if you create data/foo.json containing this:

{"bar": "baz"}

Then your templates can use things like ${data['foo']['bar']} and it will be replaced by "baz".

Individual posts can also have a data file. Those are specified using the data meta field (path relative to conf.py, can be different in different post languages). Those are accessible as eg. ${post.data['bar']} in templates. Template-based shortcodes are a good idea in this case.

Data files can be useful for eg. auto-generated sites, where users provide JSON/YAML/TOML files and Nikola generates a large page with data from all data files. (This is especially useful with some automatic rebuild feature, like those documented in Deployment)

Data files are also available as global_data, to avoid name conflicts in shortcodes. (global_data works everywhere.)

Redirections

If you need a page to be available in more than one place, you can define redirections in your conf.py:

# A list of redirection tuples, [("foo/from.html", "/bar/to.html")].
#
# A HTML file will be created in output/foo/from.html that redirects
# to the "/bar/to.html" URL. notice that the "from" side MUST be a
# relative URL.
#
# If you don't need any of these, just set to []

REDIRECTIONS = [("index.html", "/weblog/index.html")]

It's better if you can do these using your web server's configuration, but if you can't, this will work.

Configuration

The configuration file is called conf.py and can be used to customize a lot of what Nikola does. Its syntax is python, but if you don't know the language, it still should not be terribly hard to grasp.

The default conf.py you get with Nikola should be fairly complete, and is quite commented.

You surely want to edit these options:

# Data about this site
BLOG_AUTHOR = "Your Name"  # (translatable)
BLOG_TITLE = "Demo Site"  # (translatable)
SITE_URL = "https://getnikola.com/"
BLOG_EMAIL = "joe@demo.site"
BLOG_DESCRIPTION = "This is a demo site for Nikola."  # (translatable)

Some options are marked with a (translatable) comment above or right next to them. For those options, two types of values can be provided:

• a string, which will be used for all languages

• a dict of language-value pairs, to have different values in each language

Customizing Your Site

There are lots of things you can do to personalize your website, but let's see the easy ones!

CSS tweaking

Using the default configuration, you can create a assets/css/custom.css file under files/ or in your theme and then it will be loaded from the <head> blocks of your site pages. Create it and put your CSS code there, for minimal disruption of the provided CSS files.

If you feel tempted to touch other files in assets, you probably will be better off with a custom theme.

If you want to use LESS or Sass for your custom CSS, or the theme you use contains LESS or Sass code that you want to override, you will need to install the LESS plugin or SASS plugin create a less or sass directory in your site root, put your .less or .scss files there and a targets file containing the list of files you want compiled.

Template tweaking and creating themes

If you really want to change the pages radically, you will want to do a custom theme.

Navigation Links

The NAVIGATION_LINKS option lets you define what links go in a sidebar or menu (depending on your theme) so you can link to important pages, or to other sites.

The format is a language-indexed dictionary, where each element is a tuple of tuples which are one of:

1. A (url, text) tuple, describing a link

2. A (((url, text), (url, text), (url, text)), title) tuple, describing a submenu / sublist.

Example:

NAVIGATION_LINKS = {
    DEFAULT_LANG: (
        ('/archive.html', 'Archives'),
        ('/categories/index.html', 'Tags'),
        ('/rss.xml', 'RSS'),
        ((('/foo', 'FOO'),
          ('/bar', 'BAR')), 'BAZ'),
    ),
}

Note

1. Support for submenus is theme-dependent. Only one level of submenus is supported.

2. Some themes, including the default Bootstrap theme, may present issues if the menu is too large. (in Bootstrap, the navbar can grow too large and cover contents.)

3. If you link to directories, make sure to follow STRIP_INDEXES. If it’s set to True, end your links with a /, otherwise end them with /index.html — or else they won’t be highlighted when active.

There’s also NAVIGATION_ALT_LINKS. Themes may display this somewhere else, or not at all. Bootstrap puts it on the right side of the header.

The SEARCH_FORM option contains the HTML code for a search form based on duckduckgo.com which should always work, but feel free to change it to something else.

Footer

CONTENT_FOOTER is displayed, small at the bottom of all pages, I use it for the copyright notice. The default shows a text formed using BLOG_AUTHOR, BLOG_EMAIL, the date and LICENSE. Note you need to use CONTENT_FOOTER_FORMATS instead of regular str.format or %-formatting, for compatibility with the translatable settings feature.

BODY_END

This option lets you define a HTML snippet that will be added at the bottom of body. The main usage is a Google analytics snippet or something similar, but you can really put anything there. Good place for JavaScript.

SOCIAL_BUTTONS_CODE

The SOCIAL_BUTTONS_CODE option lets you define a HTML snippet that will be added at the bottom of body. It defaults to a snippet for AddThis, but you can really put anything there. See social_buttons.html for more details.

Fancy Dates

Nikola can use various styles for presenting dates.

DATE_FORMAT

The date format to use if there is no JS or fancy dates are off. Compatible with CLDR syntax.

JS_DATE_FORMAT

The date format to use if fancy dates are on. Compatible with moment.js syntax.

DATE_FANCINESS = 0

Fancy dates are off, and DATE_FORMAT is used.

DATE_FANCINESS = 1

Dates are recalculated in user’s timezone. Requires JavaScript.

DATE_FANCINESS = 2

Dates are recalculated as relative time (eg. 2 days ago). Requires JavaScript.

In order to use fancy dates, your theme must support them. The built-in Bootstrap family supports it, but other themes might not by default.

For Mako:

<!-- required scripts -- best handled with bundles -->
<script src="/assets/js/moment-with-locales.min.js"></script>
<script src="/assets/js/fancydates.js"></script>

<!-- fancy dates code -->
<script>
moment.locale("${momentjs_locales[lang]}");
fancydates(${date_fanciness}, ${js_date_format});
</script>
<!-- end fancy dates code -->

For Jinja2:

<!-- required scripts -- best handled with bundles -->
<script src="/assets/js/moment-with-locales.min.js"></script>
<script src="/assets/js/fancydates.js"></script>

<!-- fancy dates code -->
<script>
moment.locale("{{ momentjs_locales[lang] }}");
fancydates({{ date_fanciness }}, {{ js_date_format }});
</script>
<!-- end fancy dates code -->

Adding Files

Any files you want to be in output/ but are not generated by Nikola (for example, favicon.ico) should be placed in files/. Remember that you can't have files that collide with files Nikola generates (it will give an error).

If you want to copy more than one folder of static files into output you can change the FILES_FOLDERS option:

# One or more folders containing files to be copied as-is into the output.
# The format is a dictionary of "source" "relative destination".
# Default is:
# FILES_FOLDERS = {'files': '' }
# Which means copy 'files' into 'output'

Custom Themes

If you prefer to have a custom appearance for your site, and modifying CSS files and settings (see Customizing Your Site for details) is not enough, you can create your own theme. See the Theming Nikola and Creating a Theme for more details. You can put them in a themes/ folder and set THEME to the directory name. You can also put them in directories listed in the EXTRA_THEMES_DIRS configuration variable.

Getting Extra Themes

There are a few themes for Nikola. They are available at the Themes Index. Nikola has a built-in theme download/install mechanism to install those themes — the theme command:

$ nikola theme -l
Themes:
-------
blogtxt
bootstrap3-gradients
⋮
⋮

$ nikola theme -i blogtxt
[2013-10-12T16:46:13Z] NOTICE: theme: Downloading:
https://themes.getnikola.com/v6/blogtxt.zip
[2013-10-12T16:46:15Z] NOTICE: theme: Extracting: blogtxt into themes

And there you are, you now have themes/blogtxt installed. It's very rudimentary, but it should work in most cases.

If you create a nice theme, please share it! You can do it as a pull request in the GitHub repository.

One other option is to tweak an existing theme using a different color scheme, typography and CSS in general. Nikola provides a subtheme command to create a custom theme by downloading free CSS files from http://bootswatch.com and http://hackerthemes.com

$ nikola subtheme -n custom_theme -s flatly -p bootstrap4
[2013-10-12T16:46:58Z] NOTICE: subtheme: Creating 'custom_theme' theme
from 'flatly' and 'bootstrap4'
[2013-10-12T16:46:58Z] NOTICE: subtheme: Downloading:
http://bootswatch.com/flatly/bootstrap.min.css
[2013-10-12T16:46:58Z] NOTICE: subtheme: Downloading:
http://bootswatch.com/flatly/bootstrap.css
[2013-10-12T16:46:59Z] NOTICE: subtheme: Theme created. Change the THEME setting to "custom_theme" to use it.

Play with it, there's cool stuff there. This feature was suggested by clodo.

Deployment

If you can specify your deployment procedure as a series of commands, you can put them in the DEPLOY_COMMANDS option, and run them with nikola deploy.

You can have multiple deployment presets. If you run nikola deploy, the default preset is executed. You can also specify the names of presets you want to run (eg. nikola deploy default, multiple presets are allowed).

One caveat is that if any command has a % in it, you should double them.

Here is an example, from my own site's deployment script:

DEPLOY_COMMANDS = {'default': [
    'rsync -rav --delete output/ ralsina@lateral.netmanagers.com.ar:/srv/www/lateral',
    'rdiff-backup output ~/blog-backup',
    "links -dump 'http://www.twingly.com/ping2?url=lateral.netmanagers.com.ar'",
]}

Other interesting ideas are using git as a deployment mechanism (or any other VCS for that matter), using lftp mirror or unison, or Dropbox. Any way you can think of to copy files from one place to another is good enough.

Comments

While Nikola creates static sites, there is a minimum level of user interaction you are probably expecting: comments.

Nikola supports several third party comment systems:

• DISQUS

• IntenseDebate

• LiveFyre

• Muut (Formerly moot)

• Facebook

• isso

• Commento

By default it will use DISQUS, but you can change by setting COMMENT_SYSTEM to one of "disqus", "intensedebate", "livefyre", "moot", "facebook", "isso" or "commento"

To use comments in a visible site, you should register with the service and then set the COMMENT_SYSTEM_ID option.

I recommend 3rd party comments, and specially DISQUS because:

1. It doesn't require any server-side software on your site

2. They offer you a way to export your comments, so you can take them with you if you need to.

3. It's free.

4. It's damn nice.

You can disable comments for a post by adding a "nocomments" metadata field to it:

.. nocomments: True

BODY_END = """
<script src="//cdn.moot.it/1/moot.min.js"></script>
"""
EXTRA_HEAD_DATA = """
<link rel="stylesheet" type="text/css" href="//cdn.moot.it/1/moot.css">
<meta name="viewport" content="width=device-width">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
"""

Images and Galleries

To create an image gallery, all you have to do is add a folder inside galleries, and put images there. Nikola will take care of creating thumbnails, index page, etc.

If you click on images on a gallery, or on images with links in post, you will see a bigger image, thanks to the excellent baguetteBox. If don’t want this behavior, add an .islink class to your link. (The behavior is caused by <a class="reference"> if you need to use it outside of galleries and reST thumbnails.)

The gallery pages are generated using the gallery.tmpl template, and you can customize it there (you could switch to another lightbox instead of baguetteBox, change its settings, change the layout, etc.).

Images in galleries may be provided with captions and given a specific ordering, by creating a file in the gallery directory called metadata.yml. This YAML file should contain a name field for each image in the gallery for which you wish to provide either a caption or specific ordering. You can also create localized versions (metadata.xx.yml).

Only one metadata.yml is needed per gallery. Here is an example, showing names, captions and ordering. caption and order are given special treatment, anything else is available to templates, as keys of photo_array images.

---
name: ready-for-the-acid-wash.jpg
---
name: almost-full.jpg
caption: The pool is now almost full
---
name: jumping-in.jpg
caption: We're enjoying the new pool already
order: 4
---
name: waterline-tiles.jpg
order: 2
custom: metadata is supported
---

Images to be used in normal posts can be placed in the images folder. These images will be processed and have thumbnails created just as for galleries, but will then be copied directly to the corresponding path in the output directory, so you can reference it from whatever page you like, most easily using the thumbnail reST extension. If you don't want thumbnails, just use the files folder instead.

The conf.py options affecting images and gallery pages are these:

# One or more folders containing galleries. The format is a dictionary of
# {"source": "relative_destination"}, where galleries are looked for in
# "source/" and the results will be located in
# "OUTPUT_PATH/relative_destination/gallery_name"
# Default is:
GALLERY_FOLDERS = {"galleries": "galleries"}
# More gallery options:
THUMBNAIL_SIZE = 180
MAX_IMAGE_SIZE = 1280
USE_FILENAME_AS_TITLE = True
EXTRA_IMAGE_EXTENSIONS = []

# If set to False, it will sort by filename instead. Defaults to True
GALLERY_SORT_BY_DATE = True

# Folders containing images to be used in normal posts or pages.
# IMAGE_FOLDERS is a dictionary of the form {"source": "destination"},
# where "source" is the folder containing the images to be published, and
# "destination" is the folder under OUTPUT_PATH containing the images copied
# to the site. Thumbnail images will be created there as well.
IMAGE_FOLDERS = {'images': 'images'}

# Images will be scaled down according to IMAGE_THUMBNAIL_SIZE and MAX_IMAGE_SIZE
# options, but will have to be referenced manually to be visible on the site
# (the thumbnail has ``.thumbnail`` added before the file extension by default,
# but a different naming template can be configured with IMAGE_THUMBNAIL_FORMAT).
IMAGE_THUMBNAIL_SIZE = 400
IMAGE_THUMBNAIL_FORMAT = '{name}.thumbnail{ext}'

If you add a reST file in galleries/gallery_name/index.txt its contents will be converted to HTML and inserted above the images in the gallery page. The format is the same as for posts.

If you add some image filenames in galleries/gallery_name/exclude.meta, they will be excluded in the gallery page.

If USE_FILENAME_AS_TITLE is True the filename (parsed as a readable string) is used as the photo caption. If the filename starts with a number, it will be stripped. For example 03_an_amazing_sunrise.jpg will be render as An amazing sunrise.

Here is a demo gallery of historic, public domain Nikola Tesla pictures taken from this site.

.. image:: /images/tesla.jpg

<img src="/images/tesla.jpg">

Handling EXIF Data

Your images contain a certain amount of extra data besides the image itself, called the EXIF metadata. It contains information about the camera you used to take the picture, when it was taken, and maybe even the location where it was taken.

This is both useful, because you can use it in some apps to locate all the pictures taken in a certain place, or with a certain camera, but also, since the pictures Nikola publishes are visible to anyone on the Internet, a privacy risk worth considering (Imagine if you post pictures taken at home with GPS info, you are publishing your home address!)

Nikola has some support for managing it, so let's go through a few scenarios to see which one you prefer.

PRESERVE_EXIF_DATA = False
EXIF_WHITELIST = {}

PRESERVE_EXIF_DATA = True
EXIF_WHITELIST = {'*': '*'}

PRESERVE_EXIF_DATA = True
EXIF_WHITELIST = {
    "0th": ["Orientation", "ImageWidth", "ImageLength"],
    "Interop": "*",
}

Handling ICC Profiles

Your images may contain ICC profiles. These describe the color space in which the images were created or captured.

Most desktop web browsers can use embedded ICC profiles to display images accurately. As of early 2018 few mobile browsers consider ICC profiles when displaying images. A notable exception is Safari on iOS.

By default Nikola strips out ICC profiles when preparing images for your posts and galleries. If you want Nikola to preserve ICC profiles, add this in your conf.py:

PRESERVE_ICC_PROFILES = True

You may wish to do this if, for example, your site contains JPEG images that use a wide-gamut profile such as "Display P3".

Post Processing Filters

You can apply post processing to the files in your site, in order to optimize them or change them in arbitrary ways. For example, you may want to compress all CSS and JS files using yui-compressor.

To do that, you can use the provided helper adding this in your conf.py:

FILTERS = {
  ".css": ["filters.yui_compressor"],
  ".js": ["filters.yui_compressor"],
}

Where "filters.yui_compressor" points to a helper function provided by Nikola in the filters module. You can replace that with strings describing command lines, or arbitrary python functions.

If there's any specific thing you expect to be generally useful as a filter, contact me and I will add it to the filters library so that more people use it.

The currently available filters are:

from nikola.filters import runinplace
def yui_compressor(infile):
    return runinplace(r'yui-compressor --nomunge %1 -o %2', infile)

import string
from nikola.filters import apply_to_text_file
FILTERS = {
  ".html": [apply_to_text_file(string.upper)]
}

filters.html_tidy_nowrap

Prettify HTML 5 documents with tidy5

filters.html_tidy_wrap

Prettify HTML 5 documents wrapped at 80 characters with tidy5

filters.html_tidy_wrap_attr

Prettify HTML 5 documents and wrap lines and attributes with tidy5

filters.html_tidy_mini

Minify HTML 5 into smaller documents with tidy5

filters.html_tidy_withconfig

Run tidy5 with tidy5.conf as the config file (supplied by user)

filters.html5lib_minify

Minify HTML5 using html5lib_minify

filters.html5lib_xmllike

Format using html5lib

filters.typogrify

Improve typography using typogrify

filters.typogrify_sans_widont

Same as typogrify without the widont filter

filters.minify_lines

THIS FILTER HAS BEEN TURNED INTO A NOOP and currently does nothing.

filters.normalize_html

Pass HTML through LXML to normalize it. For example, it will resolve " to actual quotes. Usually not needed.

filters.yui_compressor

Compress CSS/JavaScript using YUI compressor

filters.closure_compiler

Compile, compress, and optimize JavaScript Google Closure Compiler

filters.optipng

Compress PNG files using optipng

filters.jpegoptim

Compress JPEG files using jpegoptim

filters.cssminify

Minify CSS using http://cssminifier.com/ (requires Internet access)

filters.jsminify

Minify JS using http://javascript-minifier.com/ (requires Internet access)

filters.jsonminify

Minify JSON files (strip whitespace and use minimal separators).

filters.xmlminify

Minify XML files. Suitable for Nikola’s sitemaps and Atom feeds.

filters.add_header_permalinks

Add links next to every header, Sphinx-style. You will need to add styling for the headerlink class, in custom.css, for example:

/* Header permalinks */
h1:hover .headerlink, h2:hover .headerlink,
h3:hover .headerlink, h4:hover .headerlink,
h5:hover .headerlink, h6:hover .headerlink {
    display: inline;
}

.headerlink {
    display: none;
    color: #ddd;
    margin-left: 0.2em;
    padding: 0 0.2em;
}

.headerlink:hover {
    opacity: 1;
    background: #ddd;
    color: #000;
    text-decoration: none;
}

Additionally, you can provide a custom list of XPath expressions which should be used for finding headers ({hx} is replaced by headers h1 through h6). This is required if you use a custom theme that does not use "e-content entry-content" as a class for post and page contents.

# Default value:
HEADER_PERMALINKS_XPATH_LIST = ['*//div[@class="e-content entry-content"]//{hx}']
# Include *every* header (not recommended):
# HEADER_PERMALINKS_XPATH_LIST = ['*//{hx}']

filters.deduplicate_ids

Prevent duplicated IDs in HTML output. An incrementing counter is added to offending IDs. If used alongside add_header_permalinks, it will fix those links (it must run after that filter)

IDs are numbered from the bottom up, which is useful for indexes (updates appear at the top). There are exceptions, which may be configured using DEDUPLICATE_IDS_TOP_CLASSES — if any of those classes appears sin the document, the IDs are rewritten top-down, which is useful for posts/pages (updates appear at the bottom).

Note that in rare cases, permalinks might not always be permanent in case of edits.

  DEDUPLICATE_IDS_TOP_CLASSES = ('postpage', 'storypage')

You can also use a file blacklist (``HEADER_PERMALINKS_FILE_BLACKLIST``),
useful for some index pages. Paths include the output directory (eg.
``output/index.html``)

You can apply filters to specific posts or pages by using the filters metadata field:

.. filters: filters.html_tidy_nowrap, "sed s/foo/bar"

Optimizing Your Website

One of the main goals of Nikola is to make your site fast and light. So here are a few tips we have found when setting up Nikola with Apache. If you have more, or different ones, or about other web servers, please share!

1. Use a speed testing tool. I used Yahoo's YSlow but you can use any of them, and it's probably a good idea to use more than one.

2. Enable compression in Apache:

   AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript
   

3. If even after you did the previous step the CSS files are not sent compressed:

   AddType text/css .css
   

4. Optionally you can create static compressed copies and save some CPU on your server with the GZIP_FILES option in Nikola.

5. The bundles Nikola plugin can drastically decrease the number of CSS and JS files your site fetches.

6. Through the filters feature, you can run your files through arbitrary commands, so that images are recompressed, JavaScript is minimized, etc.

7. The USE_CDN option offloads standard JavaScript and CSS files to a CDN so they are not downloaded from your server.

Math

Nikola supports math input via MathJax (by default) or KaTeX. It is activated via the math roles and directives of reStructuredText and the usual LaTeX delimiters for other input formats.

MATHJAX_CONFIG = """
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
    tex2jax: {
        inlineMath: [ ['$','$'], ["\\\(","\\\)"] ],
        displayMath: [ ['$$','$$'], ["\\\[","\\\]"] ],
        processEscapes: true
    },
    displayAlign: 'center', // Change this to 'left' if you want left-aligned equations.
    "HTML-CSS": {
        styles: {'.MathJax_Display': {"margin": 0}}
    }
});
</script>
"""

KATEX_AUTO_RENDER = """
delimiters: [
    {left: "$$", right: "$$", display: true},
    {left: "\\\[", right: "\\\]", display: true},
    {left: "$", right: "$", display: false},
    {left: "\\\(", right: "\\\)", display: false}
]
"""

Euler’s formula: :math:`e^{ix} = \cos x + i\sin x`

Euler’s formula: \(e^{ix} = \cos x + i\sin x\)

.. math::

   \int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C

\[\int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C\]

reStructuredText Extensions

Nikola includes support for a few directives and roles that are not part of docutils, but which we think are handy for website development.

.. media:: http://vimeo.com/72425090

.. media:: http://www.youtube.com/watch?v=wyRpAat5oz0

.. youtube:: 8N_tupPBtWQ

.. youtube:: 8N_tupPBtWQ
   :align: center

.. vimeo:: 20241459

.. vimeo:: 20241459
   :height: 240
   :width: 320

[soundcloud url="http://api.soundcloud.com/tracks/78131362" …/]

.. soundcloud:: 78131362

.. code-block:: python
   :number-lines:

   print("Our virtues and our failings are inseparable")

.. listing:: foo.py python

.. gist:: 2395294

.. thumbnail:: /images/tesla.jpg
   :alt: Nikola Tesla

.. thumbnail:: /images/tesla.jpg
   :alt: Nikola Tesla

   Nikola Tesla, the man that invented the 20th century.

<a class="reference" href="images/tesla.jpg" alt="Nikola Tesla"><img src="images/tesla.thumbnail.jpg"></a>

.. chart:: Bar
   :title: 'Browser usage evolution (in %)'
   :x_labels: ["2002", "2003", "2004", "2005", "2006", "2007"]

   'Firefox', [None, None, 0, 16.6, 25, 31]
   'Chrome',  [None, None, None, None, None, None]
   'IE',      [85.8, 84.6, 84.7, 74.5, 66, 58.6]
   'Others',  [14.2, 15.4, 15.3, 8.9, 9, 10.4]

Take a look at :doc:`my other post <creating-a-theme>` about theme creating.

Take a look at :doc:`creating-a-theme` to know how to do it.

Here are my 5 latest and greatest blog posts:

.. post-list::
   :stop: 5

These are all my posts about Nikola:

.. post-list::
   :tags: nikola

{{% post-list stop=5 %}}{{% /post-list %}}

Importing your WordPress site into Nikola

If you like Nikola, and want to start using it, but you have a WordPress blog, Nikola supports importing it. Here are the steps to do it:

1. Get an XML dump of your site 1

2. nikola import_wordpress mysite.wordpress.2012-12-20.xml

After some time, this will create a new_site folder with all your data. It currently supports the following:

• All your posts and pages

• Keeps “draft” status

• Your tags and categories

• Imports your attachments and fixes links to point to the right places

• Will try to add redirects that send the old post URLs to the new ones

• Will give you a URL map so you know where each old post was

  This is also useful for DISQUS thread migration, or server-based 301 redirects!

• Allows you to export your comments with each post

• Exports information on attachments per post

• There are different methods to transfer the content of your posts:

  • You can convert them to HTML with the WordPress page compiler plugin for Nikola. This will format the posts including supported shortcodes the same way as WordPress does. Use the --transform-to-html option to convert your posts to HTML.

    If you use this option, you do not need to install the plugin permanently. You can ask Nikola to install the plugin into the subdirectory plugins of the current working directory by specifying the --install-wordpress-compiler option.

  • You can leave the posts the way they are and use the WordPress page compiler plugin to render them when building your new blog. This also allows you to create new posts using the WordPress syntax, or to manually add more shortcode plugins later. Use the --use-wordpress-compiler option to not touch your posts.

    If you want to use this option, you have to install the plugin permanently. You can ask Nikola to install the plugin into your new site by specifying the --install-wordpress-compiler option.

  • You can let Nikola convert your posts to Markdown. This is not error free, because WordPress uses some unholy mix of HTML and strange things. This is the default option and requires no plugins.

  You will find your old posts in new_site/posts/post-title.html in the first case, new_site/posts/post-title.wp in the second case or new_site/posts/post-title.md in the last case if you need to edit or fix any of them.

  Please note that the page compiler currently only supports the [code] shortcode, but other shortcodes can be supported via plugins.

  Also note that the WordPress page compiler is licensed under GPL v2 since it uses code from WordPress itself, while Nikola is licensed under the more liberal MIT license.

This feature is a work in progress, and the only way to improve it is to have it used for as many sites as possible and make it work better each time, so we are happy to get requests about it.

1

The dump needs to be in 1.2 format. You can check by reading it, it should say xmlns:excerpt="http://wordpress.org/export/1.2/excerpt/" near the top of the file. If it says 1.1 instead of 1.2 you will have to update your WordPress before dumping.

Other versions may or may not work.

$ nikola import_wordpress mysite.wordpress.2012-12-20.xml -o import_location

Using Twitter Cards