1.1. nikola package

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

1.1.1. Subpackages

1.1.2. Submodules

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

nikola.filters.apply_to_binary_file(f)

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.

nikola.filters.apply_to_text_file(f)

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.

nikola.filters.cssminify(data)

Minify CSS using <https://www.toptal.com/developers/cssminifier>.

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

Post-process HTML via lxml to deduplicate IDs.

nikola.filters.html5lib_minify(data)

Minify with html5lib.

nikola.filters.html5lib_xmllike(data)

Transform document to an XML-like form with html5lib.

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

Run HTML tidy with minimal settings.

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

Run HTML Tidy without line wrapping.

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

Run HTML Tidy with tidy.conf as config file.

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

Run HTML Tidy with line wrapping.

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

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.

nikola.filters.jsminify(data)

Minify JS using <https://www.toptal.com/developers/javascript-minifier>.

nikola.filters.jsonminify(data)

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.

nikola.filters.minify_lines(data)

Do nothing – deprecated filter.

nikola.filters.normalize_html(data)

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

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

Run optipng on a file.

nikola.filters.php_template_injection(data)

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.

nikola.filters.typogrify(data)

Prettify text with typogrify.

nikola.filters.typogrify_custom(data, typogrify_filters=None, ignore_tags=None)

Run typogrify with a custom list of filter functions.

nikola.filters.typogrify_oldschool(data)

Prettify text with typogrify.

nikola.filters.typogrify_sans_widont(data)

Prettify text with typogrify, skipping the widont filter.

nikola.filters.xmlminify(data)

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

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

Run YUI Compressor on a file.

1.1.4. nikola.hierarchy_utils module

Hierarchy utility functions.

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

Bases: object

A tree node.

get_children()

Get children of a node.

get_path()

Get path.

indent_change_after = 0
indent_change_before = 0
indent_levels = None
nikola.hierarchy_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.

nikola.hierarchy_utils.flatten_tree_structure(root_list)

Flatten a tree.

nikola.hierarchy_utils.join_hierarchical_category_path(category_path)

Join a category path.

nikola.hierarchy_utils.parse_escaped_hierarchical_category_name(category_name)

Parse a category name.

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

1.1.5. nikola.image_processing module

Process images.

class nikola.image_processing.ImageProcessor

Bases: object

Apply image operations.

dates: Dict[str, datetime]
filter_exif(exif, whitelist)

Filter EXIF data as described in the documentation.

image_date(src)

Try to figure out the date of the image.

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

Make a copy of the image in the requested size(s).

max_sizes should be a list of sizes, and the image would be resized to fit in a square of each size (preserving aspect ratio).

dst_paths is a list of the destination paths, and should be the same length as max_sizes.

Backwards compatibility:

  • If max_sizes is None, it’s set to [max_size]

  • If dst_paths is None, it’s set to [dst]

  • Either max_size or max_sizes should be set

  • Either dst or dst_paths should be set

resize_svg(src, dst_paths, max_sizes, bigger_panoramas)

Make a copy of an svg at the requested sizes.

1.1.6. nikola.log module

Logging support.

nikola.log.get_logger(name: str, handlers=None) → Logger

Get a logger with handlers attached.

1.1.7. nikola.metadata_extractors module

Default metadata extractors and helper functions.

class nikola.metadata_extractors.MetaCondition(value)

Bases: Enum

Conditions for extracting metadata.

compiler = 4
config_bool = 1
config_present = 2
extension = 3
first_line = 5
never = -1
class nikola.metadata_extractors.MetaPriority(value)

Bases: Enum

Priority of metadata.

An extractor is used if and only if the higher-priority extractors returned nothing.

fallback = 4
normal = 3
override = 1
specialized = 2
class nikola.metadata_extractors.MetaSource(value)

Bases: Enum

Source of metadata.

filename = 2
text = 1
nikola.metadata_extractors.check_conditions(post, filename: str, conditions: list, config: dict, source_text: str) → bool

Check the conditions for a metadata extractor.

1.1.8. nikola.nikola module

The main Nikola site object.

