Themes are located in the
themes folder where Nikola is installed, and in the
of your site, one folder per theme. The folder name is the theme name.
A Nikola theme consists of the following folders (they are all optional):
output/assetswhen you build the site, and the templates will contain references to them. The default subdirectories are
The included themes use Bootstrap, baguetteBox, Justified Layout by Flickr and Luxon, so they are in assets, along with CSS files for syntax highlighting, reStructuredText and Jupyter, as well as a minified copy of jQuery.
If you want to base your theme on other frameworks (or on no framework at all) just remember to put there everything you need for deployment. (Not all of the listed assets are used by
This contains the templates used to generate the pages. While Nikola will use a certain set of template names by default, you can add others for specific parts of your site.
Nikola tries to be multilingual. This is where you put the strings for your theme so that it can be translated into other languages.
- less, sass
Files to be compiled into CSS using LESS and Sass (both require plugins)
This mandatory file:
An INI file containing theme meta data. The file format is described in detail below, in the Theme meta files section.
And these optional files:
- parent, engine
One-line text files that contain the names of parent and engine themes, respectively. Those are needed for older versions (Nikola v7.8.5 and older).
A config file containing a list of files to be turned into bundles. For example:
assets/css/all.css= bootstrap.min.css, rst_base.css, nikola_rst.css, code.css, baguetteBox.min.css, theme.css, custom.css,
This creates a file called "assets/css/all.css" in your output that is the combination of all the other file paths, relative to the output file. This makes the page much more efficient because it avoids multiple connections to the server, at the cost of some extra difficult debugging.
Bundling applies to CSS and JS files.
Templates should use either the bundle or the individual files based on the
use_bundlesvariable, which in turn is set by the
As of Nikola v7.8.6, Nikola uses meta files for themes. Those are INI files,
with the same name as your theme, and a
.theme extension, eg.
bootstrap3.theme. Here is an example, from the bootstrap3 theme:
[Theme] engine = mako parent = base author = The Nikola Contributors author_url = https://getnikola.com/ based_on = Bootstrap 3 <https://getbootstrap.com/> license = MIT tags = bootstrap [Family] family = bootstrap3 jinja_version = bootstrap3-jinja variants = bootstrap3-gradients, bootstrap3-gradients-jinja [Nikola] bootswatch = True
The following keys are currently supported:
Theme— contains information about the theme.
engine— engine used by the theme. Should be
parent— the parent theme. Any resources missing in this theme, will be looked up in the parent theme (and then in the grandparent, etc).
The parent is so you don’t have to create a full theme each time: just create an empty theme, set the parent, and add the bits you want modified. You must define a parent, otherwise many features won’t work due to missing templates, messages, and assets.
The following settings are recommended:
If your theme uses Bootstrap 3, inherit the
If your theme uses Jinja as a template engine, inherit
In any other case, inherit
author_url— used to identify theme author.
based_on— optional list of inspirations, frameworks, etc. used in the theme. Should be comma-separated, the format
Name <URL>is recommended.
license— theme license. Pick MIT if you have no preference.
tags— optional list of tags (comma-separated) to describe the theme.
Family— contains information about other related themes. All values optional. (Do not use unless you have related themes.)
family— the name of the main theme in a family, which is also used as the family name.
jinja_version— name of the mako/jinja version of the theme.
variants— comma-separated list of stylistic variants (other than the mako/jinja version listed above)
Nikola— Nikola-specific information, currently optional.
bootswatch— whether or not theme supports Bootswatch styling (optional, defaults to False)
ignored_assets— comma-separated list of assets to ignore (relative to the
In templates there is a number of files whose name ends in
.tmpl. Those are the
theme’s page templates. They are done using the Mako
or Jinja2 template languages. If you want to do a theme, you
should learn one first. What engine is used by the theme is declared in the
If you are using Mako templates, and want some extra speed when building the site you can install Beaker and make templates be cached
Both template engines have a nifty concept of template inheritance. That means that a
template can inherit from another and only change small bits of the output. For example,
base.tmpl defines the whole layout for a page but has only a placeholder for content
post.tmpl only define the content, and the layout is inherited from
Another concept is theme inheritance. You do not need to duplicate all the default templates in your theme — you can just override the ones you want changed, and the rest will come from the parent theme. (Every theme needs a parent.)
Apart from the built-in templates listed below, you can add other templates for specific
pages, which the user can then use in his
PAGES option in
conf.py. Also, you can specify a custom template to be used by a post or
page via the
template metadata, and custom templates can be added in the
templates/ folder of your site.
If you want to modify (override) a built-in template, use
nikola theme -c
<name>.tmpl. This command will copy the specified template file to the
templates/ directory of your currently used theme.
Keep in mind that your theme is yours, so you can require whatever data you
want (eg. you may depend on specific custom
GLOBAL_CONTEXT variables, or
post meta attributes). You don’t need to keep the same theme structure as the
default themes do (although many of those names are hardcoded). Inheriting from
base-jinja) is heavily recommended, but not strictly
required (unless you want to share it on the Themes Index).
These are the templates that come with the included themes:
This template defines the basic page layout for the site. It’s mostly plain HTML but defines a few blocks that can be re-defined by inheriting templates.
It has some separate pieces defined in
base_footer.tmplso they can be easily overridden.
Template used to render the multipost indexes. The posts are in a
postsvariable. Some functionality is in the
Code that implements archive navigation (previous/up/next). Included by archive templates.
Used to display archives, if
ARCHIVES_ARE_INDEXESis True. By default, it just inherits
index.tmpl, with added archive navigation and feeds.
Used to display author pages.
Used to display author indexes, if
AUTHOR_PAGES_ARE_INDEXESis True. By default, it just inherits
index.tmpl, with added feeds.
This template handles comments. You should probably never touch it :-) It uses a bunch of helper templates, one for each supported comment system (all of which start with
These templates help render specific UI items, and can be tweaked as needed.
Template used for image galleries. Interesting data includes:
post: A post object, containing descriptive
post.text()for the gallery.
crumbs: A list of
link, crumbto implement breadcrumbs.
folders: A list of folders to implement hierarchical gallery navigation.
enable_comments: To enable/disable comments in galleries.
photo_array: a list of dictionaries, each containing:
url: URL for the full-sized image.
url_thumb: URL for the thumbnail.
title: The title of the image.
size: A dict containing
h, the real size of the thumbnail.
photo_array_json: a JSON dump of photo_array, used by the
Template used to display generic lists of links, which it gets in
items, a list of (text, link, count) elements.
Template used to display generic lists of posts, which it gets in
Used to display code listings.
Used to add MathJax/KaTeX code to pages.
Template used by default for blog posts, gets the data in a
postobject which is an instance of the Post class. Some functionality is in the
Template used by the
Used to display section indexes, if
POST_SECTIONS_ARE_INDEXESis True. By default, it just inherits
index.tmpl, with added feeds.
Used for pages that are not part of a blog, usually a cleaner, less intrusive layout than
post.tmpl, but same parameters.
Used to show the contents of a single tag or category.
Used to show the contents of a single tag or category, if
TAG_PAGES_ARE_INDEXESis True. By default, it just inherits
index.tmpl, with added feeds and some extra features.
Used to display the list of tags and categories.
The full, complete list of variables available in templates is maintained in a separate document: Template variables
The user’s preference for theme color is exposed in templates as
theme_color set in the
Each section has an assigned color that is either set by the user or auto
selected by adjusting the hue of the user’s
THEME_COLOR. The color is
exposed in templates through
post.section_color(lang). The function that
generates the colors from strings and any given color (by section name and
theme color for sections) is exposed through the
colorize_str_from_base_color(string, hex_color) function
Hex color values, like that returned by the theme or section color can be
altered in the HSL colorspace through the function
color_hsl_adjust_hex(hex_string, adjust_h, adjust_s, adjust_l).
Adjustments are given in values between 1.0 and -1.0. For example, the theme
color can be made lighter using this code:
The included themes are translated into a variety of languages. You can add your own translation at https://www.transifex.com/projects/p/nikola/
If you want to create a theme that has new strings, and you want those strings to be translatable,
then your theme will need a custom
The LESS and Sass compilers were moved to the Plugins Index in Nikola v7.0.0.
If you want to use those CSS extensions, you can — just store your files
sass directory of your theme.
In order to have them work, you need to create a list of
.scss/.sass files to compile — the list should be in a file named
targets in the respective directory (
The files listed in the
targets file will be passed to the respective
compiler, which you have to install manually (
lessc which comes from
the Node.js package named
sass from a Ruby package aptly
sass). Whatever the compiler outputs will be saved as a CSS
file in your rendered site, with the
Conflicts may occur if you have two files with the same base name but a different extension. Pay attention to how you name your files or your site won’t build! (Nikola will tell you what’s wrong when this happens)