nikola package



nikola.filters module

Utility functions to help run filters on files.

All filters defined in this module are registered in Nikola.__init__.

Post-process HTML via lxml to add header permalinks Sphinx-style.


Apply a filter to a binary file.

Take a function f that transforms a data argument, and returns a function that takes a filename and applies f to the contents, in place. Reads files in binary mode.


Apply a filter to a text file.

Take a function f that transforms a data argument, and returns a function that takes a filename and applies f to the contents, in place. Reads files in UTF-8.

nikola.filters.closure_compiler(infile, executable='closure-compiler')

Run closure-compiler on a file.


Minify CSS using

nikola.filters.deduplicate_ids(data, top_classes=None)

Post-process HTML via lxml to deduplicate IDs.


Minify with html5lib.


Transform document to an XML-like form with html5lib.

nikola.filters.html_tidy_mini(infile, executable='tidy5')

Run HTML tidy with minimal settings.

nikola.filters.html_tidy_nowrap(infile, executable='tidy5')

Run HTML Tidy without line wrapping.

nikola.filters.html_tidy_withconfig(infile, executable='tidy5')

Run HTML Tidy with tidy5.conf as config file.

nikola.filters.html_tidy_wrap(infile, executable='tidy5')

Run HTML Tidy with line wrapping.

nikola.filters.html_tidy_wrap_attr(infile, executable='tidy5')

Run HTML tidy with line wrapping and attribute indentation.

nikola.filters.jpegoptim(infile, executable='jpegoptim')

Run jpegoptim on a file.

nikola.filters.jpegoptim_progressive(infile, executable='jpegoptim')

Run jpegoptim on a file and convert to progressive.


Minify JS using


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

nikola.filters.list_replace(the_list, find, replacement)

Replace all occurrences of find with replacement in the_list.


Do nothing – deprecated filter.


Pass HTML through LXML to clean it up, if possible.

nikola.filters.optipng(infile, executable='optipng')

Run optipng on a file.


Insert PHP code into Nikola templates.

nikola.filters.runinplace(command, infile)

Run a command in-place on a file.

command is a string of the form: “commandname %1 %2” and it will be execed with infile as %1 and a temporary file as %2. Then, that temporary file will be moved over %1.

Example usage:

runinplace(“yui-compressor %1 -o %2”, “myfile.css”)

That will replace myfile.css with a minified version.

You can also supply command as a list.


Prettify text with typogrify.


Prettify text with typogrify.


Prettify text with typogrify, skipping the widont filter.


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

nikola.filters.yui_compressor(infile, executable=None)

Run YUI Compressor on a file.

nikola.image_processing module

Process images.

class nikola.image_processing.ImageProcessor

Bases: :class:`object`

Apply image operations.

filter_exif(exif, whitelist)

Filter EXIF data as described in the documentation.


Try to figure out the date of the image.

image_ext_list_builtin = ['.jpg', '.png', '.jpeg', '.gif', '.svg', '.svgz', '.bmp', '.tiff']
resize_image(src, dst, max_size, bigger_panoramas=True, preserve_exif_data=False, exif_whitelist={}, preserve_icc_profiles=False)

Make a copy of the image in the requested size.

resize_svg(src, dst, max_size, bigger_panoramas)

Make a copy of an svg at the requested size.

nikola.nikola module

The main Nikola site object.

class nikola.nikola.Nikola(**config)

Bases: :class:`object`

Class that handles site generation.

Takes a site config as argument on creation.


Initialize some parts of GLOBAL_CONTEXT only when it’s queried.


Get an absolute link.

apply_shortcodes(data, filename=None, lang=None, extra_context=None)

Apply shortcodes from the registry on data.

apply_shortcodes_uuid(data, _shortcodes, filename=None, lang=None, extra_context=None)

Apply shortcodes from the registry on data.

atom_feed_renderer(lang, posts, output_path, filters, extra_context)

Render Atom feeds and archives with lists of posts.

Feeds are considered archives when no future updates to them are expected.


Translate a category path to a category name.


Normalize target paths in the task.

file_exists(path, not_empty=False)

Check if the file exists. If not_empty is True, it also must not be empty.

filename_path(name, lang)

Link to post or page by source filename.


link://filename/manual.txt => /docs/handbook.html

gen_tasks(name, plugin_category, doc='')

Generate tasks.

generic_index_renderer(lang, posts, indexes_title, template_name, context_source, kw, basename, page_link, page_path, additional_dependencies=[])

Create an index page.

lang: The language posts: A list of posts indexes_title: Title template_name: Name of template file context_source: This will be copied and extended and used as every

page’s context

kw: An extended version will be used for uptodate dependencies basename: Basename for task page_link: A function accepting an index i, the displayed page number,

the number of pages, and a boolean force_addition which creates a link to the i-th page (where i ranges between 0 and num_pages-1). The displayed page (between 1 and num_pages) is the number (optionally) displayed as ‘page %d’ on the rendered page. If force_addition is True, the appendum (inserting ‘-%d’ etc.) should be done also for i == 0.
page_path: A function accepting an index i, the displayed page number,
the number of pages, and a boolean force_addition, which creates a path to the i-th page. All arguments are as the ones for page_link.
additional_dependencies: a list of dependencies which will be added
to task[‘uptodate’]
generic_page_renderer(lang, post, filters, context=None)

Render post fragments to final HTML pages.

generic_post_list_renderer(lang, posts, output_name, template_name, filters, extra_context)

Render pages with lists of posts.

generic_renderer(lang, output_name, template_name, filters, file_deps=None, uptodate_deps=None, context=None, context_deps_remove=None, post_deps_dict=None, url_type=None, is_fragment=False)

Create tasks for rendering pages and post lists and other related pages.

