Template variables

Version:
8.3.1
Author:

Chris Warrick <[email protected]>

Variables available in templates are listed below.

  • This list is maintained by humans, so it may not always be perfect.

  • Variables whose types are marked with ? may not always be available or may be None in some cases.

  • Templates usually do not have access to the original TranslatableSetting variables, only to the current locale version (except NAVIGATION_LINKS).

  • For function and setting documentation, please consult code documentation and default configuration respectively.

  • Templates often create their own functions (macros), and import macros from other templates. Those macros are not listed here.

  • This list has a partial documentation of post objects, but no other objects. For full docs, please consult the code, or auto-generated code docs on ReadTheDocs.

Variables and functions come from three places:

  • the global context

  • the local context of a page

  • the templates themselves and the templates they import

Global variables

Some variables on the global variables list may be None (the ? symbol is not used).

Name

Type

Description

_link

function

Nikola.link function

abs_link

function

Nikola.abs_link function

atom_path

TranslatableSetting[str]

ATOM_PATH setting

author_pages_generated

bool

False

blog_author

TranslatableSetting[str]

BLOG_AUTHOR setting

blog_email

str

BLOG_EMAIL setting

blog_description

TranslatableSetting[str]

BLOG_DESCRIPTION setting

blog_title

TranslatableSetting[str]

BLOG_TITLE setting

blog_url

str

SITE_URL setting

body_end

TranslatableSetting[str]

BODY_END setting

colorize_str_from_base_color

function

utils.colorize_str_from_base_color function

color_hsl_adjust_hex

function

utils.color_hsl_adjust_hex function

comment_system_id

str

COMMENT_SYSTEM_ID setting

comment_system

str

COMMENT_SYSTEM setting

content_footer

TranslatableSetting[str]

CONTENT_FOOTER setting

data

dict

data files (from the data/ directory)

date_fanciness

int

DATE_FANCINESS setting

date_format

TranslatableSetting[str]

DATE_FORMAT setting

exists

function

Nikola.file_exists function

extra_head_data

TranslatableSetting[str]

EXTRA_HEAD_DATA setting

favicons

tuple

FAVICONS setting

front_index_header

TranslatableSetting[str]

FRONT_INDEX_HEADER setting

generate_atom

bool

GENERATE_ATOM setting

generate_rss

bool

GENERATE_RSS setting

global_data

dict

alias for data

has_custom_css

bool

True if custom.css exists

hidden_authors

list[str]

HIDDEN_AUTHORS setting

hidden_categories

list[str]

HIDDEN_CATEGORIES setting

hidden_tags

list[str]

HIDDEN_TAGS setting

hide_sourcelink

bool

SHOW_SOURCELINK setting, negated

index_display_post_count

int

INDEX_DISPLAY_POST_COUNT setting

index_file

str

INDEX_FILE setting

js_date_format

TranslatableSetting[str]

MOMENTJS_DATE_FORMAT setting, JSONified

katex_auto_render

str

KATEX_AUTO_RENDER setting

license

TranslatableSetting[str]

LICENSE setting

logo_url

str

LOGO_URL setting

luxon_date_format

TranslatableSetting[str]

LUXON_DATE_FORMAT setting, JSONified

mathjax_config

str

MATHJAX_CONFIG setting

messages

dict[dict[str, str]]

translated messages ({language: {english: translated}})

meta_generator_tag

bool

META_GENERATOR_TAG setting

momentjs_locales

defaultdict[str, str]

dictionary of available Moment.js locales

multiple_authors_per_post

bool

MULTIPLE_AUTHORS_PER_POST setting

navigation_links

TranslatableSetting

NAVIGATION_LINKS setting

navigation_alt_links

TranslatableSetting

NAVIGATION_ALT_LINKS setting

needs_ipython_css

bool

whether or not Jupyter CSS is needed by this site

rel_link

function

Nikola.rel_link function

rss_link

str

RSS_LINK setting

search_form

TranslatableSetting[str]

SEARCH_FORM setting

set_locale

function

LocaleBorg.set_locale function (or None if not available)

show_blog_title

bool

SHOW_BLOG_TITLE setting

show_sourcelink

bool

SHOW_SOURCELINK setting

site_has_comments