class nikola.nikola.Nikola(**config)

Bases: object

Class that handles site generation.

Takes a site config as argument on creation.

property GLOBAL_CONTEXT

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

property MESSAGES
property THEMES

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.

category_path_to_category_name(category_path)

Translate a category path to a category name.

clean_task_paths(task)

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.

Example:

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

gen_tasks(name, plugin_category, doc='')

Generate tasks.

generic_atom_renderer(lang, posts, context_source, kw, basename, classification, kind, additional_dependencies=None)

Create an Atom feed.

lang: The language posts: A list of posts 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 classification: name of current classification (used to generate links) kind: classification kind (used to generate links) additional_dependencies: a list of dependencies which will be added

to task[‘uptodate’]

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

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

Note: if context[‘featured’] is present, it must be a list of posts, whose dependencies will be taken 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_compiler(source_name)

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

To make things easier for users, the mapping in conf.py 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) → None

Load plugins as needed.

Create a link.

parse_category_name(category_name)

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 conf.py)

The returned value is either a path relative to output, like “categories/whatever.html”, or an absolute URL (”https://getnikola.com/”), 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.

plugin_manager: PluginManager
post_path(name, lang)

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

Example:

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: str, output_name: str, 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.

Example:

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.

Example:

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

slug_source(name, lang)

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

Example:

link://slug_source/yellow-camaro => /posts/cars/awful/yellow-camaro.rst

static sort_posts_chronologically(posts, lang=None)

Sort a list of posts chronologically.

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

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

1.1.9. nikola.plugin_categories module

Nikola plugin categories.

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

Bases: BasePlugin, 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.ConfigPlugin

Bases: BasePlugin

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

name = 'dummy_config_plugin'
class nikola.plugin_categories.LateTask

Bases: BaseTask

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

name = 'dummy_latetask'
class nikola.plugin_categories.MarkdownExtension

Bases: CompilerExtension

Extensions for Markdown.

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

Bases: BasePlugin

Plugins that can extract meta information from post files.

check_requirements()

Check if requirements for an extractor are satisfied.

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

Extract metadata from filename.

extract_text(source_text: str) → 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) → Tuple[str, str]

Split text into metadata and content (both strings).

split_metadata_re = None
supports_write = False
write_metadata(metadata: 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.PageCompiler

Bases: 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 = {'category': '', 'date': '', 'description': '', 'link': '', 'slug': '', 'tags': '', 'title': '', 'type': 'text'}
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.

get_dep_filename(post: Post, lang: str) → str

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

get_extra_targets(post: Post, lang: str, dest: str) → List[str]

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_metadata(post: Post, lang=None) → Dict[str, str]

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

register_extra_dependencies(post: Post)

Add dependency to post object to check .dep file.

split_metadata(data: str, post=None, lang=None) → Tuple[str, str]

Split data from metadata in the raw post content.

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

Bases: BasePlugin

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

scan() → List[Post]

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

supported_extensions() → List[str] | None

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

class nikola.plugin_categories.RestExtension

Bases: CompilerExtension

Extensions for reStructuredText.

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

Bases: BasePlugin

Signal handlers.

name = 'dummy_signal_handler'
class nikola.plugin_categories.Task

Bases: BaseTask

Task generator.

name = 'dummy_task'
class nikola.plugin_categories.TaskMultiplier

Bases: 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.Taxonomy

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

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_atom = False:

Whether to always disable Atom feed generation.

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.

path_handler_docstrings:

A dictionary of docstrings for path handlers. See eg. nikola.py 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_atom = False
always_disable_rss = False
apply_to_pages = False
apply_to_posts = True
classification_name = 'taxonomy'
classify(post: Post, lang: str) → Iterable[str]

Classify the given post for the given language.

Must return a list or tuple of strings.

extract_hierarchy(classification: str) → List[str]

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

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

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) → 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: List[str]) → 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': '', 'taxonomy_atom': '', 'taxonomy_index': '', 'taxonomy_rss': ''}
postprocess_posts_per_classification(posts_per_classification_per_language: List[Post], flat_hierarchy_per_lang=None, hierarchy_lookup_per_lang=None) → None

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) → Tuple[Dict, 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: 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].

