Skip to content

Commit b84f62f

Browse files
committedApr 14, 2017
Update theming.txt
Signed-off-by: Chris Warrick <kwpolska@gmail.com>
1 parent 7edda09 commit b84f62f

File tree

2 files changed

+110
-39
lines changed

2 files changed

+110
-39
lines changed
 

‎state_data.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
{
2-
"last_deploy": "2017-04-14T12:05:11.698615"
2+
"last_deploy": "2017-04-14T12:35:27.179149"
33
}

‎stories/theming.txt

+109-38
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ Theming Nikola
1919
.. class:: lead
2020

2121
This document is a reference about themes. If you want a tutorial, please read
22-
`Creating a Theme <creating-a-theme.html>`_.
22+
`Creating a Theme <creating-a-theme.html>`_. If you’re looking for a ready-made
23+
theme for your site, check out the `Themes Index <https://themes.getnikola.com/>`_.
2324

2425
The Structure
2526
-------------
@@ -30,17 +31,21 @@ of your site, one folder per theme. The folder name is the theme name.
3031
A Nikola theme consists of the following folders (they are *all* optional):
3132

3233
assets
33-
This is where you would put your CSS, Javascript and image files. It will be copied
34+
This is where you would put your CSS, JavaScript and image files. It will be copied
3435
into ``output/assets`` when you build the site, and the templates will contain
35-
references to them.
36+
references to them. The default subdirectories are ``css``, ``js``, ``xml``
37+
and ``fonts`` (Bootstrap).
3638

37-
The included themes use `Bootstrap <http://twitter.github.com/bootstrap/>`_
38-
and `Colorbox <http://www.jacklmoore.com/colorbox>`_ so they are in assets,
39-
along with CSS files for syntax highlighting and reStructuredText, and a
40-
minified copy of jQuery.
39+
The included themes use `Bootstrap <https://getbootstrap.com/>`_, `Colorbox
40+
<http://www.jacklmoore.com/colorbox>`_, `Flowr.js
41+
<https://github.com/kalyan02/flowr-js>`_ and `Moment.js
42+
<https://momentjs.com/>`_, so they are in assets, along with CSS files for
43+
syntax highlighting, reStructuredText and Jupyter, as well as a minified
44+
copy of jQuery.
4145

4246
If you want to base your theme on other frameworks (or on no framework at all)
43-
just remember to put there everything you need for deployment.
47+
just remember to put there everything you need for deployment. (Not all of
48+
the listed assets are used by ``base``)
4449

4550
templates
4651
This contains the templates used to generate the pages. While Nikola will use a
@@ -51,11 +56,8 @@ messages
5156
Nikola tries to be multilingual. This is where you put the strings for your theme
5257
so that it can be translated into other languages.
5358

54-
less
55-
Files to be compiled into CSS using `LESS <http://lesscss.org/>`__
56-
57-
sass
58-
Files to be compiled into CSS using `Sass <http://sass-lang.com/>`__
59+
less, sass
60+
Files to be compiled into CSS using LESS and Sass (both require plugins)
5961

6062
This mandatory file:
6163

@@ -64,8 +66,10 @@ parent
6466
Any resources missing on this theme, will be looked up in the parent theme
6567
(and then in the grandparent, etc).
6668

67-
The ``parent`` is so you don't have to create a full theme each time: just create an
68-
empty theme, set the parent, and add the bits you want modified.
69+
The ``parent`` is so you don’t have to create a full theme each time: just
70+
create an empty theme, set the parent, and add the bits you want modified.
71+
You **must** define a parent, otherwise many features won’t work due to
72+
missing templates, messages, and assets.
6973

7074
I recommend this:
7175

@@ -74,15 +78,19 @@ parent
7478
or ``bootstrap3-jinja``
7579
* In any other case, inherit ``base``.
7680

81+
7782
And these optional files:
7883

7984
engine
8085
A text file which, on the first line, contains the name of the template engine
81-
this theme needs. Currently supported values are "mako" and "jinja".
86+
this theme needs. Currently supported values are "mako" and "jinja". You
87+
must create this file if you’re using Jinja2; otherwise, it’s optional.
8288

8389
bundles
8490
A text file containing a list of files to be turned into bundles using WebAssets.
85-
For example::
91+
For example:
92+
93+
.. code:: text
8694

8795
assets/css/all.css=bootstrap.css,rst.css,code.css,colorbox.css,custom.css
8896

@@ -100,27 +108,25 @@ Templates
100108
---------
101109

102110
In templates there is a number of files whose name ends in ``.tmpl``. Those are the
103-
theme's page templates. They are done using the `Mako <http://makotemplates.org>`_
111+
themes page templates. They are done using the `Mako <http://makotemplates.org>`_
104112
or `Jinja2 <http://jinja.pocoo.org>`_ template languages. If you want to do a theme, you
105113
should learn one first. What engine is used by the theme is declared in the ``engine`` file.
106114

