--- author: '' category: '' date: 2012/12/28 21:12:38 description: '' link: '' priority: '' slug: creating-a-theme-for-nikola-from-scratch-almost tags: python, nikola title: Creating a Theme for Nikola From Scratch (almost) type: text updated: 2012/12/28 21:12:38 url_type: '' --- There is some documentation about creating themes for Nikola, but maybe a tutorial is also a useful way to explain it. So, here it is. I'll explain how to create a theme (almost) from scratch. Alternatively, you can take an existing theme and modify only parts of it via inheritance, but that's for another document. I will try to create a theme that looks like `Vinicius Massuchetto's Monospace Theme `_. .. TEASER_END Starting The Theme ------------------ First, we create a testing site, and copy the orphan theme from nikola's sources into the right place:: $ nikola init monospace-site A new site with some sample data has been created at monospace-site. See README.txt in that folder for more information. $ cd monospace-site/ $ mkdir themes $ cp -RL ~/Desktop/proyectos/nikola/nikola/nikola/data/themes/orphan/ themes/monospace The next step is to make the testing site use this new theme, by editing ``conf.py`` and changing the ``THEME`` option:: # Name of the theme to use. Themes are located in themes/theme_name THEME = 'monospace' Now we can already build and test the site:: $ nikola build && nikola serve .. figure:: //ralsina.me/galleries/random/monospace-1.png :target: //ralsina.me/galleries/random/monospace-1.png :height: 400px This is the almost completely unstyled "orphan" theme. Of course, the page layout is completely broken. To fix that, we need to get into templates. Templates: Page Layout ---------------------- The general page layout for the theme is done by the ``base.tmpl`` template, which is done using `Mako `_. This is orphan's ``base.tmpl``, it's not very big: .. code-block:: mako ## -*- coding: utf-8 -*- <%namespace file="base_helper.tmpl" import="*"/> ${html_head()} <%block name="extra_head"> %if add_this_buttons: % endif

${blog_title}

<%block name="belowtitle"> %if len(translations) > 1: ${(messages[lang][u"Also available in"])}: ${html_translations()} %endif <%block name="content"> ${content_footer}

${license} ${html_social()} ${html_sidebar_links()}
${search_form}

${analytics} It's basically a HTML document with some placeholders to be replaced with actual content, configuration options, and some helper functions. For example, the ``html_head`` helper can be used to add CSS or JS files in all document's ``head`` tags. Monospace is a two-column-with-footer layout, so let's copy the basics from its HTML and see what happens: .. code-block:: mako ## -*- coding: utf-8 -*- <%namespace file="base_helper.tmpl" import="*"/> ${html_head()} <%block name="extra_head"> %if add_this_buttons: % endif

<%block name="content">

${blog_title}

<%block name="belowtitle"> %if len(translations) > 1: ${(messages[lang][u"Also available in"])}: ${html_translations()} %endif

${license} ${html_social()} ${html_sidebar_links()}
${search_form}

${analytics} .. figure:: //ralsina.me/galleries/random/monospace-2.png :target: //ralsina.me/galleries/random/monospace-2.png :height: 400px Yikes! This will get better quickly once we add some CSS Base CSS -------- The orphan theme includes just a little styling, specifically ``rest.css`` so the restructured text output looks reasonable, and code.css for code snippets. It also includes an empty ``assets/css/theme.css`` where you can add your own CSS. For example, this is taken from the original monospace theme: .. code-block:: css body { margin:0px; padding:20px 0px; text-align:center; font-family:Monospace; color:#585858; } .post { margin:0px 0px 30px 0px; padding:0px 0px 30px 0px; border-bottom:1px dotted #C8C8C8; } .meta { margin:10px; padding:15px; background:#EAEAEA; clear:both; } #footer { text-align:center; clear:both; margin:30px 0px 0px 0px; padding:30px 0px 0px 0px; border-top:1px dotted #C8C8C8; } #wrap { margin:0px auto; text-align:left; font-size: 13px; line-height: 1.4; } #container { float:right; } #sidebar { overflow:hidden; clear:left; text-align:right; width:250px; height:auto; padding:0px 15px 0px 0px; border-right:1px dotted #C8C8C8; } #sidebar li { list-style-type:none; } #sidebar > li { margin:20px 0px; } #sidebar h1 { border-bottom:1px dotted #C8C8C8; } #sidebar .description { display:block; width:100%; height:auto; margin:0px 0px 10px 0px; } h1, h2, h3, h4, h5, h6, h7 { margin:0px; text-transform:uppercase; } h4, h5, h6 { font-size:14px; } h1 { padding:0px 0px 15px; margin:0px 0px 15px 0px; } This will (after we rebuild it) make the site looks different of course, and getting closer to our goal: .. figure:: //ralsina.me/galleries/random/monospace-3.png :target: //ralsina.me/galleries/random/monospace-3.png :height: 400px Monospaced allright. If you compare it to `the original `_, however, you will see that the layout of the posts themselves is different, and that was not described in ``base.tmpl`` at all. But if you look, you'll see that there is a placeholder called content: ``<%block name="content">`` That's because ``base.tmpl`` defines the *base* layout. The layout of more specific pages, like "the page that shows a lis of posts" is defined in the other templates. Specifically, this is defined in ``index.tmpl``: .. code-block:: mako ## -*- coding: utf-8 -*- <%namespace name="helper" file="index_helper.tmpl"/> <%inherit file="base.tmpl"/> <%block name="content"> % for post in posts:

${post.title(lang)} ${messages[lang]["Posted"]}: ${post.date.strftime(date_format)}

${post.text(lang, index_teasers)} ${helper.html_disqus_link(post)}

% endfor ${helper.html_pager()} ${helper.html_disqus_script()} So, let's tweak that to be closer to the original. We put the post's metadata in a box, add links for the posts tags, move the date there, etc. .. code-block:: mako ## -*- coding: utf-8 -*- <%namespace name="helper" file="index_helper.tmpl"/> <%inherit file="base.tmpl"/> <%block name="content"> % for post in posts:

${post.title(lang)}

${messages[lang]["Posted"]}: ${post.date.strftime(date_format)}
Tags: %if post.tags: %for tag in post.tags: ${tag} %endfor %endif

${post.text(lang, index_teasers)} ${helper.html_disqus_link(post)}

% endfor ${helper.html_pager()} .. figure:: //ralsina.me/galleries/random/monospace-4.png :target: //ralsina.me/galleries/random/monospace-4.png :height: 400px Close enough! Then if we click on the post title, we will see some broken details in the metadata that can be fixed in ``post.tmpl``, and so on. .. code-block:: mako ## -*- coding: utf-8 -*- <%namespace name="helper" file="post_helper.tmpl"/> <%inherit file="base.tmpl"/> <%block name="content">

${helper.html_title()}

${messages[lang]["Posted"]}: ${post.date.strftime(date_format)} [${messages[lang]["Source"]}]
%if post.tags: ${messages[lang]["Tags"]}: %for tag in post.tags: ${tag} %endfor
%endif ${helper.html_translations(post)}

${post.text(lang)} ${helper.html_pager(post)} ${helper.html_disqus(post)}

.. figure:: //ralsina.me/galleries/random/monospace-5.png :target: //ralsina.me/galleries/random/monospace-5.png :height: 400px Details, details. The demo site exercises most of the features in Nikola, so if you make it look good, your site probably will look good too. This monospace theme is in nikola's github master, if you want to use it or play with it.