From 9c5708cc92af894e414bc76ee35ec2230de5d288 Mon Sep 17 00:00:00 2001 From: Agustin Henze Date: Wed, 2 Jan 2013 08:35:03 -0300 Subject: Imported Upstream version 5.1 --- docs/creating-a-theme.txt | 283 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 docs/creating-a-theme.txt (limited to 'docs/creating-a-theme.txt') diff --git a/docs/creating-a-theme.txt b/docs/creating-a-theme.txt new file mode 100644 index 0000000..0535073 --- /dev/null +++ b/docs/creating-a-theme.txt @@ -0,0 +1,283 @@ +Creating A Theme From Scratch (Almost) +====================================== + +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:: http://ralsina.com.ar/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"> +
+ + +
+ ${analytics} + + + +.. figure:: http://ralsina.com.ar/galleries/random/monospace-2.png + + 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; } + +This will (after we rebuild it) make the site looks different of course, and getting closer to our goal: + +.. figure:: http://ralsina.com.ar/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:: http://ralsina.com.ar/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:: http://ralsina.com.ar/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 included with nikola, if you want to use it or play with it. + -- cgit v1.2.3