should_generate_atom_for_classification_page(classification: str, post_list: List[Post], lang: str) → bool

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

should_generate_classification_page(classification: str, post_list: List[Post], lang: str) → bool

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

should_generate_rss_for_classification_page(classification: str, post_list: List[Post], lang: str) → bool

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: 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_posts(posts: List[Post], classification: str, lang: str)

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'
class nikola.plugin_categories.TemplateSystem

Bases: BasePlugin

Provide support for templating systems.

get_deps(filename: str, context=None)

Return paths to dependencies for the template loaded from filename.

get_string_deps(text: str, context=None)

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: Dict[str, 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: Dict[str, str]) → str

Render template to a string using context.

set_directories(directories: List[str], cache_folder: str) → None

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

set_user_engine_factory(factory: Callable[[...], Any]) → None

Accept a function that will be used to produce the underlying raw template engine.

template_deps(template_name: str, context=None)

Return filenames which are dependencies for a template.

1.1.10. nikola.post module

The Post class.

class nikola.post.Post(source_path, config, destination, use_in_feeds, messages, template_name, compiler, destination_base=None, metadata_extractors_by=None)

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

Example:

post.add_dependency_uptodate(

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

property alltags

Return ALL the tags for this post.

author(lang=None) → str

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.

authors(lang=None) → list

Return localized authors or BLOG_AUTHOR if unspecified.

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

compile(lang)

Generate the cache/ file with the compiled post.

deps(lang)

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

deps_uptodate(lang)

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.

description(lang=None)

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

formatted_updated(date_format)

Return the updated date as string.

fragment_deps(lang)

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

fragment_deps_uptodate(lang)

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

guid(lang=None)

Return localized GUID.

property has_math

Return True if this post has has_math set to True or is a python notebook.

Alternatively, it will return True if it has set the mathjax tag in the current language and the USE_TAG_METADATA config setting is True.

has_oldstyle_metadata_tags = False
has_pretty_url(lang)

Check if this page has a pretty URL.

property hyphenate

Post is hyphenated.

is_draft = False
is_private = False
is_translation_available(lang)

Return True if the translation actually exists.

property is_two_file

Post has a separate .meta file.

property next_post

Return next post.

property paragraph_count

Return the paragraph count for this post.

Return permalink for a post.

post_status = 'published'
property prev_post

Return previous post.

property previewimage

Return the previewimage path.

property reading_time

Return reading time based on length of text.

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

Register a dependency in the dependency file.

property remaining_paragraph_count

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

property remaining_reading_time

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

save(lang=None, source=None, meta=None)

Write post source to disk.

Use this with utmost care, it may wipe out a post.

Keyword Arguments:
lang str – Language for this source. If set to None,

use current language.

source str – The source text for the post in the

language. If set to None, use current source for this language.

meta dict – Metadata for this language, if not set,

use current metadata for this language.

should_hide_title()

Return True if this post’s title should be hidden. Use in templates to manage posts without titles.

should_show_title()

Return True if this post’s title should be displayed. Use in templates to manage posts without titles.

source(lang=None)

Read the post and return its source.

source_ext(prefix=False)

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.

property tags

Return tags for the current language.

tags_for_language(lang)

Return tags for a given language.

property template_name

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

title(lang=None)

Return localized title.

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

translated_base_path(lang)

Return path to the translation’s base_path file.

translated_source_path(lang)

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.

write_metadata(lang=None)

Save the post’s metadata.

Keep in mind that this will save either in the post file or in a .meta file, depending on self.is_two_file.

metadata obtained from filenames or document contents will be superseded by this, and becomes inaccessible.

Post contents will not be modified.

If you write to a language not in self.translated_to an exception will be raised.

Remember to scan_posts(really=True) after you update metadata if you want the rest of the system to know about the change.

1.1.11. nikola.shortcodes module

Support for Hugo-style shortcodes.

exception nikola.shortcodes.ParsingError

Bases: 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 <==
nikola.shortcodes.extract_shortcodes(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.

1.1.12. nikola.state module

Persistent state implementation.

class nikola.state.Persistor(path)

Bases: 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)

Delete key and the value it contains.

get(key)

Get data stored in key.

set(key, value)

Store value in key.

1.1.13. 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: JSONEncoder

Custom JSON encoder.

default(obj)

Create default encoding handler.

class nikola.utils.Functionary(default, default_lang)

Bases: defaultdict

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

class nikola.utils.LocaleBorg

Bases: object

Provide locale related services and autoritative current_lang.

This class stores information about the locales used and interfaces with the Babel library to provide internationalization services.

Usage:

# 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 .formatted_date: format a date(time) according to locale rules .format_date_in_string: take a message and format the date in it

The default implementation uses the Babel package and completely ignores the Python locale module. If you wish to override this, write functions and assign them to the appropriate names. The functions are:

  • LocaleBorg.datetime_formatter(date, date_format, lang, locale)

  • LocaleBorg.in_string_formatter(date, mode, custom_format, lang, locale)

property current_lang: str

Return the current language.

datetime_formatter = None
format_date_in_string(message: str, date: date, lang: str | None = None) → str

Format date inside a string (message).

Accepted modes: month, month_year, month_day_year. Format: {month} for standard, {month:MMMM} for customization.

formatted_date(date_format: str, date: date | datetime, lang: str | None = None) → str

Return the formatted date/datetime as a string.

in_string_formatter = None
classmethod initialize(locales: Dict[str, str], initial_lang: str)

Initialize LocaleBorg.

locales: dict with custom locale name overrides.

initialized = False
classmethod reset()

Reset LocaleBorg.

Used in testing to prevent leaking state between tests.

set_locale(lang: str) → str

Set the current language and return an empty string (to make use in templates easier).

class nikola.utils.NikolaPygmentsHTML(anchor_ref=None, classes=None, **kwargs)

Bases: BetterHtmlFormatter

A Nikola-specific modification of Pygments’ HtmlFormatter.

wrap(source, *args)

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

class nikola.utils.TemplateHookRegistry(name, site)

Bases: object

A registry for template hooks.

Usage:

>>> 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_deps()

Calculate dependencies for a registry.

generate()

Generate items.

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

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

get_lang()

Return the language that should be used to retrieve settings.

lang = None
langformat(formats)

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

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

Bases: object

A tree node.

get_children()

Get children of a node.

get_path()

Get path.

indent_change_after = 0
indent_change_before = 0
indent_levels = None

Return link for a given index file.

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.

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

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

Ask a question.

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

Ask a yes/no question.

nikola.utils.bool_from_meta(meta, key, fallback=False, blank=None)

Convert a boolean-ish meta value to a boolean.

nikola.utils.clean_before_deployment(site)

Clean drafts and future posts before deployment.

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.

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

Bases: config_changed

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

configure_task(task)

Configure a task with a digest.

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.copy_tree(src, dst, link_cutoff=None, ignored_filenames=None)

Copy a src tree to the dst folder.

Example:

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.create_redirect(src, dst)

Create a redirection.

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

Demote <hN> elements by one.

nikola.utils.flatten_tree_structure(root_list)

Flatten a tree.

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'])))
/.../nikola/data/themes/base/assets/css/nikola_rst.css

>>> print(get_asset_path('assets/css/theme.css', get_theme_chain('bootstrap3', ['themes'])))
/.../nikola/data/themes/bootstrap3/assets/css/theme.css

>>> print(get_asset_path('nikola.py', get_theme_chain('bootstrap3', ['themes']), {'nikola': ''}))
/.../nikola/nikola.py

>>> print(get_asset_path('nikola.py', get_theme_chain('bootstrap3', ['themes']), {'nikola': 'nikola'}))
None

>>> print(get_asset_path('nikola/nikola.py', get_theme_chain('bootstrap3', ['themes']), {'nikola': 'nikola'}))
/.../nikola/nikola.py
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)
1
>>> crumbs[0]
['#', 'galleries']

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

