6. Template variables — Nikola 8.1.3 documentation

# 6. Template variables

Version

  8.1.3

Author

  Chris Warrick <chris@getnikola.com>

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

Contents

- Template variables

  - Global variables

  - Per-page local variables

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

  - Variables available in post lists

  - Variables available in indexes

  - Variables available in taxonomies

    - Templates and settings used by taxonomies

    - Classification overviews

    - Classification pages (lists)

    - Subclassification page

    - Hierarchical lists

  - Variables available in archives

  - Variables available in author pages

  - Variables available in category pages

  - Variables available in galleries

  - Variables available in listings

  - Variables available in sections

  - Variables available in tag pages

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

  - Variables available in shortcodes

  - Variables available in post lists

  - Post object attributes

## 6.1. 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
`posts_sections` | bool | `POSTS_SECTIONS` setting
`posts_section_are_indexes` | bool | `POSTS_SECTIONS_ARE_INDEXES` setting
`posts_sections_are_indexes` | bool | `POSTS_SECTIONS_ARE_INDEXES` setting
`posts_section_colors` | TranslatableSetting | `POSTS_SECTION_COLORS` setting
`posts_section_descriptions` | Tss | `POSTS_SECTION_DESCRIPTIONS` setting
`posts_section_from_meta` | bool | `POSTS_SECTION_FROM_META` setting
`posts_section_name` | TranslatableSetting[str] | `POSTS_SECTION_NAME` setting
`posts_section_title` | TranslatableSetting[str] | `POSTS_SECTION_TITLE` setting
`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)

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

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

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

## 6.5. 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)

## 6.6. 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`
`section_index` | `overview_page_variable_name` | `sections`
`tag` | `overview_page_variable_name` | `tags`
`tag` | `overview_page_items_variable_name` | `items`

### 6.6.1. 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
`section_index` | no | list.tmpl | sectionindex.tmpl | n/a | n/a | `POSTS_SECTIONS_ARE_INDEXES` | no
`tag` | no | tag.tmpl | tagindex.tmpl | tags.tmpl (with categories) | n/a | `TAG_PAGES_ARE_INDEXES` | no

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

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

### 6.6.4. 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)`

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

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

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

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

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

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

## 6.12. Variables available in sections

Name | Type | Description
--- | --- | ---
`section` | str | Section name (internal)
`kind` | str | Always `"section"`
`other_languages` | list[tuple] | List of tuples `(lang, section, name)` of same section in other languages

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

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

## 6.15. 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`

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

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