1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
Theming Nikola
==============
:Version: 5
:Author: Roberto Alsina <ralsina@netmanagers.com.ar>
.. class:: alert alert-info pull-right
.. contents::
This document is a reference about themes. If you want a tutorial, please read
`Creating a Theme <creating-a-theme.html>`_
The Structure
-------------
Themes are located in the ``themes`` folder where Nikola is installed, one folder per theme.
The folder name is the theme name.
A Nikola theme consists of three folders:
assets
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.
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
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.
templates
This contains the templates used to generate the pages. While Nikola will use a
certain set of template names by default, you can add others for specific parts
of your site.
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.
And these optional files:
parent
A text file that, on its first line, contains the name of the **parent theme**.
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.
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".
If this file is not given, "mako" is assumed.
bundles
A text file containing a list of files to be turned into bundles using WebAssets.
For example::
assets/css/all.css=bootstrap.css,bootstrap-responsive.css,rst.css,code.css,colorbox.css,custom.css
This creates a file called "assets/css/all.css" in your output that is the
combination of all the other file paths, relative to the output file.
This makes the page much more efficient because it avoids multiple connections to the server,
at the cost of some extra difficult debugging.
WebAssets supports bundling CSS and JS files.
Templates should use either the bundle or the individual files based on the ``use_bundles``
variable, which in turn is set by the ``USE_BUNDLES`` option.
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>`_
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.
Mako has 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
but defines a few blocks that can be re-defined by inheriting templates:
* ``extra_head`` is a block that is added before ``</head>``, (ex: for adding extra CSS)
* ``belowtitle`` is used by default to display a list of translations but you can put
anything there.
* ``content`` is where the inheriting templates will place the main content of the page.
* ``permalink`` is an absolute path to the page (ex: "/archive/index.html")
This template always receives the following variables you can use:
* ``lang`` is the laguage for this page.
* ``title`` is the page's title.
* ``description`` is the page's description.
* ``blog_title`` is the blog's title.
* ``blog_author`` is the blog's author.
* ``messages`` contains the theme's strings and translations.
* ``_link`` is an utility function to create links to other pages in the site.
It takes three arguments, kind, name, lang:
kind is one of:
* tag_index (name is ignored)
* tag (and name is the tag name)
* tag_rss (name is the tag name)
* archive (and name is the year, or None for the main archive index)
* index (name is the number in index-number)
* rss (name is ignored)
* gallery (name is the gallery name)
The returned value is always an absolute path, like "/archive/index.html".
* ``rel_link`` converts absolute paths to relative ones. You can use it with
``_link`` and ``permalink`` to create relative links, which makes the site
able to work when moved inside the server. Example: ``rel_link(permalink, url)``
* Anything you put in your ``GLOBAL_CONTEXT`` option in ``dodo.py``. This
usually includes ``sidebar_links``, ``search_form``, and others.
The included themes use at least these:
* ``rss_link`` a link to custom RSS feed, although it may be empty)
* ``site_url`` the URL for your site
* ``blog_title`` the name of your site
* ``content_footer`` things like copyright notices, disclaimers, etc.
* ``license`` a larger license badge
* ``analytics`` google scripts, or any JS you want to tack at the end of the body
of the page.
* ``disqus_forum``: a `Disqus <http://disqus.com>`_ ID you can use to enable comments.
It's probably a bad idea to do a theme that *requires* more than this (please put
a ``README`` in it saying what the user should add in its ``dodo.py``), but there is no
problem in requiring less.
post.tmpl
Template used for blog posts. Can use everything ``base.tmpl`` uses, plus:
* ``post``: a Post object. This has a number of members:
* ``post.title(language)``: returns a localized title
* ``post.date``
* ``post.tags``: A list of tags
* ``post.text(language)``: the translated text of the post
* ``post.permalink(language, absolute)``: Link to the post in that language.
If ``absolute`` is ``True`` the link contains the full URL. This is useful
for things like Disqus comment forms.
* ``post.next_post`` is None or a Post object that is next newest in the timeline.
* ``post.prev_post`` is None or a Post object that is next oldest in the timeline.
story.tmpl
Used for pages that are not part of a blog, usually a cleaner, less
intrusive layout than ``post.tmpl``, but same parameters.
gallery.tmpl
Template used for image galleries. Can use everything ``base.tmpl`` uses, plus:
* ``text``: A descriptive text for the gallery.
* ``images``: A list of (thumbnail, image) paths.
index.tmpl
Template used to render the multipost indexes. Can use everything ``base.tmpl`` uses, plus:
* ``posts``: a list of Post objects, as described above.
* ``prevlink``: a link to a previous page
* ``nextlink``: a link to the next page
list.tmpl
Template used to display generic lists of links. Can use everything ``base.tmpl`` uses, plus:
* ``items``: a list of (text, link) elements.
list_post.tmpl
Template used to display generic lists of links. Can use everything ``base.tmpl`` uses, plus:
* ``posts``: a list of Post objects.
You can add other templates for specific pages, which the user can the use in his ``post_pages``
option in ``dodo.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.
Messages and Translations
-------------------------
The included themes are translated into a variety of languages. You can add your own translation
at https://www.transifex.com/projects/p/nikola/
If you want to create a theme that has new strings, and you want those strings to be translatable,
then your theme will need a custom ``messages`` folder.
|