>>> crumbs = get_crumbs(os.path.join('listings','foo','bar'), is_file=True)
>>> len(crumbs)
3
>>> crumbs[0]
['..', 'listings']
>>> crumbs[1]
['.', 'foo']
>>> crumbs[2]
['#', 'bar']
nikola.utils.get_displayed_page_number(i, num_pages, site)

Get page number to be displayed for entry i.

nikola.utils.get_parent_theme_name(theme_name, themes_dirs=None) → str | None

Get name of parent theme.

nikola.utils.get_theme_chain(theme, themes_dirs) → List[str]

Create the full theme inheritance chain including paths.

nikola.utils.get_theme_path(theme)

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

nikola.utils.get_theme_path_real(theme, themes_dirs) → str

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_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'))
*.es.rst
>>> print(get_translation_candidate(config, 'fancy.post.rst', 'es'))
fancy.post.es.rst
>>> print(get_translation_candidate(config, '*.es.rst', 'es'))
*.es.rst
>>> print(get_translation_candidate(config, '*.es.rst', 'en'))
*.rst
>>> print(get_translation_candidate(config, 'cache/posts/fancy.post.es.html', 'en'))
cache/posts/fancy.post.html
>>> print(get_translation_candidate(config, 'cache/posts/fancy.post.html', 'es'))
cache/posts/fancy.post.es.html
>>> print(get_translation_candidate(config, 'cache/pages/charts.html', 'es'))
cache/pages/charts.es.html
>>> print(get_translation_candidate(config, 'cache/pages/charts.html', 'en'))
cache/pages/charts.html

