| Version: | 5 |
|---|---|
| Author: | Roberto Alsina <ralsina@netmanagers.com.ar> |
This document is a reference about themes. If you want a tutorial, please read Creating a Theme
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:
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 and 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.
And these optional files:
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.
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.
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 or Jinja2 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:
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:
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:
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:
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.
Template used for blog posts. Can use everything base.tmpl uses, plus:
Template used for image galleries. Can use everything base.tmpl uses, plus:
Template used to render the multipost indexes. Can use everything base.tmpl uses, plus:
Template used to display generic lists of links. Can use everything base.tmpl uses, plus:
Template used to display generic lists of links. Can use everything base.tmpl uses, plus:
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.
When you modify templates, you may want to add text in them (for example: "About Me"). Instead of adding the text directly, which makes it impossible to translate to other languages, add it like this:
${messages[lang]["About Me"]}
Then, in messages/en.py add it along the other strings:
MESSAGES = [
u"Posts for year %s",
u"Archive",
u"Posts about %s:",
u"Tags",
u"Also available in: ",
u"More posts about",
u"Posted:",
u"Original site",
u"Read in english",
u"About Me",
]
Then, when I want to use your theme in spanish, all I have to do is add a line in messages/es.py:
MESSAGES = {
u"LANGUAGE": u"Español",
u"Posts for year %s": u"Posts del año %s",
u"Archive": u"Archivo",
u"Posts about %s:": u"Posts sobre %s",
u"Tags": u"Tags",
u"Also available in: ": u"También disponible en: ",
u"More posts about": u"Más posts sobre",
u"Posted:": u"Publicado:",
u"Original site": u"Sitio original",
u"Read in english": u"Leer en español",
u"About Me": u"Acerca del autor",
}
And voilá, your theme works in spanish. Don't remove strings from these files even if it seems your theme is not using them. Some are used internally in Nikola to generate titles and similar things.
To create a new translation, just copy one of the existing ones, translate the right side of every string to your language, save it and send it to me, I will add it to Nikola!