Fix #2259 -- refresh theming.txt (templates, Jinja2)

Signed-off-by: Chris Warrick <kwpolska@gmail.com>
getnikola · Apr 14, 2017 · c33f28b · c33f28b
1 parent 6356485
commit c33f28b
Show file tree

Hide file tree

Showing 2 changed files with 110 additions and 39 deletions.
diff --git a/CHANGES.txt b/CHANGES.txt
@@ -14,7 +14,7 @@ Features
 --------
 
 * Add a list of template variables to documentation (Issues #2328,
-  #2712)
+  #2712, #2259) and update the theming reference (Issue #2259)
 * Add ``{post_title}`` tag for Read More links (Issue #2709)
 * Include MathJax config only when needed (via Issue #2715)
 * Include KaTeX CSS automatically when needed (Issue #2715)

diff --git a/docs/theming.txt b/docs/theming.txt
@@ -19,7 +19,8 @@ Theming Nikola
 .. class:: lead
 
 This document is a reference about themes. If you want a tutorial, please read
-`Creating a Theme <creating-a-theme.html>`_.
+`Creating a Theme <creating-a-theme.html>`_. If you’re looking for a ready-made
+theme for your site, check out the `Themes Index <https://themes.getnikola.com/>`_.
 
 The Structure
 -------------
@@ -30,17 +31,21 @@ of your site, one folder per theme. The folder name is the theme name.
 A Nikola theme consists of the following folders (they are *all* optional):
 
 assets
-    This is where you would put your CSS, Javascript and image files. It will be copied
+    This is where you would put your CSS, JavaScript and image files. It will be copied
     into ``output/assets`` when you build the site, and the templates will contain
-    references to them.
+    references to them. The default subdirectories are ``css``, ``js``, ``xml``
+    and ``fonts`` (Bootstrap).
 
-    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 highlighting and reStructuredText, and a
-    minified copy of jQuery.
+    The included themes use `Bootstrap <https://getbootstrap.com/>`_, `Colorbox
+    <http://www.jacklmoore.com/colorbox>`_, `Flowr.js
+    <https://github.com/kalyan02/flowr-js>`_ and `Moment.js
+    <https://momentjs.com/>`_, so they are in assets, along with CSS files for
+    syntax highlighting, reStructuredText and Jupyter, as well as a minified
+    copy of jQuery.
 
     If you want to base your theme on other frameworks (or on no framework at all)
-    just remember to put there everything you need for deployment.
+    just remember to put there everything you need for deployment. (Not all of
+    the listed assets are used by ``base``)
 
 templates
     This contains the templates used to generate the pages. While Nikola will use a
@@ -51,11 +56,8 @@ messages
     Nikola tries to be multilingual. This is where you put the strings for your theme
     so that it can be translated into other languages.
 
-less
-    Files to be compiled into CSS using `LESS <http://lesscss.org/>`__
-
-sass
-    Files to be compiled into CSS using `Sass <http://sass-lang.com/>`__
+less, sass
+    Files to be compiled into CSS using LESS and Sass (both require plugins)
 
 This mandatory file:
 
@@ -64,8 +66,10 @@ parent
     Any resources missing on this theme, will be looked up in the parent theme
     (and then in the grandparent, etc).
 
-    The ``parent`` is so you don't have to create a full theme each time: just create an
-    empty theme, set the parent, and add the bits you want modified.
+    The ``parent`` is so you don’t have to create a full theme each time: just
+    create an empty theme, set the parent, and add the bits you want modified.
+    You **must** define a parent, otherwise many features won’t work due to
+    missing templates, messages, and assets.
 
     I recommend this:
 
@@ -74,15 +78,19 @@ parent
       or ``bootstrap3-jinja``
     * In any other case, inherit ``base``.
 
+
 And these optional files:
 
 engine
     A text file which, on the first line, contains the name of the template engine
-    this theme needs. Currently supported values are "mako" and "jinja".
+    this theme needs. Currently supported values are "mako" and "jinja". You
+    must create this file if you’re using Jinja2; otherwise, it’s optional.
 
 bundles
     A text file containing a list of files to be turned into bundles using WebAssets.
-    For example::
+    For example:
+
+    .. code:: text
 
         assets/css/all.css=bootstrap.css,rst.css,code.css,colorbox.css,custom.css
 
@@ -100,27 +108,25 @@ Templates
 ---------
 
 In templates there is a number of files whose name ends in ``.tmpl``. Those are the
-theme's page templates. They are done using the `Mako <http://makotemplates.org>`_
+theme’s page templates. They are done using the `Mako <http://makotemplates.org>`_
 or `Jinja2 <http://jinja.pocoo.org>`_ template languages. If you want to do a theme, you
 should learn one first. What engine is used by the theme is declared in the ``engine`` file.
 
-The rest of this document explains Mako templates, but Jinja2 is fairly similar.
-
 .. Tip::
 
    If you are using Mako templates, and want some extra speed when building the site
    you can install Beaker and `make templates be cached <http://docs.makotemplates.org/en/latest/caching.html>`__
 
 
-Mako has a nifty concept of template inheritance. That means that, a
+Both template engines have a nifty concept of template inheritance. That means that, a
 template can inherit from another and only change small bits of the output. For example,
 ``base.tmpl`` defines the whole layout for a page but has only a placeholder for content
 so ``post.tmpl`` only define the content, and the layout is inherited from ``base.tmpl``.
 
 These are the templates that come with the included themes:
 
 ``base.tmpl``
-    This template defines the basic page layout for the site. It's mostly plain HTML
+    This template defines the basic page layout for the site. It’s mostly plain HTML
     but defines a few blocks that can be re-defined by inheriting templates.
 
     It has some separate pieces defined in ``base_helper.tmpl``,
@@ -131,16 +137,31 @@ These are the templates that come with the included themes:
     Template used to render the multipost indexes. The posts are in a ``posts`` variable.
     Some functionality is in the ``index_helper.tmpl`` helper template.
 
+``annotation_helper.tmpl`` (internal)
+    Code for the optional annotations feature.
+
+``archive_navigation_helper.tmpl``
+    Code that implements archive navigation (previous/up/next). Included by
+    archive templates.
+
 ``archiveindex.tmpl``
     Used to display archives, if ``ARCHIVES_ARE_INDEXES`` is True.
-    By default, it just inherits ``index.tmpl``.
+    By default, it just inherits ``index.tmpl``, with added archive navigation
+    and feeds.
+
+``author.tmpl``
+    Used to display author pages.
 
-``comments_helper.tmpl``
+``authorindex.tmpl``
+    Used to display author indexes, if ``AUTHOR_PAGES_ARE_INDEXES`` is True.
+    By default, it just inherits ``index.tmpl``, with added feeds.
+
+``comments_helper.tmpl`` (internal)
     This template handles comments. You should probably never touch it :-)
     It uses a bunch of helper templates, one for each supported comment system
     (all of which start with ``comments_helper``)
 
-``crumbs.tmpl``, ``slides.tmpl``
+``crumbs.tmpl``, ``slides.tmpl``, ``pagination_helper.tmpl``
     These templates help render specific UI items, and can be tweaked as needed.
 
 ``gallery.tmpl``
@@ -162,14 +183,17 @@ These are the templates that come with the included themes:
 
 ``list.tmpl``
     Template used to display generic lists of links, which it gets in ``items``,
-    a list of (text, link) elements.
+    a list of *(text, link, count)* elements.
 
 ``list_post.tmpl``
     Template used to display generic lists of posts, which it gets in ``posts``.
 
 ``listing.tmpl``
     Used to display code listings.
 
+``math_helper.tmpl`` (internal)
+    Used to add MathJax/KaTeX code to pages.
+
 ``post.tmpl``
     Template used by default for blog posts, gets the data in a ``post`` object
     which is an instance of the Post class. Some functionality is in the
@@ -178,6 +202,10 @@ 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.
+
 ``story.tmpl``
     Used for pages that are not part of a blog, usually a cleaner, less
     intrusive layout than ``post.tmpl``, but same parameters.
@@ -187,23 +215,25 @@ These are the templates that come with the included themes:
 
 ``tagindex.tmpl``
     Used to show the contents of a single tag or category, if ``TAG_PAGES_ARE_INDEXES`` is True.
-    By default, it just inherits ``index.tmpl``.
+    By default, it just inherits ``index.tmpl``, with added feeds and some
+    extra features.
 
 ``tags.tmpl``
     Used to display the list of tags and categories.
 
 You can add other templates for specific pages, which the user can then use in his ``POSTS``
-or ``PAGES`` option in ``conf.py``. Also, keep in mind that your theme is yours,
-there is no reason why you would need to maintain the inheritance as it is, or not
-require whatever data you want.
+or ``PAGES`` option in ``conf.py``. Also, keep in mind that your theme is
+*yours*, there is no reason why you would need to maintain the inheritance as
+it is, or not require whatever data you want (eg. you may depend on specific
+custom ``GLOBAL_CONTEXT`` variables, or post meta attributes)
 
 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.
 
 Variables available in templates
 --------------------------------
 
-The list of variables available in templates is maintained in a separate
+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
@@ -223,27 +253,34 @@ 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:
+color can be made lighter using this code:
 
 .. code:: html+mako
 
-    <span style="color:${color_hsl_adjust_hex(theme_color, adjust_l=0.05)}">
+    <!-- Mako -->
+    <span style="color: ${color_hsl_adjust_hex(theme_color, adjust_l=0.05)}">
+
+.. code:: html+jinja
+
+    <!-- Jinja2 -->
+    <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
+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
+the ``base_helper.tmpl`` is used in all pages, ``index.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
+(archives, author pages, and tag pages), and others again to the front page
 and in every post pages:
 
 .. code:: html+mako
 
+    <!-- Mako -->
     <head>
         …
         % if 'index' in pagekind:
@@ -259,23 +296,57 @@ and in every post pages:
         % endif
     </head>
 
+.. code:: html+jinja
+
+    <!-- Jinja2 -->
+    <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
 
+    <!-- Mako -->
     % if 'index' in pagekind:
-        % if 'author_page' in postkind:
+        % if 'author_page' in pagekind:
             <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:
+        % elif 'tag_page' in pagekind:
             <p>This is a filtered selection of posts tagged “${tag}”, visit
                the <a href="/">front page</a> to see all posts.</p>
         % endif
     % endif
 
+.. code:: html+jinja
+
+    <!-- Jinja2 -->
+    {% if 'index' in pagekind %}
+        {% if 'author_page' in pagekind %}
+            <p>These posts were written by {{ author }}. See posts by all
+               authors on the <a href="/">front page</a>.</p>
+        {% elif 'tag_page' in pagekind %}
+            <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: