1.1. nikola package — Nikola 8.1.3 documentation

# 1.1. nikola package

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

## 1.1.1. Subpackages

- 1.1.1.1. nikola.packages package
  - 1.1.1.1.1. Subpackages
    - 1.1.1.1.1.1. nikola.packages.datecond package
    - 1.1.1.1.1.2. nikola.packages.pygments_better_html package
- 1.1.1.2. nikola.plugins package
  - 1.1.1.2.1. Subpackages
    - 1.1.1.2.1.1. nikola.plugins.command package
      - 1.1.1.2.1.1.1. Subpackages
      - 1.1.1.2.1.1.2. Submodules
      - 1.1.1.2.1.1.3. nikola.plugins.command.check module
      - 1.1.1.2.1.1.4. nikola.plugins.command.console module
      - 1.1.1.2.1.1.5. nikola.plugins.command.default_config module
      - 1.1.1.2.1.1.6. nikola.plugins.command.deploy module
      - 1.1.1.2.1.1.7. nikola.plugins.command.github_deploy module
      - 1.1.1.2.1.1.8. nikola.plugins.command.import_wordpress module
      - 1.1.1.2.1.1.9. nikola.plugins.command.init module
      - 1.1.1.2.1.1.10. nikola.plugins.command.new_page module
      - 1.1.1.2.1.1.11. nikola.plugins.command.new_post module
      - 1.1.1.2.1.1.12. nikola.plugins.command.orphans module
      - 1.1.1.2.1.1.13. nikola.plugins.command.plugin module
      - 1.1.1.2.1.1.14. nikola.plugins.command.serve module
      - 1.1.1.2.1.1.15. nikola.plugins.command.status module
      - 1.1.1.2.1.1.16. nikola.plugins.command.subtheme module
      - 1.1.1.2.1.1.17. nikola.plugins.command.theme module
      - 1.1.1.2.1.1.18. nikola.plugins.command.version module
    - 1.1.1.2.1.2. nikola.plugins.compile package
      - 1.1.1.2.1.2.1. Subpackages
      - 1.1.1.2.1.2.2. Submodules
      - 1.1.1.2.1.2.3. nikola.plugins.compile.html module
      - 1.1.1.2.1.2.4. nikola.plugins.compile.ipynb module
      - 1.1.1.2.1.2.5. nikola.plugins.compile.pandoc module
      - 1.1.1.2.1.2.6. nikola.plugins.compile.php module
    - 1.1.1.2.1.3. nikola.plugins.misc package
      - 1.1.1.2.1.3.1. Submodules
      - 1.1.1.2.1.3.2. nikola.plugins.misc.scan_posts module
      - 1.1.1.2.1.3.3. nikola.plugins.misc.taxonomies_classifier module
    - 1.1.1.2.1.4. nikola.plugins.task package
      - 1.1.1.2.1.4.1. Submodules
      - 1.1.1.2.1.4.2. nikola.plugins.task.archive module
      - 1.1.1.2.1.4.3. nikola.plugins.task.authors module
      - 1.1.1.2.1.4.4. nikola.plugins.task.bundles module
      - 1.1.1.2.1.4.5. nikola.plugins.task.categories module
      - 1.1.1.2.1.4.6. nikola.plugins.task.copy_assets module
      - 1.1.1.2.1.4.7. nikola.plugins.task.copy_files module
      - 1.1.1.2.1.4.8. nikola.plugins.task.galleries module
      - 1.1.1.2.1.4.9. nikola.plugins.task.gzip module
      - 1.1.1.2.1.4.10. nikola.plugins.task.indexes module
      - 1.1.1.2.1.4.11. nikola.plugins.task.listings module
      - 1.1.1.2.1.4.12. nikola.plugins.task.page_index module
      - 1.1.1.2.1.4.13. nikola.plugins.task.pages module
      - 1.1.1.2.1.4.14. nikola.plugins.task.posts module
      - 1.1.1.2.1.4.15. nikola.plugins.task.redirect module
      - 1.1.1.2.1.4.16. nikola.plugins.task.robots module
      - 1.1.1.2.1.4.17. nikola.plugins.task.scale_images module
      - 1.1.1.2.1.4.18. nikola.plugins.task.sitemap module
      - 1.1.1.2.1.4.19. nikola.plugins.task.sources module
      - 1.1.1.2.1.4.20. nikola.plugins.task.tags module
      - 1.1.1.2.1.4.21. nikola.plugins.task.taxonomies module
    - 1.1.1.2.1.5. nikola.plugins.template package
      - 1.1.1.2.1.5.1. Submodules
      - 1.1.1.2.1.5.2. nikola.plugins.template.jinja module
      - 1.1.1.2.1.5.3. nikola.plugins.template.mako module
  - 1.1.1.2.2. Submodules
  - 1.1.1.2.3. nikola.plugins.basic_import module

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