107-
The rest of this document explains Mako templates, but Jinja2 is fairly similar.
108-
109115
.. Tip::
110116

111117
If you are using Mako templates, and want some extra speed when building the site
112118
you can install Beaker and `make templates be cached <http://docs.makotemplates.org/en/latest/caching.html>`__
113119

114120

115-
Mako has a nifty concept of template inheritance. That means that, a
121+
Both template engines have a nifty concept of template inheritance. That means that, a
116122
template can inherit from another and only change small bits of the output. For example,
117123
``base.tmpl`` defines the whole layout for a page but has only a placeholder for content
118124
so ``post.tmpl`` only define the content, and the layout is inherited from ``base.tmpl``.
119125

120126
These are the templates that come with the included themes:
121127

122128
``base.tmpl``
123-
This template defines the basic page layout for the site. It's mostly plain HTML
129+
This template defines the basic page layout for the site. Its mostly plain HTML
124130
but defines a few blocks that can be re-defined by inheriting templates.
125131

126132
It has some separate pieces defined in ``base_helper.tmpl``,
@@ -131,16 +137,31 @@ These are the templates that come with the included themes:
131137
Template used to render the multipost indexes. The posts are in a ``posts`` variable.
132138
Some functionality is in the ``index_helper.tmpl`` helper template.
133139

140+
``annotation_helper.tmpl`` (internal)
141+
Code for the optional annotations feature.
142+
143+
``archive_navigation_helper.tmpl``
144+
Code that implements archive navigation (previous/up/next). Included by
145+
archive templates.
146+
134147
``archiveindex.tmpl``
135148
Used to display archives, if ``ARCHIVES_ARE_INDEXES`` is True.
136-
By default, it just inherits ``index.tmpl``.
149+
By default, it just inherits ``index.tmpl``, with added archive navigation
150+
and feeds.
151+
152+
``author.tmpl``
153+
Used to display author pages.
137154

138-
``comments_helper.tmpl``
155+
``authorindex.tmpl``
156+
Used to display author indexes, if ``AUTHOR_PAGES_ARE_INDEXES`` is True.
157+
By default, it just inherits ``index.tmpl``, with added feeds.
158+
159+
``comments_helper.tmpl`` (internal)
139160
This template handles comments. You should probably never touch it :-)
140161
It uses a bunch of helper templates, one for each supported comment system
141162
(all of which start with ``comments_helper``)
142163

143-
``crumbs.tmpl``, ``slides.tmpl``
164+
``crumbs.tmpl``, ``slides.tmpl``, ``pagination_helper.tmpl``
144165
These templates help render specific UI items, and can be tweaked as needed.
145166

146167
``gallery.tmpl``
@@ -162,14 +183,17 @@ These are the templates that come with the included themes:
162183

163184
``list.tmpl``
164185
Template used to display generic lists of links, which it gets in ``items``,
165-
a list of (text, link) elements.
186+
a list of *(text, link, count)* elements.
166187

167188
``list_post.tmpl``
168189
Template used to display generic lists of posts, which it gets in ``posts``.
169190

170191
``listing.tmpl``
171192
Used to display code listings.
172193

194+
``math_helper.tmpl`` (internal)
195+
Used to add MathJax/KaTeX code to pages.
196+
173197
``post.tmpl``
174198
Template used by default for blog posts, gets the data in a ``post`` object
175199
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:
178202
``post_list_directive.tmpl``
179203
Template used by the ``post_list`` reStructuredText directive.
180204

205+
``sectionindex.tmpl``
206+
Used to display section indexes, if ``POST_SECTIONS_ARE_INDEXES`` is True.
207+
By default, it just inherits ``index.tmpl``, with added feeds.
208+
181209
``story.tmpl``
182210
Used for pages that are not part of a blog, usually a cleaner, less
183211
intrusive layout than ``post.tmpl``, but same parameters.
@@ -187,23 +215,25 @@ These are the templates that come with the included themes:
187215

188216
``tagindex.tmpl``
189217
Used to show the contents of a single tag or category, if ``TAG_PAGES_ARE_INDEXES`` is True.
190-
By default, it just inherits ``index.tmpl``.
218+
By default, it just inherits ``index.tmpl``, with added feeds and some
219+
extra features.
191220

192221
``tags.tmpl``
193222
Used to display the list of tags and categories.
194223

195224
You can add other templates for specific pages, which the user can then use in his ``POSTS``
196-
or ``PAGES`` option in ``conf.py``. Also, keep in mind that your theme is yours,
197-
there is no reason why you would need to maintain the inheritance as it is, or not
198-
require whatever data you want.
225+
or ``PAGES`` option in ``conf.py``. Also, keep in mind that your theme is
226+
*yours*, there is no reason why you would need to maintain the inheritance as
227+
it is, or not require whatever data you want (eg. you may depend on specific
228+
custom ``GLOBAL_CONTEXT`` variables, or post meta attributes)
199229