bool

whether or not a comment system is configured

social_buttons_code

TranslatableSetting[str]

SOCIAL_BUTTONS_CODE setting

sort_posts

function

utils.sort_posts function

smartjoin

function

utils.smartjoin function

colorize_str

function

utils.colorize_str function

template_hooks

dict[str, TemplateHookRegistry]

Template hooks registered by plugins

theme_color

str

THEME_COLOR setting

theme_config

dict

THEME_CONFIG setting

timezone

tzinfo

Timezone object (represents the configured timezone)

translations

dict[str, str]

TRANSLATIONS setting

twitter_card

dict

TWITTER_CARD setting, defaults to an empty dictionary

url_replacer

function

Nikola.url_replacer function

url_type

str

URL_TYPE setting

use_bundles

bool

USE_BUNDLES setting

use_cdn

bool

USE_CDN setting

use_katex

bool

USE_KATEX setting

subtheme

str?

THEME_REVEAL_CONFIG_SUBTHEME setting (only if set — deprecated)

transition

str?

THEME_REVEAL_CONFIG_TRANSITION setting (only if set — deprecated)

Per-page local variables

Those variables are available on all pages, but their contents are dependent on page contents.

Name

Type

Description

description

str

Description of the page

is_rtl

bool

Whether or not the language is left-to-right

lang

str

Current language

pagekind

list[str]

List of strings that identify the type of this page (docs)

title

str

Title of the page (taken from post, config, etc.)

formatmsg

function

Wrapper over % string formatting

striphtml

function

Strips HTML tags (Mako only)

crumbs

list

Breadcrumbs for this page

Variables available in post pages (post.tmpl, page.tmpl etc.)

Name

Type

Description

post

Post

The post object

permalink

str

Permanent link to the post

enable_comments

bool

True for posts, COMMENTS_IN_PAGES setting for pages

Variables available in post lists

Name

Type

Description

posts

list[Post]

List of post objects that appear in this list

prevlink

str

Link to previous page

nextlink

str

Link to next page

Variables available in indexes

Name

Type

Description

posts

list[Post]

List of post objects that appear in this list

index_teasers

bool

INDEX_TEASERS setting

show_index_page_navigation

bool

SHOW_INDEX_PAGE_NAVIGATION setting

current_page

int

Number of current page

page_links

list[str]

Links to different pages

prevlink

str

Link to previous page

nextlink

str

Link to next page

prevfeedlink

str

Link to previous page as an Atom feed

nextfeedlink

str

Link to next page as an Atom feed

prev_next_links_reversed

bool

Whether or not previous and next links should be reversed (INDEXES_STATIC)

is_frontmost_index

bool

Whether or not this is the front-most index (page 0)

Variables available in taxonomies

Variable names enclosed in {} are dependent on the taxonomy.

Taxonomy

Variable

Value

archive

overview_page_variable_name

archive

author

overview_page_variable_name

authors

category

overview_page_variable_name

categories

category

overview_page_items_variable_name

cat_items

category

overview_page_hierarchy_variable_name

cat_hierarchy

index

overview_page_variable_name

unavailable (None)

page_index_folder

overview_page_variable_name

page_folder

tag

overview_page_variable_name

tags

tag

overview_page_items_variable_name

items

Templates and settings used by taxonomies

Taxonomy

Has hierarchy

List (one classification) template

Index (one classification) template

Overview (list of classifications) template

Subcategories list template

List is an index

Show as list of subcategories

(default settings)

no

tagindex.tmpl

tagindex.tmpl

list.tmpl

taxonomy_list.tmpl (does not exist)

no

no

archive

yes (0-3 levels)

list_post.tmpl

archiveindex.tmpl

list.tmpl

list.tmpl

ARCHIVES_ARE_INDEXES

not CREATE_FULL_ARCHIVES

author

no

author.tmpl

authorindex.tmpl

authors.tmpl

n/a

AUTHOR_PAGES_ARE_INDEXES

no

category

yes

tag.tmpl

tagindex.tmpl

tags.tmpl (with tags)

n/a

CATEGORY_PAGES_ARE_INDEXES

n/a

index

no

n/a

index.tmpl

n/a

n/a

yes

no

page_index_folder

yes

