New upstream version 8.2.3.upstream/8.2.3

1 files changed, 40 insertions, 16 deletions

diff --git a/docs/theming.rst b/docs/theming.rst
index 957e68e..ff10d28 100644
--- a/docs/theming.rst
+++ b/docs/theming.rst
@@ -6,7 +6,7 @@
 .. description:
 .. author: The Nikola Team
 
-:Version: 8.2.0
+:Version: 8.2.3
 :Author: Roberto Alsina <ralsina@netmanagers.com.ar>
 
 .. class:: alert alert-primary float-md-right
@@ -284,10 +284,6 @@ These are the templates that come with the included themes:
 ``post_list_directive.tmpl``
     Template used by the ``post_list`` reStructuredText directive.
 
-``sectionindex.tmpl``
-    Used to display section indexes, if ``POST_SECTIONS_ARE_INDEXES`` is True.
-    By default, it just inherits ``index.tmpl``, with added feeds.
-
 ``page.tmpl``
     Used for pages that are not part of a blog, usually a cleaner, less
     intrusive layout than ``post.tmpl``, but same parameters.
@@ -309,20 +305,50 @@ Variables available in templates
 The full, complete list of variables available in templates is maintained in a separate
 document: `Template variables <https://getnikola.com/template-variables.html>`_
 
-Customizing themes to user color preference and section colors
---------------------------------------------------------------
+Customizing themes to user color preference, colorizing category names
+----------------------------------------------------------------------
 
 The user’s preference for theme color is exposed in templates as
 ``theme_color`` set in the ``THEME_COLOR`` option.
 
-Each section has an assigned color that is either set by the user or auto
-selected by adjusting the hue of the user’s ``THEME_COLOR``. The color is
-exposed in templates through ``post.section_color(lang)``. The function that
-generates the colors from strings and any given color (by section name and
-theme color for sections) is exposed through the
-``colorize_str_from_base_color(string, hex_color)`` function
+This theme color is exposed to the browser in default themes — some browsers
+might use this color in the user interface (eg. Chrome on Android in light mode
+displays the toolbar in this color).
+
+Nikola also comes with support for auto-generating colors similar to a base
+color. This can be used with ``theme_color`` and eg. category names. This
+feature is exposed to templates as two functions: ``colorize_str(string,
+hex_color, presets)`` and  ``colorize_str_from_base_color(string, hex_color)``.
+If you want to display the category name in the color, first define a list of
+overrides in your ``conf.py`` file:
+
+.. code:: python
+
+    # end of conf.py
+    GLOBAL_CONTEXT = {
+        "category_colors": {
+            "Blue": "#0000FF"
+        }
+    }
+
+With that definition, you can now use ``colorize_str`` in your templates like this:
+
+.. code:: html+mako
+
+    <!-- Mako -->
+    <span style="background-color: ${colorize_str(post.meta('category'), theme_color, category_colors)}">${post.meta('category')}</span>
+
+.. code:: html+jinja
+
+    <!-- Jinja2 -->
+    <span style="background-color: {{ colorize_str(post.meta('category'), theme_color, category_colors) }}">{{ post.meta('category') }}</span>
+
+Note that the category named “Blue” will be displyed in #0000FF due to the
+override specified in your config; other categories will have an auto-generated
+color visually similar to your theme color.
+
 
-Hex color values, like that returned by the theme or section color can be
+Hex color values, like that returned by the theme or string colorization can be
 altered in the HSL colorspace through the function
 ``color_hsl_adjust_hex(hex_string, adjust_h, adjust_s, adjust_l)``.
 Adjustments are given in values between 1.0 and -1.0. For example, the theme
@@ -427,12 +453,10 @@ List of page kinds provided by default plugins:
 * index, archive_page
 * index, author_page
 * index, main_index
-* index, section_page
 * index, tag_page
 * list
 * list, archive_page
 * list, author_page
-* list, section_page
 * list, tag_page
 * list, tags_page
 * post_page