Permalink
Browse files

Apply fixes to taxonomy variable documentation

h/t @felixfontein

Signed-off-by: Chris Warrick <kwpolska@gmail.com>
  • Loading branch information...
Kwpolska committed Apr 14, 2017
1 parent 04d8c2f commit a868ef4f3d9ece66e03685fa3e5eb3cfa1c4420f
Showing with 68 additions and 23 deletions.
  1. +66 −21 docs/template-variables.rst
  2. +2 −2 nikola/plugin_categories.py
@@ -189,37 +189,57 @@ 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``
-============== ========================================== ===================
+====================== ========================================== ===================
+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``
+====================== ========================================== ===================
+
+Templates and settings used by taxonomies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: table table-bordered table-striped
+
+====================== ================== ================================== ====================================== ============================================== ====================================== ============================== ==============================
+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
+====================== ================== ================================== ====================================== ============================================== ====================================== ============================== ==============================
Classification overviews
~~~~~~~~~~~~~~~~~~~~~~~~
+Hierarchy-related variables are available if and only if ``has_hierarchy`` is True.
+
.. class:: table table-bordered table-striped
-================================================================== ====== ============================================
+================================================================== ====== ==============================================================================================================================================================================
Name Type Description
-================================================================== ====== ============================================
+================================================================== ====== ==============================================================================================================================================================================
``<overview_page_variable_name>`` str List of classifications
-``<overview_page_items_variable_name>`` str List of items **(name, link)**
-``<overview_page_items_variable_name + "_with_postcount">`` str List of items **(name, link, count)**
-``<overview_page_hierarchy_variable_name>`` str? List of hierarchies
-``<overview_page_hierarchy_variable_name + "_with_postcount">`` str List of hierarchies, with added counts
+``<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)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -247,6 +267,29 @@ Name Type Description
``permalink`` str Permanent link to page
============== ====== =======================
+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:
+
+.. code:: text
+
+ +--- 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
-------------------------------
@@ -357,6 +400,8 @@ Name Type Description
``cat_items`` list Categories *(name, full name, path, link, indent levels, indent to change before, indent to change after)*
============== ====== ===========================================================================================================
+For more details about hierarchies, see `Hierarchical lists`_
+
Variables available in shortcodes
---------------------------------
@@ -560,7 +560,7 @@ class Taxonomy(BasePlugin):
Whether to show the posts for one classification as an index or
as a post list.
- subcategories_list_template = "taxonomy_list":
+ subcategories_list_template = "taxonomy_list.tmpl":
The template to use for the subcategories list when
show_list_as_subcategories_list is True.
@@ -617,7 +617,7 @@ class Taxonomy(BasePlugin):
include_posts_into_hierarchy_root = False
show_list_as_subcategories_list = False
show_list_as_index = False
- subcategories_list_template = "taxonomy_list"
+ subcategories_list_template = "taxonomy_list.tmpl"
generate_atom_feeds_for_post_lists = False
template_for_single_list = "tagindex.tmpl"
template_for_classification_overview = "list.tmpl"

0 comments on commit a868ef4

Please sign in to comment.