nikola.filters.add_header_permalinks(fname, xpath_list=None, file_blacklist=None)

  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://cssminifier.com/.

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

nikola.filters.jsminify(data)

  Minify JS using https://javascript-minifier.com/.

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: :class:`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: :class:`object`

  Apply image operations.

  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']
  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) → logging.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: :class:`enum.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: :class:`enum.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: :class:`enum.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: :class:`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
  abs_link(dst, protocol_relative=False)

    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)

    Load plugins as needed.

  link(*args, **kwargs)

    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.

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

  rel_link(src, dst)

    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.

  rewrite_links(doc, src, lang, url_type=None)

    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

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

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

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

  name = 'dummy_latetask'

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_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) -> (<class 'str'>, <class '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: :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 = {'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: nikola.post.Post, lang: str) → str

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

  get_extra_targets(post: nikola.post.Post, lang: str, dest: str) → typing.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: nikola.post.Post, lang=None) → typing.Dict[str, str]

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

  register_extra_dependencies(post: nikola.post.Post)

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

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

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

  scan() → typing.List[nikola.post.Post]

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

  supported_extensions() → Optional[List]

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

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

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

  Signal handlers.

  name = 'dummy_signal_handler'

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

  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: nikola.post.Post, lang: str) → typing.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: typing.List[nikola.post.Post], flat_hierarchy_per_lang=None, hierarchy_lookup_per_lang=None) → typing.List[nikola.post.Post]

    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]

    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: typing.List[nikola.post.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: typing.List[nikola.post.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: typing.List[nikola.post.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: typing.List[nikola.post.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: :class:`nikola.plugin_categories.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])

    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)

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

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

    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.

  permalink(lang=None, absolute=False, extension='.html', query=None)

    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.

  source_link(lang=None)

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

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

    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: :class:`json.encoder.JSONEncoder`

  Custom JSON encoder.

  default(obj)

    Create default encoding handler.

class nikola.utils.Functionary(default, default_lang)

  Bases: :class:`collections.defaultdict`

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

class nikola.utils.LocaleBorg

  Bases: :class:`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: datetime.date, lang: Optional[str] = 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: Union[datetime.date, datetime.datetime], lang: Optional[str] = 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: :class:`nikola.packages.pygments_better_html.BetterHtmlFormatter`

  A Nikola-specific modification of Pygments’ HtmlFormatter.

  wrap(source, outfile)

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

class nikola.utils.TemplateHookRegistry(name, site)

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

  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: :class:`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.utils.adjust_name_for_index_link(name, i, displayed_i, lang, site, force_addition=False, extension=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: :class:`doit.tools.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)

  Get name of parent theme.

nikola.utils.get_theme_chain(theme, themes_dirs)

  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)

  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) → str

  Join string_or_iterable with join_char if it is iterable; otherwise converts 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)

  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_into_dir(filename, dirname)

  Check if a file is in directory.