diff options
Diffstat (limited to 'docs/theming.txt')
| -rw-r--r-- | docs/theming.txt | 100 |
1 files changed, 97 insertions, 3 deletions
diff --git a/docs/theming.txt b/docs/theming.txt index 4b6b4a7..f84f966 100644 --- a/docs/theming.txt +++ b/docs/theming.txt @@ -4,11 +4,12 @@ .. tags: .. link: .. description: +.. author: The Nikola Team Theming Nikola ============== -:Version: 7.6.4 +:Version: 7.7.3 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> .. class:: alert alert-info pull-right @@ -35,7 +36,7 @@ assets The included themes use `Bootstrap <http://twitter.github.com/bootstrap/>`_ and `Colorbox <http://www.jacklmoore.com/colorbox>`_ so they are in assets, - along with CSS files for syntax highligting and reStructuredText, and a + along with CSS files for syntax highlighting and reStructuredText, and a minified copy of jQuery. If you want to base your theme on other frameworks (or on no framework at all) @@ -118,7 +119,7 @@ These are the templates that come with the included themes: It has some separate pieces defined in ``base_helper.tmpl``, ``base_header.tmpl`` and ``base_footer.tmpl`` so they can be - easily overriden. + easily overridden. ``index.tmpl`` Template used to render the multipost indexes. The posts are in a ``posts`` variable. @@ -193,6 +194,99 @@ 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. +Customizing themes to user color preference and section colors +-------------------------------------------------------------- + +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 + +Hex color values, like that returned by the theme or section color 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 +color can be made lighter using: + +.. code:: html+mako + + <span style="color:${color_hsl_adjust_hex(theme_color, adjust_l=0.05)}"> + +Identifying and customizing different kinds of pages with a shared template +--------------------------------------------------------------------------- + +Nikola provides a `pagekind` in each template contexts that can be used to +modify shared templates based on the context it’s being used. For example, +the ``base_helper.tmpl`` is used in all pages, ``indexes.tmpl`` is used in +many contexts and you may want to add or remove something from only one of +these contexts. + +Example of conditionally loading different resources on all index pages +(archives, author pages, and tag pages), and others again o the front page +and in every post pages: + +.. code:: html+mako + + <head> + … + % if 'index' in pagekind: + <link href="/assets/css/multicolumn.css" rel="stylesheet"> + % endif + % if 'front_page' in pagekind: + <link href="/assets/css/fancy_homepage.css" rel="stylesheet"> + <script src="/assets/js/post_carousel.js"></script> + % endif + % if 'post_page' in pagekind: + <link href="/assets/css/article.css" rel="stylesheet"> + <script src="/assets/js/comment_system.js"></script> + % endif + </head> + +Promoting visits to the front page when visiting other filtered +``index.tmpl`` page variants such as author pages and tag pages. This +could have been included in ``index.tmpl`` or maybe in ``base.tmpl`` +depending on what you want to achieve. + +.. code:: html+mako + + % if 'index' in pagekind: + % if 'author_page' in postkind: + <p>These posts were written by ${author}. See posts by all + authors on the <a href="/">front page</a>.</p> + % elif 'tag_page' in postkind: + <p>This is a filtered selection of posts tagged “${tag}”, visit + the <a href="/">front page</a> to see all posts.</p> + % endif + % endif + + +List of page kinds provided by default plugins: + +* front_page +* index +* 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 +* story_page +* listing +* generic_page +* gallery_front +* gallery_page + Messages and Translations ------------------------- |