Skip to content

Commit

Permalink
Remove section leftovers from theming.rst and template-variables.rst (f…
Browse files Browse the repository at this point in the history 
…ix #3596)
  • Loading branch information
@Kwpolska
Kwpolska committed Feb 5, 2022
1 parent 2da876e commit f07f2c9
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 38 deletions.
23 changes: 0 additions & 23 deletions docs/template-variables.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,14 +84,6 @@ Name Type Descript
``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
Expand Down Expand Up @@ -205,7 +197,6 @@ Taxonomy Variable Value
``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``
====================== ========================================== ===================
Expand All @@ -224,7 +215,6 @@ Taxonomy Has hierarchy List (one classification) template
``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
====================== ================== ================================== ====================================== ============================================== ====================================== ============================== ==============================

Expand Down Expand Up @@ -391,19 +381,6 @@ Name Type Description
``source_link`` str Link to the source file
================== ========== ========================================

Variables available in sections
-------------------------------

.. class:: table table-bordered table-striped

=================== =========== ===========================================================================
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
=================== =========== ===========================================================================

Variables available in tag pages
--------------------------------

Expand Down
53 changes: 38 additions & 15 deletions docs/theming.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -309,20 +305,49 @@ 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
# 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
Expand Down Expand Up @@ -427,12 +452,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
Expand Down

0 comments on commit f07f2c9

Please sign in to comment.