lang is the current language. output_name is the destination file name. template_name is the template to be used. filters is the list of filters (usually site.config[‘FILTERS’]) which will be used to post-process the result. file_deps (optional) is a list of additional file dependencies (next to template and its dependencies). uptodate_deps (optional) is a list of additional entries added to the task’s uptodate list. context (optional) a dict used as a basis for the template context. The lang parameter will always be added. context_deps_remove (optional) is a list of keys to remove from the context after using it as an uptodate dependency. This should name all keys containing non-trivial Python objects; they can be replaced by adding JSON-style dicts in post_deps_dict. post_deps_dict (optional) is a dict merged into the copy of context which is used as an uptodate dependency. url_type (optional) allows to override the URL_TYPE configuration. is_fragment (optional) allows to write a HTML fragment instead of a HTML document.

generic_rss_feed(lang, title, link, description, timeline, rss_teasers, rss_plain, feed_length=10, feed_url=None, enclosure=<function _enclosure>, rss_links_append_query=None, copyright_=None)

Generate an ExtendedRSS2 feed object for later use.

generic_rss_renderer(lang, title, link, description, timeline, output_path, rss_teasers, rss_plain, feed_length=10, feed_url=None, enclosure=<function _enclosure>, rss_links_append_query=None, copyright_=None)

Take all necessary data, and render a RSS feed in output_path.


Get the correct compiler for a post from conf.COMPILERS.

To make things easier for users, the mapping in is compiler->[extensions], although this is less convenient for us. The majority of this function is reversing that dictionary and error checking.

init_plugins(commands_only=False, load_all=False)

Load plugins as needed.

Create a link.


Parse a category name into a hierarchy.

path(kind, name, lang=None, is_link=False, **kwargs)

Build the path to a certain kind of page.

These are mostly defined by plugins by registering via the register_path_handler method, except for slug, post_path, root and filename which are defined in this class’ init method.

