Skip to content

Commit a868ef4

Browse files
committedApr 14, 2017
Apply fixes to taxonomy variable documentation
h/t @felixfontein Signed-off-by: Chris Warrick <kwpolska@gmail.com>
1 parent 04d8c2f commit a868ef4

File tree

2 files changed

+68
-23
lines changed

2 files changed

+68
-23
lines changed
 

‎docs/template-variables.rst

+66-21
Original file line numberDiff line numberDiff line change
@@ -189,37 +189,57 @@ Variable names enclosed in ``<>`` are dependent on the taxonomy.
189189

190190
.. class:: table table-bordered table-striped
191191

192-
============== ========================================== ===================
193-
Taxonomy Variable Value
194-
============== ========================================== ===================
195-
``archive`` ``overview_page_variable_name`` ``archive``
196-
``authors`` ``overview_page_variable_name`` ``authors``
197-
``categories`` ``overview_page_variable_name`` ``categories``
198-
``categories`` ``overview_page_items_variable_name`` ``cat_items``
199-
``categories`` ``overview_page_hierarchy_variable_name`` ``cat_hierarchy``
200-
``indexes`` ``overview_page_variable_name`` unavailable (None)
201-
``page_index`` ``overview_page_variable_name`` ``page_folder``
202-
``sections`` ``overview_page_variable_name`` ``sections``
203-
``tags`` ``overview_page_variable_name`` ``tags``
204-
``tags`` ``overview_page_items_variable_name`` ``items``
205-
============== ========================================== ===================
192+
====================== ========================================== ===================
193+
Taxonomy Variable Value
194+
====================== ========================================== ===================
195+
``archive`` ``overview_page_variable_name`` ``archive``
196+
``author`` ``overview_page_variable_name`` ``authors``
197+
``category`` ``overview_page_variable_name`` ``categories``
198+
``category`` ``overview_page_items_variable_name`` ``cat_items``
199+
``category`` ``overview_page_hierarchy_variable_name`` ``cat_hierarchy``
200+
``index`` ``overview_page_variable_name`` unavailable (None)
201+
``page_index_folder`` ``overview_page_variable_name`` ``page_folder``
202+
``section_index`` ``overview_page_variable_name`` ``sections``
203+
``tag`` ``overview_page_variable_name`` ``tags``
204+
``tag`` ``overview_page_items_variable_name`` ``items``
205+
====================== ========================================== ===================
206+
207+
Templates and settings used by taxonomies
208+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
209+
210+
.. class:: table table-bordered table-striped
211+
212+
====================== ================== ================================== ====================================== ============================================== ====================================== ============================== ==============================
213+
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
214+
====================== ================== ================================== ====================================== ============================================== ====================================== ============================== ==============================
215+
(default settings) no tagindex.tmpl tagindex.tmpl list.tmpl taxonomy_list.tmpl (does not exist) no no
216+
``archive`` yes (0-3 levels) list_post.tmpl archiveindex.tmpl list.tmpl list.tmpl ``ARCHIVES_ARE_INDEXES`` ``not CREATE_FULL_ARCHIVES``
217+
``author`` no author.tmpl authorindex.tmpl authors.tmpl n/a ``AUTHOR_PAGES_ARE_INDEXES`` no
218+
``category`` yes tag.tmpl tagindex.tmpl tags.tmpl (with tags) n/a ``CATEGORY_PAGES_ARE_INDEXES`` n/a
219+
``index`` no n/a index.tmpl n/a n/a yes no
220+
``page_index_folder`` yes list.tmpl n/a n/a n/a no no
221+
``section_index`` no list.tmpl sectionindex.tmpl n/a n/a ``POSTS_SECTIONS_ARE_INDEXES`` no
222+
``tag`` no tag.tmpl tagindex.tmpl tags.tmpl (with categories) n/a ``TAG_PAGES_ARE_INDEXES`` no
223+
====================== ================== ================================== ====================================== ============================================== ====================================== ============================== ==============================
206224

