diff options
Diffstat (limited to 'docs/theming.txt')
| -rw-r--r-- | docs/theming.txt | 204 |
1 files changed, 109 insertions, 95 deletions
diff --git a/docs/theming.txt b/docs/theming.txt index d767cae..99492ab 100644 --- a/docs/theming.txt +++ b/docs/theming.txt @@ -1,7 +1,14 @@ +.. title: Theming Nikola +.. slug: theming +.. date: 2012/03/13 12:00 +.. tags: +.. link: +.. description: + Theming Nikola ============== -:Version: 5 +:Version: 6.2.1 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> .. class:: alert alert-info pull-right @@ -14,10 +21,10 @@ This document is a reference about themes. If you want a tutorial, please read The Structure ------------- -Themes are located in the ``themes`` folder where Nikola is installed, one folder per theme. -The folder name is the theme name. +Themes are located in the ``themes`` folder where Nikola is installed, and in the ``themes`` folder +of your site, one folder per theme. The folder name is the theme name. -A Nikola theme consists of three folders: +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 @@ -41,7 +48,13 @@ 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: +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/>`__ + +This mandatory file: parent A text file that, on its first line, contains the name of the **parent theme**. @@ -51,10 +64,19 @@ parent 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. + I recommend this: + + * If your theme uses bootstrap, inherit the ``bootstrap`` theme. + * If your theme uses bootstrap3, inherit the ``bootstrap3`` theme. + * If your theme uses Jinja as a template engine, inherit ``base-jinja`` + or ``bootstrap-jinja`` (available at http://themes.nikola.ralsina.com.ar) + * 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". - 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. @@ -89,108 +111,74 @@ so ``post.tmpl`` only define the content, and the layout is inherited from ``bas These are the templates that come with the included themes: -base.tmpl +``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. + but defines a few blocks that can be re-defined by inheriting templates. + + It has some separate pieces defined in ``base_helper.tmpl`` so they can be + easily overriden. For example, the Bootstrap theme adds a ``bootstrap_helper.tmpl`` + and then uses it to override things defined in base theme's ``base_helper.tmpl`` + +``index.tmpl`` + Template used to render the multipost indexes. The posts are in a ``posts`` variable. + Some functionality is in the ``index_helper.tmpl`` helper template. -gallery.tmpl - Template used for image galleries. Can use everything ``base.tmpl`` uses, plus: +``comments_helper.tmpl`` + This template handles comments. You should probably never touch it :-) + It uses a bunch of helper templates, one for each supported comment system: + ``disqus_helper.tmpl`` ``facebook_helper.tmpl`` ``googleplus_helper.tmpl`` + ``intensedebate_helper.tmpl`` ``livefyre_helper.tmpl`` ``moot_helper.tmpl`` + +``crumbs.tmpl`` ``slides.tmpl`` + These templates help render specific UI items, and can be tweaked as needed. + +``gallery.tmpl`` + Template used for image galleries. Interesting data includes: * ``text``: A descriptive text for the gallery. - * ``images``: A list of (thumbnail, image) paths. + * ``crumbs``: A list of ``link, crumb`` to implement a crumbbar. + * ``folders``: A list of folders to implement hierarchical gallery navigation. + * ``enable_comments``: To enable/disable comments in galleries. + * ``thumbnail_size``: The ``THUMBNAIL_SIZE`` option. + * ``photo_array``: a list of dictionaries, each containing: + + + ``url``: URL for the full-sized image. + + ``url_thumb``: URL for the thumbnail. + + ``title``: The title of the image. + + ``size``: A dict containing ``w`` and ``h``, the real size of the thumbnail. -index.tmpl - Template used to render the multipost indexes. Can use everything ``base.tmpl`` uses, plus: + * ``photo_array_json``: a JSON dump of photo_array, used in the bootstrap theme by flowr.js - * ``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, which it gets in ``items``, + a list of (text, link) elements. -list.tmpl - Template used to display generic lists of links. Can use everything ``base.tmpl`` uses, plus: +``list_post.tmpl`` + Template used to display generic lists of posts, which it gets in ``posts``. - * ``items``: a list of (text, link) elements. +``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 + ``post_helper.tmpl`` template. +``story.tmpl`` + Used for pages that are not part of a blog, usually a cleaner, less + intrusive layout than ``post.tmpl``, but same parameters. -list_post.tmpl - Template used to display generic lists of links. Can use everything ``base.tmpl`` uses, plus: +``listing.tmpl`` + Used to display code listings. - * ``posts``: a list of Post objects. +``tags.tmpl`` + Used to display the list of tags and categories. ``tag.tmpl`` is used to show the contents + of a single tag or category. +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. -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. +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. Messages and Translations ------------------------- @@ -200,3 +188,29 @@ 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. + +`LESS <http://lesscss.org/>`__ and `Sass <http://sass-lang.com/>`__ +------------------------------------------------------------------- + +.. note:: + The LESS and Sass compilers will be moved to the Plugins Index in + Nikola v7.0.0. + +If you want to use those CSS extensions, you can — just store your files +in the ``less`` or ``sass`` directory of your theme. + +In order to have them work, you need to create a list of ``.less`` or +``.scss/.sass`` files to compile — the list should be in a file named +``targets`` in the respective directory (``less``/``sass``). + +The files listed in the ``targets`` file will be passed to the respective +compiler, which you have to install manually (``lessc`` which comes from +the Node.js package named ``less`` or ``sass`` from a Ruby package aptly +named ``sass``). Whatever the compiler outputs will be saved as a CSS +file in your rendered site, with the ``.css`` extension. + +.. note:: + Conflicts may occur if you have two files with the same base name + but a different extension. Pay attention to how you name your files + or your site won’t build! (Nikola will tell you what’s wrong when + this happens) |