200230
Also, you can specify a custom template to be used by a post or page via the ``template`` metadata,
201231
and custom templates can be added in the ``templates/`` folder of your site.
202232

203233
Variables available in templates
204234
--------------------------------
205235

206-
The list of variables available in templates is maintained in a separate
236+
The full, complete list of variables available in templates is maintained in a separate
207237
document: `Template variables <https://getnikola.com/template-variables.html>`_
208238

209239
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
223253
altered in the HSL colorspace through the function
224254
``color_hsl_adjust_hex(hex_string, adjust_h, adjust_s, adjust_l)``.
225255
Adjustments are given in values between 1.0 and -1.0. For example, the theme
226-
color can be made lighter using:
256+
color can be made lighter using this code:
227257

228258
.. code:: html+mako
229259

230-
<span style="color:${color_hsl_adjust_hex(theme_color, adjust_l=0.05)}">
260+
<!-- Mako -->
261+
<span style="color: ${color_hsl_adjust_hex(theme_color, adjust_l=0.05)}">
262+
263+
.. code:: html+jinja
264+
265+
<!-- Jinja2 -->
266+
<span style="color: {{ color_hsl_adjust_hex(theme_color, adjust_l=0.05) }}">
231267

232268
Identifying and customizing different kinds of pages with a shared template
233269
---------------------------------------------------------------------------
234270

235-
Nikola provides a `pagekind` in each template contexts that can be used to
271+
Nikola provides a ``pagekind`` in each template contexts that can be used to
236272
modify shared templates based on the context it’s being used. For example,
237-
the ``base_helper.tmpl`` is used in all pages, ``indexes.tmpl`` is used in
273+
the ``base_helper.tmpl`` is used in all pages, ``index.tmpl`` is used in
238274
many contexts and you may want to add or remove something from only one of
239275
these contexts.
240276

241277
Example of conditionally loading different resources on all index pages
242-
(archives, author pages, and tag pages), and others again o the front page
278+
(archives, author pages, and tag pages), and others again to the front page
243279
and in every post pages:
244280

245281
.. code:: html+mako
246282

283+
<!-- Mako -->
247284
<head>
248285
249286
% if 'index' in pagekind:
@@ -259,23 +296,57 @@ and in every post pages:
259296
% endif
260297
</head>
261298

299+
.. code:: html+jinja
300+
301+
<!-- Jinja2 -->
302+
<head>
303+
304+
{% if 'index' in pagekind %}
305+
<link href="/assets/css/multicolumn.css" rel="stylesheet">
306+
{% endif %}
307+
{% if 'front_page' in pagekind %}
308+
<link href="/assets/css/fancy_homepage.css" rel="stylesheet">
309+
<script src="/assets/js/post_carousel.js"></script>
310+
{% endif %}
311+
{% if 'post_page' in pagekind %}
312+
<link href="/assets/css/article.css" rel="stylesheet">
313+
<script src="/assets/js/comment_system.js"></script>
314+
{% endif %}
315+
</head>
316+
317+
262318
Promoting visits to the front page when visiting other filtered
263319
``index.tmpl`` page variants such as author pages and tag pages. This
264320
could have been included in ``index.tmpl`` or maybe in ``base.tmpl``
265321
depending on what you want to achieve.
266322

267323
.. code:: html+mako
268324

325+
<!-- Mako -->
269326
% if 'index' in pagekind:
270-
% if 'author_page' in postkind:
327+
% if 'author_page' in pagekind:
271328
<p>These posts were written by ${author}. See posts by all
272329
authors on the <a href="/">front page</a>.</p>
273-
% elif 'tag_page' in postkind:
330+
% elif 'tag_page' in pagekind:
274331
<p>This is a filtered selection of posts tagged “${tag}”, visit
275332
the <a href="/">front page</a> to see all posts.</p>
276333
% endif
277334
% endif
278335

336+
.. code:: html+jinja
337+
338+
<!-- Jinja2 -->
339+
{% if 'index' in pagekind %}
340+
{% if 'author_page' in pagekind %}
341+
<p>These posts were written by {{ author }}. See posts by all
342+
authors on the <a href="/">front page</a>.</p>
343+
{% elif 'tag_page' in pagekind %}
344+
<p>This is a filtered selection of posts tagged “{{ tag }}”, visit
345+
the <a href="/">front page</a> to see all posts.</p>
346+
{% endif %}
347+
{% endif %}
348+
349+
279350

280351
List of page kinds provided by default plugins:
281352

0 commit comments

Comments
 (0)
Please sign in to comment.