207225
Classification overviews
208226
~~~~~~~~~~~~~~~~~~~~~~~~
209227

228+
Hierarchy-related variables are available if and only if ``has_hierarchy`` is True.
229+
210230
.. class:: table table-bordered table-striped
211231

212-
================================================================== ====== ============================================
232+
================================================================== ====== ==============================================================================================================================================================================
213233
Name Type Description
214-
================================================================== ====== ============================================
234+
================================================================== ====== ==============================================================================================================================================================================
215235
``<overview_page_variable_name>`` str List of classifications
216-
``<overview_page_items_variable_name>`` str List of items **(name, link)**
217-
``<overview_page_items_variable_name + "_with_postcount">`` str List of items **(name, link, count)**
218-
``<overview_page_hierarchy_variable_name>`` str? List of hierarchies
219-
``<overview_page_hierarchy_variable_name + "_with_postcount">`` str List of hierarchies, with added counts
236+
``<overview_page_items_variable_name>`` list List of items **(name, link)**
237+
``<overview_page_items_variable_name + "_with_postcount">`` list List of items **(name, link, number of posts)**
238+
``<overview_page_hierarchy_variable_name>`` list? List of hierarchies **(name, full name, path, link, indent levels, indent to change before, indent to change after)**
239+
``<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)**
220240
``has_hierarchy`` bool Value of ``has_hierarchy`` for the taxonomy
221241
``permalink`` str Permanent link to page
222-
================================================================== ====== ============================================
242+
================================================================== ====== ==============================================================================================================================================================================
223243

224244
Classification pages (lists)
225245
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -247,6 +267,29 @@ Name Type Description
247267
``permalink`` str Permanent link to page
248268
============== ====== =======================
249269

270+
Hierarchical lists
271+
~~~~~~~~~~~~~~~~~~
272+
273+
The indenting information can be used to render the items as a tree. The values have the following meanings:
274+
275+
* ``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``;
276+
* ``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;
277+
* ``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.
278+
279+
Example:
280+
281+
.. code:: text
282+
283+
+--- levels:[(0,3)], before:1, after:0
284+
+-+- levels:[(1,3)], before:0, after:1
285+
| +--- levels:[(1,3), (0,2)], before:1, after:0
286+
| +-+- levels:[(1,3), (1,2)], before:0, after:1
287+
| +--- levels:[(1,3), (1,2), (0, 1)], before:1, after:-2
288+
+-+- levels:[(2,3)], before:-2, after:1
289+
+- levels:[(2,3), (0,1)], before:1, after:-2
290+
291+
See ``tags.tmpl`` in the base themes for examples on how to render a tree as nested unordered lists in HTML.
292+
250293
Variables available in archives
251294
-------------------------------
252295

@@ -357,6 +400,8 @@ Name Type Description
357400
``cat_items`` list Categories *(name, full name, path, link, indent levels, indent to change before, indent to change after)*
358401
============== ====== ===========================================================================================================
359402

403+
For more details about hierarchies, see `Hierarchical lists`_
404+
360405
Variables available in shortcodes
361406
---------------------------------
362407

‎nikola/plugin_categories.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -560,7 +560,7 @@ class Taxonomy(BasePlugin):
560560
Whether to show the posts for one classification as an index or
561561
as a post list.
562562
563-
subcategories_list_template = "taxonomy_list":
563+
subcategories_list_template = "taxonomy_list.tmpl":
564564
The template to use for the subcategories list when
565565
show_list_as_subcategories_list is True.
566566
@@ -617,7 +617,7 @@ class Taxonomy(BasePlugin):
617617
include_posts_into_hierarchy_root = False
618618
show_list_as_subcategories_list = False
619619
show_list_as_index = False
620-
subcategories_list_template = "taxonomy_list"
620+
subcategories_list_template = "taxonomy_list.tmpl"
621621
generate_atom_feeds_for_post_lists = False
622622
template_for_single_list = "tagindex.tmpl"
623623
template_for_classification_overview = "list.tmpl"

0 commit comments

Comments
 (0)
Please sign in to comment.