Skip to content
Permalink
Browse files
Update theming.txt
Signed-off-by: Chris Warrick <kwpolska@gmail.com>
  • Loading branch information
Kwpolska committed Apr 14, 2017
1 parent 7edda09 commit b84f62ff87048245c74ea7e2c19f322490ee528d
Showing with 110 additions and 39 deletions.
  1. +1 −1 state_data.json
  2. +109 −38 stories/theming.txt
@@ -1,3 +1,3 @@
{
"last_deploy": "2017-04-14T12:05:11.698615"
"last_deploy": "2017-04-14T12:35:27.179149"
}
@@ -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>`_
themes 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. Its 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:

0 comments on commit b84f62f

Please sign in to comment.