>>> config = {'TRANSLATIONS_PATTERN': '{path}.{ext}.{lang}', 'DEFAULT_LANG': 'en', 'TRANSLATIONS': {'es':'1', 'en': 1}}
>>> print(get_translation_candidate(config, '*.rst', 'es'))
*.rst.es
>>> print(get_translation_candidate(config, '*.rst.es', 'es'))
*.rst.es
>>> print(get_translation_candidate(config, '*.rst.es', 'en'))
*.rst
>>> print(get_translation_candidate(config, 'cache/posts/fancy.post.html.es', 'en'))
cache/posts/fancy.post.html
>>> print(get_translation_candidate(config, 'cache/posts/fancy.post.html', 'es'))
cache/posts/fancy.post.html.es
nikola.utils.get_tzname(dt)

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.html_unescape(s)

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

nikola.utils.join_hierarchical_category_path(category_path)

Join a category path.

nikola.utils.load_data(path)

Given path to a file, load data from it.

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.makedirs(path)

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

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.options2docstring(name, options)

Translate options to a docstring.

nikola.utils.os_path_split(path)

Split a path.

nikola.utils.parse_escaped_hierarchical_category_name(category_name)

Parse a category name.

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.

nikola.utils.rss_writer(rss_obj, output_path)

Write an RSS object to an xml file.

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/defaultfilters.py”.

>>> print(slugify('áéí.óú', lang='en'))
aeiou

>>> print(slugify('foo/bar', lang='en'))
foobar

>>> print(slugify('foo bar', lang='en'))
foo-bar
nikola.utils.smartjoin(join_char: str, string_or_iterable: None | str | bytes | Iterable[Any]) → str

Join string_or_iterable with join_char if it is iterable; otherwise convert it to string.

>>> smartjoin('; ', 'foo, bar')
'foo, bar'
>>> smartjoin('; ', ['foo', 'bar'])
'foo; bar'
>>> smartjoin(' to ', ['count', 42])
'count to 42'
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.

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.sys_decode(thing)

Return Unicode.

nikola.utils.sys_encode(thing)

Return bytes encoded in the system’s encoding.

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

Convert string to datetime.

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

1.1.14. nikola.winutils module

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

nikola.winutils.fix_all_git_symlinked(topdir: Path)

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/generate_symlinked_list.sh , 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_in_dir(filename: Path, dirname: Path) → bool

Check if a file is in directory.