list.tmpl

n/a

n/a

n/a

no

no

tag

no

tag.tmpl

tagindex.tmpl

tags.tmpl (with categories)

n/a

TAG_PAGES_ARE_INDEXES

no

Classification overviews

Hierarchy-related variables are available if and only if has_hierarchy is True.

Name

Type

Description

{overview_page_variable_name}

str

List of classifications

{overview_page_items_variable_name}

list

List of items (name, link)

{overview_page_items_variable_name + "_with_postcount"}

list

List of items (name, link, number of posts)

{overview_page_hierarchy_variable_name}

list?

List of hierarchies (name, full name, path, link, indent levels, indent to change before, indent to change after)

{overview_page_hierarchy_variable_name + "_with_postcount"}

list?

List of hierarchies, with added counts (name, full name, path, link, indent levels, indent to change before, indent to change after, number of children, number of posts)

has_hierarchy

bool

Value of has_hierarchy for the taxonomy

permalink

str

Permanent link to page

Classification pages (lists)

Name

Type

Description

kind

str

The classification name

items

list?

List of items for list.tmpl (title, permalink, None)

posts

list[Post]?

List of items for other templates

permalink

str

Permanent link to page

other_languages

list[tuple]

List of triples (other_lang, other_classification, title)

Index-style classification pages have kind in addition to the usual index variables.

Subclassification page

Name

Type

Description

items

list?

List of items

permalink

str

Permanent link to page

other_languages

list[tuple]

List of triples (other_lang, other_classification, title)

Hierarchical lists

The indenting information can be used to render the items as a tree. The values have the following meanings:

  • indent levels is a list of pairs (current_i, count_i) giving the current position (0, ..., count_i-1) and maximum (count_i) in the hierarchy level i;

  • indent to change before is the difference of hierarchy levels between the previous and the current item; positive values indicate that the current item is indented further in and can be used to open HTML tags before the item;

  • indent to change after is the difference of hierarchy levels between the current and the next item; negative values indicate that the current item is indented further in and can be used to close HTML tags after the item.

Example:

+--- levels:[(0,3)], before:1, after:0
+-+- levels:[(1,3)], before:0, after:1
| +--- levels:[(1,3), (0,2)], before:1, after:0
| +-+- levels:[(1,3), (1,2)], before:0, after:1
|   +--- levels:[(1,3), (1,2), (0, 1)], before:1, after:-2
+-+- levels:[(2,3)], before:-2, after:1
  +- levels:[(2,3), (0,1)], before:1, after:-2

See tags.tmpl in the base themes for examples on how to render a tree as nested unordered lists in HTML.

Variables available in archives

The archive navigation variables are available only if create_archive_navigation is True.

Name

Type

Description

kind

str

Always "archive"

archive_name

str?

Name of the archive (only if using indexes)

create_archive_navigation

bool

CREATE_ARCHIVE_NAVIGATION setting

has_archive_navigation

bool

Whether or not archive navigation is available

up_archive

str?

Link to the archive one level up

up_archive_name

str?

Name of the archive one level up

previous_archive

str?

Link to the previous archive

previous_archive_name

str?

Name of the previous archive

next_archive

str?

Link to the next archive

next_archive_name

str?

Name of the next archive

archive_nodelevel

int?

Level of the archive

other_languages

list

List of tuples (lang, path, name) of same archive in other languages

Variables available in author pages

Name

Type

Description

kind

str

Always "author"

author

str

Author name

rss_link

str

Link to RSS (HTML fragment)

other_languages

list[tuple]

List of tuples (lang, author, name) of same author in other languages

Variables available in category pages

Name

Type

Description

kind

str

Always "category"

category

str

Category name

category_path

list[str]

Category hierarchy

rss_link

str?

Link to RSS (HTML fragment, only if using indexes)

subcategories

list

List of subcategories (contains name, link tuples)

tag

str

Friendly category name

other_languages

list[tuple]

List of tuples (lang, category, name) of same category in other languages

Variables available in galleries

Name

Type

Description

crumbs

list

Breadcrumbs for this page

enable_comments

bool

Whether or not comments are enabled in galleries

folders

list

List of folders (contains path, title tuples)

permalink

str

Permanent link to this page

photo_array

