diff options
Diffstat (limited to 'docs/creating-a-theme.txt')
| -rw-r--r-- | docs/creating-a-theme.txt | 283 |
1 files changed, 283 insertions, 0 deletions
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 <http://vinicius.soylocoporti.org.br/monospace-wordpress-theme/#.UN4e9lLzu3c>`_. + +.. 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 <http://www.makotemplates.org/>`_. This is orphan's ``base.tmpl``, it's not very big: + +.. code-block:: mako + + ## -*- coding: utf-8 -*- + <%namespace file="base_helper.tmpl" import="*"/> + <!DOCTYPE html> + <html lang="${lang}"> + <head> + ${html_head()} + <%block name="extra_head"> + </%block> + </head> + <body> + %if add_this_buttons: + <script type="text/javascript">var addthis_config={"ui_language":"${lang}"};</script> + % endif + <h1 id="blog-title"> + <a href="${abs_link('/')}" title="${blog_title}">${blog_title}</a> + </h1> + <%block name="belowtitle"> + %if len(translations) > 1: + <small> + ${(messages[lang][u"Also available in"])}: + ${html_translations()} + </small> + %endif + </%block> + <%block name="content"></%block> + <small>${content_footer}</small> + <!--Sidebar content--> + <ul class="unstyled"> + <li>${license} + ${html_social()} + ${html_sidebar_links()} + <li>${search_form} + </ul> + ${analytics} + <script type="text/javascript">jQuery("a.image-reference").colorbox({rel:"gal",maxWidth:"80%",maxHeight:"80%",scalePhotos:true});</script> + </body> + + +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="*"/> + <!DOCTYPE html> + <html lang="${lang}"> + <head> + ${html_head()} + <%block name="extra_head"> + </%block> + </head> + <body class="home blog"> + %if add_this_buttons: + <script type="text/javascript">var addthis_config={"ui_language":"${lang}"};</script> + % endif + <div id="wrap" style="width:850px"> + <div id="container" style="width:560px"> + <%block name="content"></%block> + </div> + <div id="sidebar"> + <!--Sidebar content--> + <h1 id="blog-title"> + <a href="${abs_link('/')}" title="${blog_title}">${blog_title}</a> + </h1> + <%block name="belowtitle"> + %if len(translations) > 1: + <small> + ${(messages[lang][u"Also available in"])}: + ${html_translations()} + </small> + %endif + </%block> + <ul class="unstyled"> + <li>${license} + ${html_social()} + ${html_sidebar_links()} + <li>${search_form} + </ul> + </div> + <div id="footer"> + ${content_footer} + </div> + </div> + ${analytics} + <script type="text/javascript">jQuery("a.image-reference").colorbox({rel:"gal",maxWidth:"80%",maxHeight:"80%",scalePhotos:true});</script> + </body> + +.. 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 <http://wp-themes.com/monospace/>`_, 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"></%block>`` + +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: + <div class="post"> + <h1><a href="${post.permalink(lang)}">${post.title(lang)}</a> + <small> + ${messages[lang]["Posted"]}: ${post.date.strftime(date_format)} + + </small></h1> + <hr> + ${post.text(lang, index_teasers)} + ${helper.html_disqus_link(post)} + </div> + % endfor + ${helper.html_pager()} + ${helper.html_disqus_script()} + </%block> + +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: + <div class="postbox"> + <h1><a href="${post.permalink(lang)}">${post.title(lang)}</a></h1> + <div class="meta" style="background-color: rgb(234, 234, 234); "> + <span class="authordate"> + ${messages[lang]["Posted"]}: ${post.date.strftime(date_format)} + </span> + <br> + <span class="tags">Tags: + %if post.tags: + %for tag in post.tags: + <a class="tag" href="${_link('tag', tag, lang)}"><span class="badge badge-info">${tag}</span></a> + %endfor + %endif + </span> + </div> + ${post.text(lang, index_teasers)} + ${helper.html_disqus_link(post)} + </div> + % 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"> + <div class="post"> + ${helper.html_title()} + <div class="meta" style="background-color: rgb(234, 234, 234); "> + <span class="authordate"> + ${messages[lang]["Posted"]}: ${post.date.strftime(date_format)} [<a href="${post.pagenames[lang]+'.txt'}">${messages[lang]["Source"]}</a>] + </span> + <br> + %if post.tags: + <span class="tags">${messages[lang]["Tags"]}: + %for tag in post.tags: + <a class="tag" href="${_link('tag', tag, lang)}"><span class="badge badge-info">${tag}</span></a> + %endfor + </span> + <br> + %endif + <span class="authordate"> + ${helper.html_translations(post)} + </span> + </div> + ${post.text(lang)} + ${helper.html_pager(post)} + ${helper.html_disqus(post)} + </div> + </%block> + +.. 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. + |