@@ -19,7 +19,8 @@ Theming Nikola
19
19
.. class:: lead
20
20
21
21
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/>`_.
23
24
24
25
The Structure
25
26
-------------
@@ -30,17 +31,21 @@ of your site, one folder per theme. The folder name is the theme name.
30
31
A Nikola theme consists of the following folders (they are *all* optional):
31
32
32
33
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
34
35
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).
36
38
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.
41
45
42
46
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``)
44
49
45
50
templates
46
51
This contains the templates used to generate the pages. While Nikola will use a
@@ -51,11 +56,8 @@ messages
51
56
Nikola tries to be multilingual. This is where you put the strings for your theme
52
57
so that it can be translated into other languages.
53
58
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)
59
61
60
62
This mandatory file:
61
63
@@ -64,8 +66,10 @@ parent
64
66
Any resources missing on this theme, will be looked up in the parent theme
65
67
(and then in the grandparent, etc).
66
68
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.
69
73
70
74
I recommend this:
71
75
@@ -74,15 +78,19 @@ parent
74
78
or ``bootstrap3-jinja``
75
79
* In any other case, inherit ``base``.
76
80
81
+
77
82
And these optional files:
78
83
79
84
engine
80
85
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.
82
88
83
89
bundles
84
90
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
86
94
87
95
assets/css/all.css=bootstrap.css,rst.css,code.css,colorbox.css,custom.css
88
96
@@ -100,27 +108,25 @@ Templates
100
108
---------
101
109
102
110
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
+ theme’ s page templates. They are done using the `Mako <http://makotemplates.org>`_
104
112
or `Jinja2 <http://jinja.pocoo.org>`_ template languages. If you want to do a theme, you
105
113
should learn one first. What engine is used by the theme is declared in the ``engine`` file.
106
114
107
- The rest of this document explains Mako templates, but Jinja2 is fairly similar.
108
-
109
115
.. Tip::
110
116
111
117
If you are using Mako templates, and want some extra speed when building the site
112
118
you can install Beaker and `make templates be cached <http://docs.makotemplates.org/en/latest/caching.html>`__
113
119
114
120
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
116
122
template can inherit from another and only change small bits of the output. For example,
117
123
``base.tmpl`` defines the whole layout for a page but has only a placeholder for content
118
124
so ``post.tmpl`` only define the content, and the layout is inherited from ``base.tmpl``.
119
125
120
126
These are the templates that come with the included themes:
121
127
122
128
``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. It’ s mostly plain HTML
124
130
but defines a few blocks that can be re-defined by inheriting templates.
125
131
126
132
It has some separate pieces defined in ``base_helper.tmpl``,
@@ -131,16 +137,31 @@ These are the templates that come with the included themes:
131
137
Template used to render the multipost indexes. The posts are in a ``posts`` variable.
132
138
Some functionality is in the ``index_helper.tmpl`` helper template.
133
139
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
+
134
147
``archiveindex.tmpl``
135
148
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.
137
154
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)
139
160
This template handles comments. You should probably never touch it :-)
140
161
It uses a bunch of helper templates, one for each supported comment system
141
162
(all of which start with ``comments_helper``)
142
163
143
- ``crumbs.tmpl``, ``slides.tmpl``
164
+ ``crumbs.tmpl``, ``slides.tmpl``, ``pagination_helper.tmpl``
144
165
These templates help render specific UI items, and can be tweaked as needed.
145
166
146
167
``gallery.tmpl``
@@ -162,14 +183,17 @@ These are the templates that come with the included themes:
162
183
163
184
``list.tmpl``
164
185
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.
166
187
167
188
``list_post.tmpl``
168
189
Template used to display generic lists of posts, which it gets in ``posts``.
169
190
170
191
``listing.tmpl``
171
192
Used to display code listings.
172
193
194
+ ``math_helper.tmpl`` (internal)
195
+ Used to add MathJax/KaTeX code to pages.
196
+
173
197
``post.tmpl``
174
198
Template used by default for blog posts, gets the data in a ``post`` object
175
199
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:
178
202
``post_list_directive.tmpl``
179
203
Template used by the ``post_list`` reStructuredText directive.
180
204
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
+
181
209
``story.tmpl``
182
210
Used for pages that are not part of a blog, usually a cleaner, less
183
211
intrusive layout than ``post.tmpl``, but same parameters.
@@ -187,23 +215,25 @@ These are the templates that come with the included themes:
187
215
188
216
``tagindex.tmpl``
189
217
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.
191
220
192
221
``tags.tmpl``
193
222
Used to display the list of tags and categories.
194
223
195
224
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)
199
229
200
230
Also, you can specify a custom template to be used by a post or page via the ``template`` metadata,
201
231
and custom templates can be added in the ``templates/`` folder of your site.
202
232
203
233
Variables available in templates
204
234
--------------------------------
205
235
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
207
237
document: `Template variables <https://getnikola.com/template-variables.html>`_
208
238
209
239
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
223
253
altered in the HSL colorspace through the function
224
254
``color_hsl_adjust_hex(hex_string, adjust_h, adjust_s, adjust_l)``.
225
255
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 :
227
257
228
258
.. code:: html+mako
229
259
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) }}">
231
267
232
268
Identifying and customizing different kinds of pages with a shared template
233
269
---------------------------------------------------------------------------
234
270
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
236
272
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
238
274
many contexts and you may want to add or remove something from only one of
239
275
these contexts.
240
276
241
277
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
243
279
and in every post pages:
244
280
245
281
.. code:: html+mako
246
282
283
+ <!-- Mako -->
247
284
<head>
248
285
…
249
286
% if 'index' in pagekind:
@@ -259,23 +296,57 @@ and in every post pages:
259
296
% endif
260
297
</head>
261
298
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
+
262
318
Promoting visits to the front page when visiting other filtered
263
319
``index.tmpl`` page variants such as author pages and tag pages. This
264
320
could have been included in ``index.tmpl`` or maybe in ``base.tmpl``
265
321
depending on what you want to achieve.
266
322
267
323
.. code:: html+mako
268
324
325
+ <!-- Mako -->
269
326
% if 'index' in pagekind:
270
- % if 'author_page' in postkind :
327
+ % if 'author_page' in pagekind :
271
328
<p>These posts were written by ${author}. See posts by all
272
329
authors on the <a href="/">front page</a>.</p>
273
- % elif 'tag_page' in postkind :
330
+ % elif 'tag_page' in pagekind :
274
331
<p>This is a filtered selection of posts tagged “${tag}”, visit
275
332
the <a href="/">front page</a> to see all posts.</p>
276
333
% endif
277
334
% endif
278
335
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
+
279
350
280
351
List of page kinds provided by default plugins:
281
352
0 commit comments