Here’s some of the others, for historical reasons:

  • root (name is ignored)
  • tag_index (name is ignored)
  • tag (and name is the tag name)
  • tag_rss (name is the tag name)
  • category (and name is the category name)
  • category_rss (and name is the category name)
  • archive (and name is the year, or None for the main archive index)
  • index (name is the number in index-number)
  • rss (name is ignored)
  • gallery (name is the gallery name)
  • listing (name is the source code file name)
  • post_path (name is 1st element in a POSTS/PAGES tuple)
  • slug (name is the slug of a post or page)
  • filename (name is the source filename of a post/page, in DEFAULT_LANG, relative to

The returned value is either a path relative to output, like “categories/whatever.html”, or an absolute URL (“”), if path handler returns a string.

If is_link is True, the path is absolute and uses “/” as separator (ex: “/archive/index.html”). If is_link is False, the path is relative to output and uses the platform’s separator. (ex: “archiveindex.html”) If the registered path handler returns a string instead of path component list - it’s considered to be an absolute URL and returned as is.

post_path(name, lang)

Link to the destination of an element in the POSTS/PAGES settings.


link://post_path/posts => /blog

register_filter(filter_name, filter_definition)

Register a filter.

filter_name should be a name not confusable with an actual executable. filter_definition should be a callable accepting one argument (the filename).

register_path_handler(kind, f)

Register a path handler.

register_shortcode(name, f)

Register function f to handle shortcode “name”.

Get a relative link.

render_template(template_name, output_name, context, url_type=None, is_fragment=False)

Render a template with the global context.

If output_name is None, will return a string and all URL normalization will be ignored (including the link:// scheme). If output_name is a string, URLs will be normalized and the resultant HTML will be saved to the named file (path must start with OUTPUT_FOLDER).

The argument url_type allows to override the URL_TYPE configuration.

If is_fragment is set to True, a HTML fragment will be rendered and not a whole HTML document.

Replace links in document to point to the right places.

root_path(name, lang)

Link to the current language’s root.


link://root_path => /

link://root_path => /translations/spanish/

scan_posts(really=False, ignore_quit=False, quiet=False)

Scan all the posts.

The quiet option is ignored.

slug_path(name, lang)

Return a link to a post with given slug, if not ambiguous.


link://slug/yellow-camaro => /posts/cars/awful/yellow-camaro/index.html

static sort_posts_chronologically(posts, lang=None)

Sort a list of posts chronologically.

This function also takes priority, title and source path into account.

url_replacer(src, dst, lang=None, url_type=None)

Mangle URLs.

  • Replaces link:// URLs with real links
  • Makes dst relative to src
  • Leaves fragments unchanged
  • Leaves full URLs unchanged
  • Avoids empty links

src is the URL where this link is used dst is the link to be mangled lang is used for language-sensitive URLs in link:// url_type is used to determine final link appearance, defaulting to URL_TYPE from config

nikola.plugin_categories module

Nikola plugin categories.

class nikola.plugin_categories.Command(*args, **kwargs)

Bases: :class:`nikola.plugin_categories.BasePlugin`, :class:`doit.cmd_base.Command`

Doit command implementation.

cmd_options = ()
doc_description = None
doc_purpose = 'A short explanation.'
doc_usage = ''
execute(options=None, args=None) → int

Check if the command can run in the current environment, fail if needed, or call _execute.

name = 'dummy_command'
needs_config = True
class nikola.plugin_categories.LateTask

Bases: :class:`nikola.plugin_categories.BaseTask`

Late task generator (plugin executed after all Task plugins).

name = 'dummy_latetask'
class nikola.plugin_categories.PageCompiler

Bases: :class:`nikola.plugin_categories.BasePlugin`

Compile text files into HTML.

compile(source: str, dest: str, is_two_file=True, post=None, lang=None)

Compile the source file into HTML and save as dest.

compile_string(data: str, source_path=None, is_two_file=True, post=None, lang=None) → str

Compile the source file into HTML strings (with shortcode support).

Returns a tuple of at least two elements: HTML string [0] and shortcode dependencies [last].

config_dependencies = []
create_post(path: str, content=None, onefile=False, is_page=False, **kw)

Create post file with optional metadata.

default_metadata = {'slug': '', 'type': 'text', 'description': '', 'link': '', 'tags': '', 'date': '', 'title': '', 'category': ''}
demote_headers = False
extension() → str

Return the preferred extension for the output of this compiler.

friendly_name = ''
get_compiler_extensions() → list

Activate all the compiler extension plugins for a given compiler and return them.


Return the .dep file’s name for the given post and language.


Return a list of extra targets for the render_posts task when compiling the post for the specified language.

metadata_conditions = []
name = 'dummy_compiler'

Read the metadata from a post, and return a metadata dict.


Add dependency to post object to check .dep file.

split_metadata(data: str, post=None, lang=None) -> (<class 'str'>, <class 'str'>)

Split data from metadata in the raw post content.

supports_metadata = False
supports_onefile = True
use_dep_file = True
class nikola.plugin_categories.RestExtension

Bases: :class:`nikola.plugin_categories.CompilerExtension`

Extensions for reStructuredText.

compiler_name = 'rest'
name = 'dummy_rest_extension'
class nikola.plugin_categories.MarkdownExtension

Bases: :class:`nikola.plugin_categories.CompilerExtension`

Extensions for Markdown.

compiler_name = 'markdown'
name = 'dummy_markdown_extension'
class nikola.plugin_categories.MetadataExtractor

Bases: :class:`nikola.plugin_categories.BasePlugin`

Plugins that can extract meta information from post files.


Check if requirements for an extractor are satisfied.

conditions = []
extract_filename(filename: str, lang: str) → typing.Dict[str, str]

Extract metadata from filename.

extract_text(source_text: str) → typing.Dict[str, str]

Split file, return metadata and the content.

map_from = None
name = 'unknown'
priority = None
requirements = []
source = None
split_metadata_from_text(source_text: str) -> (<class 'str'>, <class 'str'>)

Split text into metadata and content (both strings).

split_metadata_re = None
supports_write = False
write_metadata(metadata: typing.Dict[str, str], comment_wrap=False) → str

Write metadata in this extractor’s format.

comment_wrap is either True, False, or a 2-tuple of comments to use for wrapping, if necessary. If it’s set to True, defaulting to ('<!--', '-->') is recommended.

This function should insert comment markers (if applicable) and must insert trailing newlines.

class nikola.plugin_categories.Task

Bases: :class:`nikola.plugin_categories.BaseTask`

Task generator.

name = 'dummy_task'
class nikola.plugin_categories.TaskMultiplier

Bases: :class:`nikola.plugin_categories.BasePlugin`

Take a task and return more tasks.

name = 'dummy multiplier'
process(task) → list

Examine task and create more tasks. Returns extra tasks only.

class nikola.plugin_categories.TemplateSystem

Bases: :class:`nikola.plugin_categories.BasePlugin`

Provide support for templating systems.

get_deps(filename: str)

Return paths to dependencies for the template loaded from filename.

get_string_deps(text: str)

Find dependencies for a template string.

get_template_path(template_name: str) → str

Get the path to a template or return None.

inject_directory(directory: str)

Inject the directory with the lowest priority in the template search mechanism.

name = 'dummy_templates'
render_template(template_name: str, output_name: str, context: typing.Dict[str, str])

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

render_template_to_string(template: str, context: typing.Dict[str, str]) → str

Render template to a string using context.

set_directories(directories: typing.List[str], cache_folder: str)

Set the list of folders where templates are located and cache.

template_deps(template_name: str)

Return filenames which are dependencies for a template.

class nikola.plugin_categories.SignalHandler

Bases: :class:`nikola.plugin_categories.BasePlugin`

Signal handlers.

name = 'dummy_signal_handler'
class nikola.plugin_categories.ConfigPlugin

Bases: :class:`nikola.plugin_categories.BasePlugin`

A plugin that can edit config (or modify the site) on-the-fly.

name = 'dummy_config_plugin'
class nikola.plugin_categories.PostScanner

Bases: :class:`nikola.plugin_categories.BasePlugin`

The scan method of these plugins is called by Nikola.scan_posts.


Create a list of posts from some source. Returns a list of Post objects.

supported_extensions() → typing.Union[typing.List, NoneType]

Return a list of supported file extensions, or None if such a list isn’t known beforehand.

class nikola.plugin_categories.Taxonomy

Bases: :class:`nikola.plugin_categories.BasePlugin`

Taxonomy for posts.

A taxonomy plugin allows to classify posts (see #2107) by classification strings. Classification plugins must adjust a set of options to determine certain aspects.

The following options are class attributes with their default values. These variables should be set in the class definition, in the constructor or latest in the set_site function.

classification_name = “taxonomy”:
The classification name to be used for path handlers. Must be overridden!
overview_page_items_variable_name = “items”:

When rendering the overview page, its template will have a list of pairs

(friendly_name, link)

for the classifications available in a variable by this name.

The template will also have a list
(friendly_name, link, post_count)

for the classifications available in a variable by the name overview_page_items_variable_name + ‘_with_postcount’.

overview_page_variable_name = “taxonomy”:
When rendering the overview page, its template will have a list of classifications available in a variable by this name.
overview_page_hierarchy_variable_name = “taxonomy_hierarchy”:

When rendering the overview page, its template will have a list of tuples

(friendly_name, classification, classification_path, link,
indent_levels, indent_change_before, indent_change_after)

available in a variable by this name. These tuples can be used to render the hierarchy as a tree.

The template will also have a list
(friendly_name, classification, classification_path, link,
indent_levels, indent_change_before, indent_change_after, number_of_children, post_count)

available in the variable by the name overview_page_hierarchy_variable_name + ‘_with_postcount’.

more_than_one_classifications_per_post = False:
If True, there can be more than one classification per post; in that case, the classification data in the metadata is stored as a list. If False, the classification data in the metadata is stored as a string, or None when no classification is given.
has_hierarchy = False:
Whether the classification has a hierarchy.
include_posts_from_subhierarchies = False:
If True, the post list for a classification includes all posts with a sub-classification (in case has_hierarchy is True).
include_posts_into_hierarchy_root = False:
If True, include_posts_from_subhierarchies == True will also insert posts into the post list for the empty hierarchy [].
show_list_as_subcategories_list = False:
If True, for every classification which has at least one subclassification, create a list of subcategories instead of a list/index of posts. This is only used when has_hierarchy = True. The template specified in subcategories_list_template will be used. If this is set to True, it is recommended to set include_posts_from_subhierarchies to True to get correct post counts.
show_list_as_index = False:
Whether to show the posts for one classification as an index or as a post list.
subcategories_list_template = “taxonomy_list.tmpl”:
The template to use for the subcategories list when show_list_as_subcategories_list is True.
generate_atom_feeds_for_post_lists = False:
Whether to generate Atom feeds for post lists in case GENERATE_ATOM is set.
template_for_single_list = “tagindex.tmpl”:
The template to use for the post list for one classification.
template_for_classification_overview = “list.tmpl”:
The template to use for the classification overview page. Set to None to avoid generating overviews.
always_disable_rss = False:
Whether to always disable RSS feed generation
apply_to_posts = True:
Whether this classification applies to posts.
apply_to_pages = False:
Whether this classification applies to pages.
minimum_post_count_per_classification_in_overview = 1:
The minimum number of posts a classification must have to be listed in the overview.
omit_empty_classifications = False:
Whether post lists resp. indexes should be created for empty classifications.
add_other_languages_variable = False:
In case this is True, each classification page will get a list of triples (other_lang, other_classification, title) of classifications in other languages which should be linked. The list will be stored in the variable other_languages.
A dictionary of docstrings for path handlers. See eg. for examples. Must be overridden, keys are “taxonomy_index”, “taxonomy”, “taxonomy_atom”, “taxonomy_rss” (but using classification_name instead of “taxonomy”). If one of the values is False, the corresponding path handler will not be created.
add_other_languages_variable = False
always_disable_rss = False
apply_to_pages = False
apply_to_posts = True
classification_name = 'taxonomy'

Classify the given post for the given language.

Must return a list or tuple of strings.

extract_hierarchy(classification: str) → typing.List[str]

Given a classification, return a list of parts in the hierarchy.

For non-hierarchical taxonomies, it usually suffices to return [classification].

generate_atom_feeds_for_post_lists = False
get_classification_friendly_name(classification: str, lang: str, only_last_component=False) → str

Extract a friendly name from the classification.

The result of this function is usually displayed to the user, instead of using the classification string.

The argument only_last_component is only relevant to hierarchical taxonomies. If it is set, the printable name should only describe the last component of classification if possible.

get_implicit_classifications(lang: str) → typing.List[str]

Return a list of classification strings which should always appear in posts_per_classification.

get_other_language_variants(classification: str, lang: str, classifications_per_language: typing.List[str]) → typing.List[str]

Return a list of variants of the same classification in other languages.

Given a classification in a language lang, return a list of pairs (other_lang, other_classification) with lang != other_lang such that classification should be linked to other_classification.

Classifications where links to other language versions makes no sense should simply return an empty list.

Provided is a set of classifications per language (classifications_per_language).

get_overview_path(lang: str, dest_type='page') → str

Return path for classification overview.

This path handler for the classification overview must return one or two values (in this order):

  • a list or tuple of strings: the path relative to OUTPUT_DIRECTORY;
  • a string with values ‘auto’, ‘always’ or ‘never’, indicating whether INDEX_FILE should be added or not.

Note that this function must always return a list or tuple of strings; the other return value is optional with default value ‘auto’.

In case INDEX_FILE should potentially be added, the last element in the returned path must have no extension, and the PRETTY_URLS config must be ignored by this handler. The return value will be modified based on the PRETTY_URLS and INDEX_FILE settings.

dest_type can be either ‘page’, ‘feed’ (for Atom feed) or ‘rss’.

get_path(classification: str, lang: str, dest_type='page') → str

Return path to the classification page.

This path handler for the given classification must return one to three values (in this order):

  • a list or tuple of strings: the path relative to OUTPUT_DIRECTORY;
  • a string with values ‘auto’, ‘always’ or ‘never’, indicating whether INDEX_FILE should be added or not;
  • an integer if a specific page of the index is to be targeted (will be ignored for post lists), or None if the most current page is targeted.

Note that this function must always return a list or tuple of strings; the other two return values are optional with default values ‘auto’ and None.

In case INDEX_FILE should potentially be added, the last element in the returned path must have no extension, and the PRETTY_URLS config must be ignored by this handler. The return value will be modified based on the PRETTY_URLS and INDEX_FILE settings.

dest_type can be either ‘page’, ‘feed’ (for Atom feed) or ‘rss’.

For hierarchical taxonomies, the result of extract_hierarchy is provided as classification. For non-hierarchical taxonomies, the classification string itself is provided as classification.

has_hierarchy = False
include_posts_from_subhierarchies = False
include_posts_into_hierarchy_root = False
is_enabled(lang=None) → bool

Return True if this taxonomy is enabled, or False otherwise.

If lang is None, this determins whether the classification is made at all. If lang is not None, this determines whether the overview page and the classification lists are created for this language.

minimum_post_count_per_classification_in_overview = 1
more_than_one_classifications_per_post = False
name = 'dummy_taxonomy'
omit_empty_classifications = False
overview_page_hierarchy_variable_name = 'taxonomy_hierarchy'
overview_page_items_variable_name = 'items'
overview_page_variable_name = 'taxonomy'
path_handler_docstrings = {'taxonomy_index': '', 'taxonomy_rss': '', 'taxonomy': '', 'taxonomy_atom': ''}

Rearrange, modify or otherwise use the list of posts per classification and per language.

For compatibility reasons, the list could be stored somewhere else as well.

In case has_hierarchy is True, flat_hierarchy_per_lang is the flat hierarchy consisting of hierarchy_utils.TreeNode elements, and hierarchy_lookup_per_lang is the corresponding hierarchy lookup mapping classification strings to hierarchy_utils.TreeNode objects.

provide_context_and_uptodate(classification: str, lang: str, node=None) → typing.Tuple[typing.Dict]

Provide data for the context and the uptodate list for the list of the given classification.

Must return a tuple of two dicts. The first is merged into the page’s context, the second will be put into the uptodate list of all generated tasks.

For hierarchical taxonomies, node is the hierarchy_utils.TreeNode element corresponding to the classification.

Context must contain title, which should be something like ‘Posts about <classification>’.

provide_overview_context_and_uptodate(lang: str) → str

Provide data for the context and the uptodate list for the classification overview.

Must return a tuple of two dicts. The first is merged into the page’s context, the second will be put into the uptodate list of all generated tasks.

Context must contain title.

recombine_classification_from_hierarchy(hierarchy: typing.List[str]) → str

Given a list of parts in the hierarchy, return the classification string.

For non-hierarchical taxonomies, it usually suffices to return hierarchy[0].


Only generates list of posts for classification if this function returns True.


Only generates RSS feed for list of posts for classification if this function returns True.

show_list_as_index = False
show_list_as_subcategories_list = False
sort_classifications(classifications: typing.List[str], lang: str, level=None)

Sort the given list of classification strings.

Allows the plugin to order the classifications as it wants. The classifications will be ordered by natsort before calling this function. This function must sort in-place.

For hierarchical taxonomies, the elements of the list are a single path element of the path returned by extract_hierarchy(). The index of the path element in the path will be provided in level.


Sort the given list of posts.

Allows the plugin to order the posts per classification as it wants. The posts will be ordered by date (latest first) before calling this function. This function must sort in-place.

subcategories_list_template = 'taxonomy_list.tmpl'
template_for_classification_overview = 'list.tmpl'
template_for_single_list = 'tagindex.tmpl' module

The Post class.

class, config, destination, use_in_feeds, messages, template_name, compiler, destination_base=None, metadata_extractors_by=None)

Bases: :class:`object`

Represent a blog post or site page.

add_dependency(dependency, add='both', lang=None)

Add a file dependency for tasks using that post.

The dependency should be a string specifying a path, or a callable which returns such a string or a list of strings.

The add parameter can be ‘both’, ‘fragment’ or ‘page’, to indicate that this dependency shall be used

  • when rendering the fragment to HTML (‘fragment’ and ‘both’), or
  • when creating a page with parts of the Post embedded, which includes the HTML resulting from compiling the fragment (‘page’ or ‘both’).

If lang is not specified, this dependency is added for all languages.

add_dependency_uptodate(dependency, is_callable=False, add='both', lang=None)

Add a dependency for task’s uptodate for tasks using that post.

This can be for example an utils.config_changed object, or a list of such objects.

The is_callable parameter specifies whether dependency is a callable which generates an entry or a list of entries for the uptodate list, or whether it is an entry which can directly be added (as a single object or a list of objects).

The add parameter can be ‘both’, ‘fragment’ or ‘page’, to indicate that this dependency shall be used

  • when rendering the fragment to HTML (‘fragment’ and ‘both’), or
  • when creating a page with parts of the Post embedded, which includes the HTML resulting from compiling the fragment (‘page’ or ‘both’).

If lang is not specified, this dependency is added for all languages.


utils.config_changed({1: some_data}, ‘uniqueid’), False, ‘page’)

Return ALL the tags for this post.


Return localized author or BLOG_AUTHOR if unspecified.

If lang is not specified, it defaults to the current language from templates, as set in LocaleBorg.


Generate the cache/ file with the compiled post.


Return a list of file dependencies to build this post’s page.


Return a list of uptodate dependencies to build this post’s page.

These dependencies should be included in uptodate for the task which generates the page.


Return localized description.

destination_path(lang=None, extension='.html', sep='/')

Destination path for this post, relative to output/.

If lang is not specified, it’s the current language. Extension is used in the path if specified.

formatted_date(date_format, date=None)

Return the formatted date as unicode.


Return the updated date as unicode.


Return a list of uptodate dependencies to build this post’s fragment.

These dependencies should be included in uptodate for the task which generates the fragment.


Return a list of file dependencies to build this post’s fragment.


Return localized GUID.


Check if this page has a pretty URL.


Return True if this post has the mathjax tag in the current language or is a python notebook.


Return True if the translation actually exists.


Return next post.


Return the paragraph count for this post.

Return permalink for a post.


Return previous post.


Return the previewimage path.


Return reading time based on length of text.

register_depfile(dep, dest=None, lang=None)

Register a dependency in the dependency file.


Return the remaining paragraph count for this post (does not include teaser).


Remaining reading time based on length of text (does not include teaser).


Return the color of the post’s section.

Return the link to the post’s section (deprecated).


Return the name of the post’s section.


Return the slug for the post’s section.


Return the source file extension.

If prefix is True, a .src. prefix will be added to the resulting extension if it’s equal to the destination extension.

Return absolute link to the post’s source.


Return tags for the current language.


Return tags for a given language.


Return template name for this post.

text(lang=None, teaser_only=False, strip_html=False, show_read_more_link=True, feed_read_more_link=False, feed_links_append_query=None)

Read the post file for that language and return its contents.

teaser_only=True breaks at the teaser marker and returns only the teaser. strip_html=True removes HTML tags show_read_more_link=False does not add the Read more… link feed_read_more_link=True uses FEED_READ_MORE_LINK instead of INDEX_READ_MORE_LINK lang=None uses the last used to set locale

All links in the returned HTML will be relative. The HTML returned is a bare fragment, not a full document.


Return localized title.

If lang is not specified, it defaults to the current language from templates, as set in LocaleBorg.


Return path to the translation’s base_path file.


Return path to the translation’s source file.

static write_depfile(dest, deps_list, post=None, lang=None)

Write a depfile for a given language.

nikola.rc4 module

nikola.shortcodes module

Support for Hugo-style shortcodes.

exception nikola.shortcodes.ParsingError

Bases: :class:`Exception`

Used for forwarding parsing error messages to apply_shortcodes.

nikola.shortcodes.apply_shortcodes(data, registry, site=None, filename=None, raise_exceptions=False, lang=None, extra_context=None)

Apply Hugo-style shortcodes on data.

{{% name parameters %}} will end up calling the registered “name” function with the given parameters. {{% name parameters %}} something {{% /name %}} will call name with the parameters and one extra “data” parameter containing ” something “.

If raise_exceptions is set to True, instead of printing error messages and terminating, errors are passed on as exceptions to the caller.

The site parameter is passed with the same name to the shortcodes so they can access Nikola state.

>>> print(apply_shortcodes('==> {{% foo bar=baz %}} <==', {'foo': lambda *a, **k: k['bar']}))
==> baz <==
>>> print(apply_shortcodes('==> {{% foo bar=baz %}}some data{{% /foo %}} <==', {'foo': lambda *a, **k: k['bar']+k['data']}))
==> bazsome data <==

Return data with replaced shortcodes, shortcodes.

data is the original data, with the shortcodes replaced by UUIDs.

a dictionary of shortcodes, where the keys are UUIDs and the values are the shortcodes themselves ready to process.

nikola.state module

Persistent state implementation.

class nikola.state.Persistor(path)

Bases: :class:`object`

Persist stuff in a place.

This is an intentionally dumb implementation. It is not meant to be fast, or useful for arbitrarily large data. Use lightly.

Intentionally it has no namespaces, sections, etc. Use as a responsible adult.


Delete key and the value it contains.


Get data stored in key.

set(key, value)

Store value in key.

nikola.utils module

Utility functions.

class nikola.utils.CustomEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: :class:`json.encoder.JSONEncoder`

Custom JSON encoder.


Create default encoding handler.


Return the theme’s path, which equals the theme’s name.

nikola.utils.get_theme_path_real(theme, themes_dirs)

Return the path where the given theme’s files are located.

Looks in ./themes and in the place where themes go when installed.

nikola.utils.get_theme_chain(theme, themes_dirs)

Create the full theme inheritance chain including paths.

nikola.utils.load_messages(themes, translations, default_lang, themes_dirs)

Load theme’s messages into context.

All the messages from parent themes are loaded, and “younger” themes have priority.

nikola.utils.copy_tree(src, dst, link_cutoff=None, ignored_filenames=None)

Copy a src tree to the dst folder.


src = “themes/default/assets” dst = “output/assets”

should copy “themes/defauts/assets/foo/bar” to “output/assets/foo/bar”

If link_cutoff is set, then the links pointing at things inside that folder will stay as links, and links pointing outside that folder will be copied.

ignored_filenames is a set of file names that will be ignored.

nikola.utils.copy_file(source, dest, cutoff=None)

Copy a file from source to dest. If link target starts with cutoff, symlinks are used.

nikola.utils.slugify(value, lang=None, force=False)

Normalize string, convert to lowercase, remove non-alpha characters, convert spaces to hyphens.

From Django’s “django/template/”.

>>> print(slugify('áéí.óú', lang='en'))
>>> print(slugify('foo/bar', lang='en'))
>>> print(slugify('foo bar', lang='en'))
nikola.utils.unslugify(value, lang=None, discard_numbers=True)

Given a slug string (as a filename), return a human readable string.

If discard_numbers is True, numbers right at the beginning of input will be removed.

nikola.utils.to_datetime(value, tzinfo=None)

Convert string to datetime.

nikola.utils.apply_filters(task, filters, skip_ext=None)

Apply filters to a task.

If any of the targets of the given task has a filter that matches, adds the filter commands to the commands of the task, and the filter itself to the uptodate of the task.

class nikola.utils.config_changed(config, identifier=None)

Bases: :class:``

A copy of doit’s config_changed, using pickle instead of serializing manually.


Configure a task with a digest.

nikola.utils.get_crumbs(path, is_file=False, index_folder=None, lang=None)

Create proper links for a crumb bar.

index_folder is used if you want to use title from index file instead of folder name as breadcrumb text.

>>> crumbs = get_crumbs('galleries')
>>> len(crumbs)
>>> crumbs[0]
['#', 'galleries']
>>> crumbs = get_crumbs(os.path.join('galleries','demo'))
>>> len(crumbs)
>>> crumbs[0]
['..', 'galleries']
>>> crumbs[1]
['#', 'demo']
>>> crumbs = get_crumbs(os.path.join('listings','foo','bar'), is_file=True)
>>> len(crumbs)
>>> crumbs[0]
['..', 'listings']
>>> crumbs[1]
['.', 'foo']
>>> crumbs[2]
['#', 'bar']

Given a datetime value, find the name of the time zone.

DEPRECATED: This thing returned basically the 1st random zone that matched the offset.

nikola.utils.get_asset_path(path, themes, files_folders={'files': ''}, output_dir='output')

Return the “real”, absolute path to the asset.

By default, it checks which theme provides the asset. If the asset is not provided by a theme, then it will be checked for in the FILES_FOLDERS. If it’s not provided by either, it will be chacked in output, where it may have been created by another plugin.

>>> print(get_asset_path('assets/css/nikola_rst.css', get_theme_chain('bootstrap3', ['themes'])))
>>> print(get_asset_path('assets/css/theme.css', get_theme_chain('bootstrap3', ['themes'])))
>>> print(get_asset_path('', get_theme_chain('bootstrap3', ['themes']), {'nikola': ''}))
>>> print(get_asset_path('', get_theme_chain('bootstrap3', ['themes']), {'nikola': 'nikola'}))
>>> print(get_asset_path('nikola/', get_theme_chain('bootstrap3', ['themes']), {'nikola': 'nikola'}))

alias of :class:`str`


alias of :class:`bytes`


Return a Unicode string of one character with ordinal i; 0 <= i <= 0x10ffff.

class nikola.utils.Functionary(default, default_lang)

Bases: :class:`collections.defaultdict`

Class that looks like a function, but is a defaultdict.

class nikola.utils.TranslatableSetting(name, inp, translations)

Bases: :class:`object`

A setting that can be translated.

You can access it via: SETTING(lang). You can omit lang, in which case Nikola will ask LocaleBorg, unless you set SETTING.lang, which overrides that call.

You can also stringify the setting and you will get something sensible (in what LocaleBorg claims the language is, can also be overriden by SETTING.lang). Note that this second method is deprecated. It is kept for backwards compatibility and safety. It is not guaranteed.

The underlying structure is a defaultdict. The language that is the default value of the dict is provided with __init__().

default_lang = 'en'
format(*args, **kwargs)

Format ALL the values in the setting the same way.


Return the language that should be used to retrieve settings.

lang = None

Format ALL the values in the setting, on a per-language basis.

class nikola.utils.TemplateHookRegistry(name, site)

Bases: :class:`object`

A registry for template hooks.


>>> r = TemplateHookRegistry('foo', None)
>>> r.append('Hello!')
>>> r.append(lambda x: 'Hello ' + x + '!', False, 'world')
>>> repr(r())
'Hello!\nHello world!'
append(inp, wants_site_and_context=False, *args, **kwargs)

Register an item.

inp can be a string or a callable returning one. wants_site tells whether there should be a site keyword

argument provided, for accessing the site.

Further positional and keyword arguments are passed as-is to the callable.

wants_site, args and kwargs are ignored (but saved!) if inp is not callable. Callability of inp is determined only once.


Calculate dependencies for a registry.


Generate items.

class nikola.utils.LocaleBorg

Bases: :class:`object`

Provide locale related services and autoritative current_lang.

current_lang is the last lang for which the locale was set and is meant to be set only by LocaleBorg.set_locale.

python’s locale code should not be directly called from code outside of LocaleBorg, they are compatibilty issues with py version and OS support better handled at one central point, LocaleBorg.

In particular, don’t call locale.setlocale outside of LocaleBorg.

We need locales only for the languages there is a nikola translation. We don’t need to support current_lang through nested contexts

# early in cmd or test execution LocaleBorg.initialize(…)

# any time later lang = LocaleBorg().<service>

Available services:
.current_lang : autoritative current_lang , the last seen in set_locale .set_locale(lang) : sets current_lang and sets the locale for lang .get_month_name(month_no, lang) : returns the localized month name

NOTE: never use locale.getlocale() , it can return values that locale.setlocale will not accept in Windows XP, 7 and pythons 2.6, 2.7, 3.3 Examples: “Spanish”, “French” can’t do the full circle set / get / set

classmethod add_handler(month_name_handler=None, formatted_date_handler=None)

Allow to add month name and formatted date handlers.

If month_name_handler is not None, it is expected to be a callable which accepts (month_no, lang) and returns either a string or None.

If formatted_date_handler is not None, it is expected to be a callable which accepts (date_format, date, lang) and returns either a string or None.

A handler is expected to either return the correct result for the given language and data, or return None to indicate it is not able to do the job. In that case, the next handler is asked, and finally the default implementation is used.


Return the current language.

formatted_date(date_format, date)

Return the formatted date as unicode.

get_month_name(month_no, lang)

Return localized month name in an unicode string.

classmethod initialize(locales, initial_lang)

Initialize LocaleBorg.

locales : dict with lang: locale_n

the same keys as in nikola’s TRANSLATIONS locale_n a sanitized locale, meaning

locale.setlocale(locale.LC_ALL, locale_n) will succeed locale_n expressed in the string form, like “en.utf8”
initialized = False
classmethod reset()

Reset LocaleBorg.

Used in testing to prevent leaking state between tests.


Set the locale for language lang, returns an empty string.

in linux the locale encoding is set to utf8, in windows that cannot be guaranted. In either case, the locale encoding is available in cls.encodings[lang]


Return bytes encoded in the system’s encoding.


Return Unicode.


Create a folder and its parents if needed (mkdir -p).

nikola.utils.get_parent_theme_name(theme_name, themes_dirs=None)

Get name of parent theme.

nikola.utils.demote_headers(doc, level=1)

Demote <hN> elements by one.

nikola.utils.get_translation_candidate(config, path, lang)

Return a possible path where we can find the translated version of some page, based on the TRANSLATIONS_PATTERN configuration variable.

>>> config = {'TRANSLATIONS_PATTERN': '{path}.{lang}.{ext}', 'DEFAULT_LANG': 'en', 'TRANSLATIONS': {'es':'1', 'en': 1}}
>>> print(get_translation_candidate(config, '*.rst', 'es'))
>>> print(get_translation_candidate(config, '', 'es'))
>>> print(get_translation_candidate(config, '*.es.rst', 'es'))
>>> print(get_translation_candidate(config, '*.es.rst', 'en'))
>>> print(get_translation_candidate(config, 'cache/posts/', 'en'))
>>> print(get_translation_candidate(config, 'cache/posts/', 'es'))
>>> print(get_translation_candidate(config, 'cache/pages/charts.html', 'es'))
>>> print(get_translation_candidate(config, 'cache/pages/charts.html', 'en'))
>>> config = {'TRANSLATIONS_PATTERN': '{path}.{ext}.{lang}', 'DEFAULT_LANG': 'en', 'TRANSLATIONS': {'es':'1', 'en': 1}}
>>> print(get_translation_candidate(config, '*.rst', 'es'))
>>> print(get_translation_candidate(config, '*', 'es'))
>>> print(get_translation_candidate(config, '*', 'en'))
>>> print(get_translation_candidate(config, 'cache/posts/', 'en'))
>>> print(get_translation_candidate(config, 'cache/posts/', 'es'))
nikola.utils.write_metadata(data, metadata_format=None, comment_wrap=False, site=None, compiler=None)

Write metadata.

Recommended usage: pass site, comment_wrap (True, False, or a 2-tuple of start/end markers), and optionally compiler. Other options are for backwards compatibility.

nikola.utils.ask(query, default=None)

Ask a question.

nikola.utils.ask_yesno(query, default=None)

Ask a yes/no question.

nikola.utils.options2docstring(name, options)

Translate options to a docstring.


Split a path.

nikola.utils.get_displayed_page_number(i, num_pages, site)

Get page number to be displayed for entry i.

nikola.utils.adjust_name_for_index_path_list(path_list, i, displayed_i, lang, site, force_addition=False, extension=None)

Retrurn a path list for a given index page.

nikola.utils.adjust_name_for_index_path(name, i, displayed_i, lang, site, force_addition=False, extension=None)

Return file name for a given index file.

Return link for a given index file.

class nikola.utils.NikolaPygmentsHTML(anchor_ref, classes=None, linenos='table', linenostart=1)

Bases: :class:`pygments.formatters.html.HtmlFormatter`

A Nikola-specific modification of Pygments’ HtmlFormatter.

wrap(source, outfile)

Wrap the source, which is a generator yielding individual lines, in custom generators.

nikola.utils.create_redirect(src, dst)

Create a redirection.


Clean drafts and future posts before deployment.

nikola.utils.sort_posts(posts, *keys)

Sort posts by a given predicate. Helper function for templates.

If a key starts with ‘-‘, it is sorted in descending order.

Usage examples:

sort_posts(timeline, 'title', 'date')
sort_posts(timeline, 'author', '-section_name')
nikola.utils.smartjoin(join_char: str, string_or_iterable) → str

Join string_or_iterable with join_char if it is not a string already.

>>> smartjoin('; ', 'foo, bar')
'foo, bar'
>>> smartjoin('; ', ['foo', 'bar'])
'foo; bar'
nikola.utils.indent(text, prefix, predicate=None)

Add ‘prefix’ to the beginning of selected lines in ‘text’.

If ‘predicate’ is provided, ‘prefix’ will only be added to the lines where ‘predicate(line)’ is True. If ‘predicate’ is not provided, it will default to adding ‘prefix’ to all non-empty lines that do not consist solely of whitespace characters.


Given path to a file, load data from it.


Convert all named and numeric character references (e.g. &gt;, &#62;, &x3e;) in the string s to the corresponding unicode characters. This function uses the rules defined by the HTML 5 standard for both valid and invalid character references, and the list of HTML 5 named character references defined in html.entities.html5.

nikola.utils.rss_writer(rss_obj, output_path)

Write an RSS object to an xml file.

nikola.utils.map_metadata(meta, key, config)

Map metadata from other platforms to Nikola names.

This uses the METADATA_MAPPING and METADATA_VALUE_MAPPING settings (via config) and modifies the dict in place.

nikola.utils.req_missing(names, purpose, python=True, optional=False)

Log that we are missing some requirements.

names is a list/tuple/set of missing things. purpose is a string, specifying the use of the missing things.

It completes the sentence:
In order to {purpose}, you must install …
python specifies whether the requirements are Python packages
or other software.
optional specifies whether the things are required
(this is an error and we exit with code 5) or not (this is just a warning).

Returns the message shown to the user (which you can usually discard). If no names are specified, False is returned and nothing is shown to the user.

class nikola.utils.TreeNode(name, parent=None)

Bases: :class:`object`

A tree node.


Get children of a node.


Get path.

indent_change_after = 0
indent_change_before = 0
indent_levels = None
nikola.utils.clone_treenode(treenode, parent=None, acceptor=<function <lambda>>)

Clone a TreeNode.

Children are only cloned if acceptor returns True when applied on them.

Returns the cloned node if it has children or if acceptor applied to it returns True. In case neither applies, None is returned.


Flatten a tree.

nikola.utils.sort_classifications(taxonomy, classifications, lang)

Sort the given list of classifications of the given taxonomy and language.

taxonomy must be a Taxonomy plugin. classifications must be an iterable collection of classification strings for that taxonomy. lang is the language the classifications are for.

The result will be returned as a sorted list. Sorting will happen according to the way the complete classification hierarchy for the taxonomy is sorted.


Join a category path.


Parse a category name.

nikola.winutils module

windows utilities to workaround problems with symlinks in a git clone.


Convert git symlinks to real content.

Most (all?) of git implementations in windows store a symlink pointing into the repo as a text file, the text being the relative path to the file with the real content.

So, in a clone of nikola in windows the symlinked files will have the wrong content; a .zip download from Github has the same problem.

This function will rewrite each symlinked file with the correct contents, but keep in mind that the working copy will be seen as dirty by git after operation.

Expects to find a list of symlinked files at nikola/data/symlinked.txt

The list can be generated by scripts/ , which is basically a redirect of

cd nikola_checkout git ls-files -s | awk ‘/120000/{print $4}’

Weakness: if interrupted of fail amidst a directory copy, next run will not see the missing files.

nikola.winutils.is_file_into_dir(filename, dirname)

Check if a file is in directory.

Module contents

Nikola – a modular, fast, simple, static website generator.