list

Photo array (contains dicts with image data: url, url_thumb, title, size{w, h})

photo_array_json

str

Photo array in JSON format

post

Post?

The Post object for this gallery

thumbnail_size

int

THUMBNAIL_SIZE setting

Variables available in listings

Name

Type

Description

code

str

Highlighted source code (HTML fragment)

crumbs

list

Breadcrumbs for this page

folders

list[str]

List of subfolders

files

list[str]

List of files in the folder

source_link

str

Link to the source file

Variables available in tag pages

Name

Type

Description

kind

str

Always "tag"

tag

str

Tag name

other_languages

list[tuple]

List of tuples (lang, tag, name) of same tag in other languages

Variables available in the “Tags and categories” page (tags.tmpl)

Name

Type

Description

items

list

Tags (name, link)

cat_items

list

Categories (name, full name, path, link, indent levels, indent to change before, indent to change after)

category_titles

dict

CATEGORY_TITLES setting (dict for the current language only)

category_descriptions

dict

CATEGORY_DESCRIPTIONS setting (dict for the current language only)

tag_titles

dict

TAG_TITLES setting (dict for the current language only)

tag_descriptions

dict

TAG_DESCRIPTIONS setting (dict for the current language only)

For more details about hierarchies, see Hierarchical lists

Variables available in shortcodes

The global context is available in templated shortcodes.

Name

Type

Description

lang

str

Current language

_args

list[str]

Arguments given to the shortcode

data

str

Shortcode contents

post

Post

Post object (if available)

filename

str?

file name, if shortcode_function.nikola_shortcode_pass_filename = True

Variables available in post lists

The global context is NOT available in post lists.

Name

Type

Description

posts

list[Post]

Posts that are on the list

lang

str

Current language

date_format

str

The date format for current language

post_list_id

str

GUID of post list

messages

dict

The messages dictionary

_link

function

Nikola.link function

Post object attributes

Usable anywhere post objects are accessible.

This list only includes variables that make sense for templates. Some function signatures have been shortened to save space, ? means the argument has default value.

More docs: nikola.post.Post on ReadTheDocs. Check out the source of the Post class as well.

Name

Type

Description

alltags

list[str]

All tags for the post

author(lang=None)

str

Localized author or BLOG_AUTHOR

base_path

str

cache path with local os.sep

category_from_destpath

bool

If category was set by CATEGORY_DESTPATH_AS_DEFAULT

data(key, lang=None)

?

Access to post data

date

datetime

Date of post (from meta)

description(key, lang=None)

str

Description of post (from meta)

destination_path(lang?, extension?, sep?)

str

Destination path of post

formatted_date(date_format, date=None)

str

Format a date (default: post date)

formatted_updated(date_format)

str

Format the last update date

guid(lang=None)

str

GUID of post (used for feeds)

has_math

bool

If the post has math

has_pretty_url(lang)

bool

If the post has a pretty URL

is_draft

bool

If the post is a draft

is_post

bool

If the post is not a page

is_private

bool

If the post is private

is_translation_available(lang)

bool

If the post is available in (translated to) a given language

is_two_file

bool

If the post uses two-file metadata

meta(key, lang=None)

?

Metadata of the post (assumes current language)

next_post

Post

Next post in the order

paragraph_count

int

Paragraph count for a post

permalink(lang?, absolute?, extension?, query?)

str

Permanent link for a post

post_name

str

Source path, without extension

post_status

str

Post status meta field (published, featured, private, draft)

prev_post

Post

Previous post in the order

previewimage

str

Preview image of the post

publish_later

bool

True if the post is not yet published (due to date)

reading_time

int

Approximate reading time in minutes (220 wpm)

remaining_paragraph_count

int

Paragraph count after the teaser

remaining_reading_time

int

Reading time after the teaser

source_link

str

Absolute link to the post's source

tags

list[str]

Tags for the current language

tags_for_language(lang)

list[str]

Tags for a given language

text(lang?, teaser_only?, strip_html?, show_read_more_link?, …)

str

The text of a post

title(lang=None)

str

Localized title of post

translated_to

list[str]

List of languages of post

updated

datetime

Date of last update (from meta)

use_in_feeds

bool

If this post should be displayed in feeds