forked from pabluk/nikola
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathcreating-a-theme.txt
287 lines (235 loc) · 10.9 KB
/
creating-a-theme.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
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 --demo 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 list 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"/>
<%namespace name="disqus" file="disqus_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)}
${disqus.html_disqus_link(post.permalink()+"#disqus_thread", post.base_path)}
</div>
% endfor
${helper.html_pager()}
${disqus.html_disqus_script()}
</%block>
.. 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"/>
<%namespace name="disqus" file="disqus_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)}
${disqus.html_disqus(post.permalink(absolute=True), post.title(lang), post.base_path)}
</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.