The Nikola Handbook

All You Need to Know

After you have Nikola installed:

Create a 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.

Build the site:

nikola build

Start the test server:

nikola serve

See the site:

http://127.0.0.1:8000

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.

It's 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, slides or whatever fancy CSS/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.

Obsolescense

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 a Python 2.7/3.3 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) pageviews 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.

Features

Nikola has a very defined feature set: it has every feature I needed for my own sites. Hopefully, it will be enough for others, and anyway, I am open to suggestions.

If you want to create a blog or a site, Nikola provides:

• Front page (and older posts pages)
• RSS Feeds
• Pages and feeds for each tag you used
• Custom search
• Full yearly archives
• Custom output paths for generated pages
• Easy page template customization
• Static pages (not part of the blog)
• Internationalization support (my own blog is English/Spanish)
• Google sitemap generation
• Custom deployment (if it's a command, you can use it)
• A (very) basic look and feel you can customize, and is even text-mode friendly
• The input format is light markup (reStructuredText or Markdown)
• Easy-to-create image galleries
• Support for displaying source code
• Image slideshows
• Client-side cloud tags

Also:

• A preview web server
• "Live" re-rendering while you edit
• "Smart" builds: only what changed gets rebuilt (usually in seconds)
• Easy to extend with minimal Python knowledge.

Installing Nikola

This is currently lacking on detail. Considering the niche Nikola is aimed at, I suspect that's not a problem yet. So, when I say "get", the specific details of how to "get" something for your specific operating system are left to you.

The short version is:

pip install nikola

Note that you need Python v2.7 or newer OR v3.3 or newer.

Some features require extra dependencies. You can install them all in bulk by doing:

pip install nikola[extras]

Alternatively, you can install those packages one-by-one, when required (Nikola will tell you what packages are needed)

After that, run nikola init --demo sitename and that will run the setup wizard, which will create a folder called sitename containing a functional demo site.

Nikola is packaged for some Linux distributions, you may get that instead. e.g. If you are running Arch Linux, there are AUR packages, available in Python 2/3 and stable/git master flavors: python-nikola / python2-nikola for the latest stable release or python-nikola-git / python2-nikola-git for the GitHub master. (only one package may be installed at the same time.)

sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev

sudo yum install libxslt-devel libxml2-devel zlib-devel

sudo apt-get install python-dev

sudo yum install python-devel

Getting Started

To create posts and pages in Nikola, you write them in one of the supported input formats. Those source files are later converted to HTML The recommended formats are reStructuredText and Markdown, but there is also support for Textile and WikiCreole and even for just writing HTML. For more details, read Configuring other input formats.

First, let's see how you "build" your site. Nikola comes with a minimal site to get you started.

The tool used to do builds is called doit, and it rebuilds the files that are not up to date, so your site always reflects your latest content. To do our first build, just run "nikola build":

$ nikola build
Scanning posts....done!
.  render_posts:stories/manual.html
.  render_posts:posts/1.html
.  render_posts:stories/1.html
.  render_archive:output/2012/index.html
.  render_archive:output/archive.html
.  render_indexes:output/index.html
.  render_pages:output/posts/welcome-to-nikola.html
.  render_pages:output/stories/about-nikola.html
.  render_pages:output/stories/handbook.html
.  render_rss:output/rss.xml
.  render_sources:output/stories/about-nikola.txt
⋮
⋮
⋮

Nikola will print a line for every output file it generates. If we do it again, that will be much much shorter:

$ nikola build
Scanning posts....done!

That is because doit is smart enough not to generate all the pages again, unless you changed something that the page requires. So, if you change the text of a post, or its title, that post page, and all index pages where it is mentioned, will be recreated. If you change the post page template, then all the post pages will be rebuilt.

Nikola is mostly a series of doit tasks, and you can see them by doing nikola list:

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

You can make Nikola redo everything by calling nikola forget and then nikola build (or nikola build -a, you can make it do just a specific part of the site using task names, for example nikola build render_pages, and even individual files like nikola build output/index.html

Nikola also has other commands besides build:

$ nikola help
Nikola is a tool to create static websites and blogs. For full documentation and more information, please visit http://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
  nikola deploy               deploy the site
  nikola doit_auto            automatically execute tasks when a dependency changes
  nikola dumpdb               dump dependency DB
  nikola forget               clear successful run status from internal DB
  nikola github_deploy        deploy the site to GitHub pages
  nikola help                 show help
  nikola ignore               ignore task (skip) on subsequent runs
  nikola import_wordpress     import a WordPress dump
  nikola init                 create a Nikola site in the specified folder
  nikola install_theme        install theme into current site
  nikola list                 list tasks from dodo file
  nikola new_page             create a new page in the site
  nikola new_post             create a new blog post or site page
  nikola orphans              list all orphans
  nikola plugin               manage plugins
  nikola serve                start the test webserver
  nikola strace               use strace to list file_deps and targets
  nikola tabcompletion        generate script for tab-completion
  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

The serve command starts a web server so you can see the site you are creating:

$ nikola serve -b
Serving HTTP on 127.0.0.1 port 8000 ...

After you do this, a web browser opens at http://127.0.0.1:8000/ and you should see the sample site. This is useful as a "preview" of your work.

By default, the serve command runs the web server on port 8000 on the IP address 127.0.0.1. You can pass in an IP address and port number explicitly using -a IP_ADDRESS (short version of --address) or -p PORT_NUMBER (short version of --port) Example usage:

$ nikola serve --address 0.0.0.0 --port 8080
Serving HTTP on 0.0.0.0 port 8080 ...

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, IPython 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 Configuring other input formats.

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
-----------------

Enter title: How to make money
Your post's text is at:  posts/how-to-make-money.txt

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.

The slug is the page name. Since often titles will have characters that look bad on URLs, it's generated as a "clean" version of the title. The third line is the post's date, and is set to "now".

The other lines are optional. Tags are comma-separated. The link is an original source for the content, and description is mostly useful for SEO. type is the post type, whatever you set here (prepended with post-) will become a CSS class of the <article> element for this post. Defaults to text (resulting in a post-text class)

You can add your own metadata fields in the same manner, if you use a theme that supports them (for example: .. author: John Doe)

To add these metadata fields to all new posts by default, you can set the variable ADDITIONAL_METADATA in your configuration. For example, you can add the author metadata to all new posts by default, by adding the following to your configuration:

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

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

If you are writing a multilingual site, you can also create a per-language post file (for example: how-to-make-money.es.txt with the default TRANSLATIONS_PATTERN, see below). This one can replace metadata of the default language, for example:

• The translated title for the post or page
• A translated version of the page name

The pattern used for finding translations is controlled by the TRANSLATIONS_PATTERN variable in your configuration file.

The default is to put the language code before the file extension, so the German translation of some_file.rst should be named some_file.de.rst. This is because the TRANSLATIONS_PATTERN variable is by default set to:

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

You can edit these files with your favourite text editor, and once you are happy with the contents, generate the pages as explained in Getting Started

Currently supported languages are:

• Basque
• Bulgarian
• Catalan
• Chinese (Simplified)
• Croatian
• Czech
• Dutch
• English
• Esperanto
• Estonian
• Finnish
• French
• German
• Greek
• Hindi
• Italian
• Japanese
• Norwegian Bokmål
• Persian
• Polish
• Portuguese (Brasil)
• Russian
• Slovak
• Slovene
• Spanish
• Turkish
• Urdu

If you wish to add support for more languages, check out the instructions at the theming guide.

The post page is generated using the post.tmpl template, which you can use to customize the output.

The place where the post will be placed by new_post is based on the POSTS and PAGES configuration options:

# POSTS and PAGES contains (wildcard, destination, template) tuples.
#
# The wildcard is used to generate a list of reSt source files
# (whatever/thing.txt).
#
# That fragment could have an associated metadata file (whatever/thing.meta),
# and optionally translated files (example for Spanish, with code "es"):
#     whatever/thing.es.txt 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 difference between POSTS and PAGES is that POSTS are added
# to feeds and are considered part of a blog, while PAGES are
# just independent HTML pages.
#

POSTS = (
    ("posts/*.txt", "posts", "post.tmpl"),
    ("posts/*.rst", "posts", "post.tmpl"),
)
PAGES = (
    ("stories/*.txt", "stories", "story.tmpl"),
    ("stories/*.rst", "stories", "story.tmpl"),
)

new_post will use the first path in POSTS (or PAGES if -p is supplied) that ends with the extension of your desired markup format (as defined in COMPILERS in conf.py) as the directory that the new post will be written into. If no such entry can be found, the post won’t be created.

The new_post command supports some options:

$ 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.
  -t ARG, --title=ARG       Title for the page/post.
  --tags=ARG                Comma-separated tags for the page/post.
  -1                        Create post with embedded metadata (single file format)
  -2                        Create post with separate metadata (two file format)
  -f ARG, --format=ARG      Markup format for post, one of rest, markdown, wiki, bbcode, html, textile, txt2tags

The optional path parameter tells nikola exactly where to put it instead of guessing from your config. So, if you do nikola new_post posts/random/foo.txt you will have a post in that path, with "foo" as its slug.

.. TEASER_END

<!-- TEASER_END -->

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

# 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>'

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.
.
.
.

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 story.tmpl template instead of post.tmpl by default

The default configuration expects the page's metadata and text files to be on the stories 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.

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 = "http://getnikola.com/"
BLOG_EMAIL = "[email protected]"
BLOG_DESCRIPTION = "This is a demo site for Nikola."  # (translatable)

Some options are demarked 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

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

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

Note

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

Note

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 hilighted when active.

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 Python’s strftime() 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) just put it in files/. Everything there is copied into output by the copy_files task. 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'

Getting More 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 install_theme command:

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

$ nikola install_theme blogtxt
[2013-10-12T16:46:13Z] NOTICE: install_theme: Downloading:
http://themes.getnikola.com/v6/blogtxt.zip
[2013-10-12T16:46:15Z] NOTICE: install_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 bootswatch_theme option to create a custom theme by downloading free CSS files from http://bootswatch.com:

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

You can even try what different swatches do on an existing site using their handy bootswatchlet

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

Deployment

Nikola doesn't really have a concept of deployment. However, 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/ [email protected]:/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 and Annotations

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
• Moot
• Google+
• Facebook
• isso

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

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">
"""

An alternative or complement to comments are annotations. Nikola integrates the annotation service provided by AnnotateIt. To use it, set the ANNOTATIONS option to True. This is specially useful if you want feedback on specific parts of your writing.

You can enable or disable annotations for specific posts or pages using the annotations and noannotations metadata.

Annotations require JQuery and are therefore not supported in the base theme. You can check bootstrap theme's base.html for details on how to handle them in custom themes.

Image 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, you should see a bigger image, thanks to the excellent colorbox

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

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"}
# One or more folders containing images. The format is again a dictionary of
# {"source": "relative_destination"}. Images will be scaled down if necessary so
# that neither width nor height is greater than MAX_IMAGE_SIZE and copied to
# destination folder. A thumbnail will also be created in the same folder with
# ``.thumbnail`` inserted in the file name before the file extension
# (e.g. ``tesla.thumbnail.jpg``).
IMAGE_FOLDERS = {'images': ''}
# More image/gallery options:
THUMBNAIL_SIZE = 180
IMAGE_THUMBNAIL_SIZE = 400
MAX_IMAGE_SIZE = 1280
USE_FILENAME_AS_TITLE = True
EXTRA_IMAGE_EXTENSIONS = []

If you add a 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.

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:

from nikola import filters

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

Where filters.yui_compressor is a helper function provided by Nikola. 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:

def yui_compressor(infile):
    return runinplace(r'yui-compressor --nomunge %1 -o %2', infile)

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

minify_lines

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

yui_compressor

Compress CSS/JavaScript using YUI compressor

closure_compiler

Compile, compress, and optimize JavaScript Google Closure Compiler

optipng

Compress PNG files using optipng

jpegoptim

Compress JPEG files using jpegoptim

typogrify

Improve typography using typogrify

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 webassets 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.

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.

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

.. math::

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

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

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

.. youtube:: 8N_tupPBtWQ

.. 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:: ../tesla.jpg

.. thumbnail:: ../tesla.jpg

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

.. slides::

   /galleries/demo/tesla_conducts_lg.jpg
   /galleries/demo/tesla_lightning2_lg.jpg
   /galleries/demo/tesla4_lg.jpg
   /galleries/demo/tesla_lightning1_lg.jpg
   /galleries/demo/tesla_tower1_lg.jpg

.. 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

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's the steps to do it:

1. Get a 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!

• Will try to convert the content of your posts. This is not error free, because WordPress uses some unholy mix of HTML and strange things. Currently we are treating it as markdown, which does a reasonable job of it.

  You will find your old posts in new_site/posts/post-title.wp in case you need to fix any of them.

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 I am happy to get requests about it.

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

Using Twitter Cards

Nikola supports Twitter Card summaries, but they are disabled by default.

Twitter Cards enable you to show additional information in Tweets that link to you content. Nikola supports Twitter Cards. They are implemented to use Open Graph tags whenever possible.

Images displayed come from the previewimage meta tag.

You can specify the card type by using the card parameter in TWITTER_CARD.

To enable and configure your use of Twitter Cards, please modify the corresponding lines in your conf.py:

TWITTER_CARD = {
    'use_twitter_cards': True,  # enable Twitter Cards
    'card': 'summary',          # Card type, you can also use 'summary_large_image',
                                # see https://dev.twitter.com/cards/types
    'site': '@website',         # twitter nick for the website
    'creator': '@username',     # Username for the content creator / author.
}

Custom Plugins

You can create your own plugins (see Extending Nikola) and use them in your own site by putting them in a plugins/ folder. You can also put them in directories listed in the EXTRA_PLUGINS_DIRS configuration variable.

Getting Extra Plugins

If you want extra plugins, there is also the Plugins Index.

Similarly to themes, there is a nice, built-in command to manage them — plugin:

$ nikola plugin -l
Plugins:
--------
helloworld
tags
⋮
⋮

$ nikola plugin --install helloworld
[2013-10-12T16:51:56Z] NOTICE: install_plugin: Downloading: http://plugins.getnikola.com/v6/helloworld.zip
[2013-10-12T16:51:58Z] NOTICE: install_plugin: Extracting: helloworld into plugins
plugins/helloworld/requirements.txt
[2013-10-12T16:51:58Z] NOTICE: install_plugin: This plugin has Python dependencies.
[2013-10-12T16:51:58Z] NOTICE: install_plugin: Installing dependencies with pip...
⋮
⋮
[2013-10-12T16:51:59Z] NOTICE: install_plugin: Dependency installation succeeded.
[2013-10-12T16:51:59Z] NOTICE: install_plugin: This plugin has a sample config file.
Contents of the conf.py.sample file:

    # Should the Hello World plugin say “BYE” instead?
    BYE_WORLD = False

Then you also can uninstall your plugins:

$ nikola plugin --uninstall tags
[2014-04-15T08:59:24Z] WARNING: plugin: About to uninstall plugin: tags
[2014-04-15T08:59:24Z] WARNING: plugin: This will delete /home/ralsina/foo/plugins/tags
Are you sure? [y/n] y
[2014-04-15T08:59:26Z] WARNING: plugin: Removing /home/ralsina/foo/plugins/tags

And upgrade them:

$ nikola plugin --upgrade
[2014-04-15T09:00:18Z] WARNING: plugin: This is not very smart, it just reinstalls some plugins and hopes for the best
Will upgrade 1 plugins: graphviz
Upgrading graphviz
[2014-04-15T09:00:20Z] INFO: plugin: Downloading: http://plugins.getnikola.com/v7/graphviz.zip
[2014-04-15T09:00:20Z] INFO: plugin: Extracting: graphviz into /home/ralsina/.nikola/plugins/
[2014-04-15T09:00:20Z] NOTICE: plugin: This plugin has third-party dependencies you need to install manually.
Contents of the requirements-nonpy.txt file:

    Graphviz
        http://www.graphviz.org/

You have to install those yourself or through a package manager.

You can also share plugins you created with the community! Visit the GitHub repository to find out more.

You can use the plugins in this repository without installing them into your site, by cloning the repository and adding the path of the plugins directory to the EXTRA_PLUGINS_DIRS list in your configuration.

Advanced Features

$ nikola tabcompletion --shell bash --hardcode-tasks > _nikola_bash
$ nikola tabcompletion --shell zsh --hardcode-tasks > _nikola_zsh

License

Nikola is released under a MIT license which is a free software license. Some components shipped along with Nikola, or required by it are released under other licenses.

If you are not familiar with free software licensing: In general, you should be able to do pretty much anything you want, unless you modify Nikola. If you modify it, and share it with someone else, that someone else should get all your modifications under the same license you got it.