diff --git a/CHANGES.txt b/CHANGES.txt index 7952f548e4..2b114d9c1b 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -13,6 +13,8 @@ Math support changes Features -------- +* Add a list of template variables to documentation (Issues #2328, + #2712) * Add ``{post_title}`` tag for Read More links (Issue #2709) * Include MathJax config only when needed (via Issue #2715) * Include KaTeX CSS automatically when needed (Issue #2715) diff --git a/docs/creating-a-theme.txt b/docs/creating-a-theme.txt index 8cd2a49ba3..4f2c3cc7de 100644 --- a/docs/creating-a-theme.txt +++ b/docs/creating-a-theme.txt @@ -17,6 +17,8 @@ create themes. Since I **suck** at designing websites, I asked for opinions on t and got some feedback. Since this is **Not So Hard™**, I will try to make time to port a few and see what happens. +If you are looking for a reference, check out `Theming reference `_ and `Template variables `_. + Today’s theme is `Lanyon `__ which is written by `@mdo `__ and released under a MIT license, which is liberal enough. diff --git a/docs/template-variables.rst b/docs/template-variables.rst new file mode 100644 index 0000000000..50c9fba314 --- /dev/null +++ b/docs/template-variables.rst @@ -0,0 +1,393 @@ +.. title: Template variables +.. slug: template-variables +.. date: 2017-04-13 12:00:00 +.. author: The Nikola Team + +:Version: 7.8.4 +:Author: Chris Warrick + +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. + +Variables and functions come from three places: + +* the global context +* the local context of a page +* the templates themselves and the templates they import + +.. class:: alert alert-info +.. contents:: + +Global variables +---------------- + +Some variables on the global variables list may be None (the ``?`` symbol is not used). + +.. class:: table table-bordered table-striped + +================================== ================================== ================================================================================ +Name Type Description +================================== ================================== ================================================================================ +``_link`` function ``Nikola.link`` function +``abs_link`` function ``Nikola.abs_link`` function +``annotations`` bool ``ANNOTATIONS`` setting +``author_pages_generated`` bool False +``blog_author`` TranslatableSetting ``BLOG_AUTHOR`` setting +``blog_description`` TranslatableSetting ``BLOG_DESCRIPTION`` setting +``blog_title`` TranslatableSetting ``BLOG_TITLE`` setting +``blog_url`` str ``SITE_URL`` setting +``body_end`` TranslatableSetting ``BODY_END`` setting +``colorbox_locales`` defaultdict dictionary of avilable Colorbox locales +``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 ``CONTENT_FOOTER`` setting +``data`` dict data files (from the ``data/`` directory) +``date_fanciness`` int ``DATE_FANCINESS`` setting +``date_format`` TranslatableSetting ``DATE_FORMAT`` setting +``exists`` function ``Nikola.file_exists`` function +``extra_head_data`` TranslatableSetting ``EXTRA_HEAD_DATA`` setting +``favicons`` tuple ``FAVICONS`` setting +``front_index_header`` TranslatableSetting ``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 ``HIDDEN_AUTHORS`` setting +``hidden_categories`` list ``HIDDEN_CATEGORIES`` setting +``hidden_tags`` list ``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 ``JS_DATE_FORMAT`` setting +``katex_auto_render`` str ``KATEX_AUTO_RENDER`` setting +``license`` TranslatableSetting ``LICENSE`` setting +``logo_url`` str ``LOGO_URL`` setting +``mathjax_config`` str ``MATHJAX_CONFIG`` setting +``messages`` dict> translated messages (``{language: {english: translated}}``) +``meta_generator_tag`` bool ``META_GENERATOR_TAG`` setting +``momentjs_locales`` defaultdict dictionary of avilable Moment.js locales +``navigation_links`` TranslatableSetting ``NAVIGATION_LINKS`` setting +``needs_ipython_css`` bool whether or not IPython CSS is needed by this site +``posts_sections`` bool ``POSTS_SECTIONS`` setting +``posts_section_are_indexes`` bool ``POSTS_SECTION_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 ``POSTS_SECTION_NAME`` setting +``posts_section_title`` TranslatableSetting ``POSTS_SECTION_TITLE`` setting +``rel_link`` function ``Nikola.rel_link`` function +``rss_link`` str ``RSS_LINK`` setting +``rss_path`` TranslatableSetting ``RSS_PATH`` setting +``search_form`` TranslatableSetting ``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 +``SLUG_AUTHOR_PATH`` bool ``SLUG_AUTHOR_PATH`` setting +``SLUG_TAG_PATH`` bool ``SLUG_TAG_PATH`` setting +``social_buttons_code`` TranslatableSetting ``SOCIAL_BUTTONS_CODE`` setting +``sort_posts`` function ``utils.sort_posts`` function +``subtheme`` str ``THEME_REVEAL_CONFIG_SUBTHEME`` setting +``template_hooks`` dict Template hooks registered by plugins +``theme_color`` str ``THEME_COLOR`` setting +``timezone`` tzinfo Timezone object (represents the configured timezone) +``transition`` str ``THEME_REVEAL_CONFIG_TRANSITION`` setting +``translations`` dict ``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_base_tag`` bool ``USE_BASE_TAG`` setting +``use_bundles`` bool ``USE_BUNDLES`` setting +``use_cdn`` bool ``USE_CDN`` setting +``use_katex`` bool ``USE_KATEX`` setting +``use_open_graph`` bool ``USE_OPEN_GRAPH`` setting, defaults to True +================================== ================================== ================================================================================ + +Per-page local variables +------------------------ + +Those variables are available on all pages, but their contents are dependent on page contents. + +.. class:: table table-bordered table-striped + +================== ========== =============================================================== +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 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) +================== ========== =============================================================== + +__ https://getnikola.com/theming.html#identifying-and-customizing-different-kinds-of-pages-with-a-shared-template + +Variables available in post pages (``post.tmpl``, ``story.tmpl`` etc.) +---------------------------------------------------------------------- + +.. class:: table table-bordered table-striped + +====================== ========== ======================================================== +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 +--------------------------------- + +.. class:: table table-bordered table-striped + +============== ============= ============================================== +Name Type Description +============== ============= ============================================== +``posts`` list 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 +------------------------------ + +.. class:: table table-bordered table-striped + +============================== ============== =============================================================================== +Name Type Description +============================== ============== =============================================================================== +``posts`` list 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 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``) +============================== ============== =============================================================================== + +Variables available in taxonomies +--------------------------------- + +Variable names enclosed in ``<>`` are dependent on the taxonomy. + +.. class:: table table-bordered table-striped + +============== ========================================== =================== +Taxonomy Variable Value +============== ========================================== =================== +``archive`` ``overview_page_variable_name`` ``archive`` +``authors`` ``overview_page_variable_name`` ``authors`` +``categories`` ``overview_page_variable_name`` ``categories`` +``categories`` ``overview_page_items_variable_name`` ``cat_items`` +``categories`` ``overview_page_hierarchy_variable_name`` ``cat_hierarchy`` +``indexes`` ``overview_page_variable_name`` unavailable (None) +``page_index`` ``overview_page_variable_name`` ``page_folder`` +``sections`` ``overview_page_variable_name`` ``sections`` +``tags`` ``overview_page_variable_name`` ``tags`` +``tags`` ``overview_page_items_variable_name`` ``items`` +============== ========================================== =================== + +Classification overviews +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: table table-bordered table-striped + +================================================================== ====== ============================================ +Name Type Description +================================================================== ====== ============================================ +```` str List of classifications +```` str List of items **(name, link)** +```` str List of items **(name, link, count)** +```` str? List of hierarchies +```` str List of hierarchies, with added counts +``has_hierarchy`` bool Value of ``has_hierarchy`` for the taxonomy +``permalink`` str Permanent link to page +================================================================== ====== ============================================ + +Classification pages (lists) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: table table-bordered table-striped + +============== ============== =========================================================== +Name Type Description +============== ============== =========================================================== +``items`` list? List of items for ``list.tmpl`` *(title, permalink, None)* +``posts`` list? List of items for other templates +``kind`` str The classification name +``permalink`` str Permanent link to page +============== ============== =========================================================== + +Subclassification page +~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: table table-bordered table-striped + +============== ====== ======================= +Name Type Description +============== ====== ======================= +``items`` list? List of items +``permalink`` str Permanent link to page +============== ====== ======================= + +Variables available in archives +------------------------------- + +The archive navigation variables are available only if ``create_archive_navigation`` is True. + +.. class:: table table-bordered table-striped + +============================== ============== =============================================== +Name Type Description +============================== ============== =============================================== +``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 +============================== ============== =============================================== + + +Variables available in author pages +----------------------------------- + +.. class:: table table-bordered table-striped + +============== ====== ============================ +Name Type Description +============== ====== ============================ +``author`` str Author name +``rss_link`` str Link to RSS (HTML fragment) +============== ====== ============================ + + +Variables available in category pages +------------------------------------- + +.. class:: table table-bordered table-striped + +================== ========== ===================================================== +Name Type Description +================== ========== ===================================================== +``kind`` str Always ``"category"`` +``category`` str Category name +``category_path`` list 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 +================== ========== ===================================================== + +Variables available in galleries +-------------------------------- + +.. class:: table table-bordered table-striped + +====================== ========== =============================================================================== +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 +------------------------------- + +.. class:: table table-bordered table-striped + +================== ========== ======================================== +Name Type Description +================== ========== ======================================== +``code`` str Highlighted source code (HTML fragment) +``crumbs`` list Breadcrumbs for this page +``folders`` list List of subfolders +``files`` list List of files in the folder +``source_link`` str Link to the source file +================== ========== ======================================== + +Variables available in tag pages +-------------------------------- + +.. class:: table table-bordered table-striped + +========= ===== ================= +Name Type Description +========= ===== ================= +``kind`` str Always ``"tag"`` +``tag`` str Tag name +========= ===== ================= + +Variables available in the “Tags and categories” page (``tags.tmpl``) +--------------------------------------------------------------------- + +.. class:: table table-bordered table-striped + +============== ====== =========================================================================================================== +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)* +============== ====== =========================================================================================================== + +Variables available in shortcodes +--------------------------------- + +*The global context is available in shortcodes.* + +.. class:: table table-bordered table-striped + +================== ========== ==================================================== +Name Type Description +================== ========== ==================================================== +``lang`` str Current language +``_args`` list Arguments given to the shortcode +``data`` str Shortcode contents +``post`` Post Post object (if available) +================== ========== ==================================================== + +Variables available in post lists +--------------------------------- + +*The global context is not available in post lists.* + +.. class:: table table-bordered table-striped + +================== ========== ===================================== +Name Type Description +================== ========== ===================================== +``posts`` list 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 +================== ========== ===================================== + +.. vim: nowrap textwidth=0 diff --git a/docs/theming.txt b/docs/theming.txt index 658bb4866b..37a4b1bd99 100644 --- a/docs/theming.txt +++ b/docs/theming.txt @@ -19,7 +19,7 @@ Theming Nikola .. class:: lead This document is a reference about themes. If you want a tutorial, please read -`Creating a Theme `_ +`Creating a Theme `_. The Structure ------------- @@ -158,7 +158,7 @@ These are the templates that come with the included themes: + ``title``: The title of the image. + ``size``: A dict containing ``w`` and ``h``, the real size of the thumbnail. - * ``photo_array_json``: a JSON dump of photo_array, used in the bootstrap theme by flowr.js + * ``photo_array_json``: a JSON dump of photo_array, used in the bootstrap theme by flowr.js ``list.tmpl`` Template used to display generic lists of links, which it gets in ``items``, @@ -200,6 +200,12 @@ require whatever data you want. Also, you can specify a custom template to be used by a post or page via the ``template`` metadata, and custom templates can be added in the ``templates/`` folder of your site. +Variables available in templates +-------------------------------- + +The list of variables available in templates is maintained in a separate +document: `Template variables `_ + Customizing themes to user color preference and section colors --------------------------------------------------------------