Ir al contenido principal

Ralsina.Me — El sitio web de Roberto Alsina

Creating a Theme for Nikola From Scratch (almost)

The­re is so­me do­cu­men­ta­tion about crea­ting the­mes for Niko­la, but ma­y­be a tu­to­rial is al­so a use­ful way to ex­plain it. So, he­re it is. I'­ll ex­plain how to crea­te a the­me (al­mos­t) from scra­tch. Al­ter­na­ti­ve­l­y, you can take an exis­ting the­me and mo­di­fy on­ly par­ts of it via inhe­ri­tan­ce, but tha­t's for ano­ther do­cu­men­t.

I wi­ll try to crea­te a the­me that looks like Vi­ni­cius Ma­s­su­che­tto­'s Mo­nos­pa­ce The­me.

Starting The Theme

Firs­t, we crea­te a tes­ting si­te, and co­py the or­phan the­me from niko­la's sour­ces in­to the ri­ght pla­ce:

$ 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 al­ready build and test the si­te:

$ nikola build && nikola serve
//ralsina.me/galleries/random/monospace-1.png

This is the al­most com­ple­te­ly uns­ty­led "or­phan" the­me.

Of cour­se, the pa­ge la­yout is com­ple­te­ly bro­ken. To fix tha­t, we need to get in­to tem­pla­tes.

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:

## -*- 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"])}:&nbsp;
            ${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.

Mo­nos­pa­ce is a two­-­co­lum­n-wi­th-­footer la­you­t, so le­t's co­py the ba­si­cs from its HT­ML and see what ha­ppen­s:

## -*- 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"])}:&nbsp;
                ${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>
//ralsina.me/galleries/random/monospace-2.png

Yikes!

This wi­ll get be­tter qui­ck­ly on­ce we add so­me 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:

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 wi­ll (a­fter we re­build it) make the si­te looks di­ffe­rent of cour­se, and ge­tting clo­ser to our goa­l:

//ralsina.me/galleries/random/monospace-3.png

Mo­nos­pa­ced all­ri­gh­t.

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 na­me="­con­ten­t"></%­blo­ck>

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:

## -*- 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>&nbsp;&nbsp;
            ${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, le­t's tweak that to be clo­ser to the ori­gi­na­l. We put the pos­t's me­ta­da­ta in a bo­x, add li­nks for the pos­ts tags, mo­ve the da­te the­re, etc.

## -*- 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:&nbsp;
                    %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()}
//ralsina.me/galleries/random/monospace-4.png

Clo­se enou­gh!

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.

## -*- 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"]}:&nbsp;
                %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>
//ralsina.me/galleries/random/monospace-5.png

De­tail­s, de­tail­s.

The de­mo si­te exer­ci­ses most of the fea­tu­res in Niko­la, so if you make it look good, your si­te pro­ba­bly wi­ll look good too. This mo­nos­pa­ce the­me is in niko­la's gi­thub mas­te­r, if you want to use it or play wi­th it.

dAnjou / 2012-12-29 01:19:

Is it responsive?

Roberto Alsina / 2012-12-29 02:07:

No, it's just a very basic theme.

Chris Warrick / 2013-01-03 16:45:

> /nikola/nikola/nikola/

Mind explaining your directory structure?

Roberto Alsina / 2013-01-03 16:52:

There is a projects folder (~/Desktop/proyectos) then there is a folder "nikola", where I have all nikola branches and releases and random things, then the master checkout is called "nikola" because that's what happens if you do what github says to checkout, then inside it there is a "nikola" folder because the python package is called that. Thus "nikola/nikola/nikola"

I could change it to nikola/master/nikola but there are a bunch of scripts that do things like pulling the docs into the website when I do a release and it would be more annoying to have to edit those.


Contents © 2000-2020 Roberto Alsina