-
Notifications
You must be signed in to change notification settings - Fork 0
/
pelican-a-static-blog-generator-for-pythonistas.html
252 lines (215 loc) · 13.3 KB
/
pelican-a-static-blog-generator-for-pythonistas.html
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
<!DOCTYPE html>
<html lang="en">
<head>
<link href='http://fonts.googleapis.com/css?family=Noticia+Text:400,700' rel='stylesheet' type='text/css' />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title> Pelican: a static blog generator for Pythonistas | fjavieralba.com </title>
<link rel="stylesheet" href="./theme/css/style.css" type="text/css" />
<link rel="stylesheet" href="./theme/css/pygments.css" type="text/css" />
<link rel="stylesheet" href="./theme/css/font-awesome.css" type="text/css"/>
</head>
<body>
<div class=container>
<!--div class=header>
<a href="./pages/about-me.html">F. Javier Alba</a>'s Page
</div-->
<div class=navigation>
<ul>
<li><a href="./index.html">Blog</a> </li>
<li><a href="./archives.html">Archive</a></li>
<li><a href="./tags.html">Tags</a> </li>
<li><a href="./pages/projects.html">Projects</a> </li>
<li><a href="./pages/talks.html">Talks</a></li>
<li><a href="./pages/about-me.html">About</a> </li>
</ul>
</div>
<div class=separator></div>
<div class=body>
<h1 class="title"> Pelican: a static blog generator for Pythonistas</h1>
<p class=date> 30 March 2012 </p>
<p>Hi!</p>
<p>I would like to start this blog speaking about <a class="reference external" href="http://blog.notmyidea.org/pelican-a-simple-static-blog-generator-in-python.html">Pelican</a>, a nice Python project initiated by <a class="reference external" href="http://notmyidea.org/">Alexis Metaireau</a> that allows you to generate a complete static blog/site from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> Templates.</p>
<p>Why would you do that? <em>First</em>: for pythonic fun. <em>Second</em>: because of the <strong>static</strong> part: all your site will be a bunch of static files (HTML, CSS...). This could sound a bit strange but I think is a good way to go if you want a simple blog or personal web. It helps keeping it simple. In addition, it makes easy to host your page for free, even maintaining your own domain name.</p>
<p>But don't get me wrong, you will have all you would expect from a blog site, including comments, socialize-buttons, pagination, tags, categories etc.</p>
<div class="section" id="restructuredtext">
<h2>reStructuredText</h2>
<p>But, what a reStructuredText (rst) template looks like?</p>
<p>A blog entry would be as simple as the following text:</p>
<div class="highlight"><pre><span class="gh">Title of a post</span>
<span class="gh">###############</span>
<span class="nc">:category:</span> <span class="nf">programming</span>
<span class="gh">Subtitle</span>
<span class="gh">--------</span>
Hi!
This is my first rst post!
And this is a link to a page_
<span class="p">..</span> <span class="nt">_page:</span> http://moliware.com/
</pre></div>
<p>reStructuredText is part of <a class="reference external" href="http://docutils.sourceforge.net/">docutils</a>, a powerful and open-source text processing system written in Python.</p>
<p>In an <tt class="docutils literal">rst</tt> file you can specify links, insert images, code snippets and many other things. <a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickref.html">Here</a> you have a good overview of all its functionalities.</p>
<p>As you may know, it's mainly used for generating documentation. For example, with <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a> you write your <tt class="docutils literal">rst</tt> files once and then you can generate your documentation in multiple formats like PDF of HTML.</p>
</div>
<div class="section" id="installing-pelican">
<h2>Installing Pelican</h2>
<pre class="literal-block">
$ pip install pelican
</pre>
<p>If you're curious, you can review its code and clone the <a class="reference external" href="https://github.com/ametaireau/pelican">github repository</a>.</p>
</div>
<div class="section" id="creating-a-site-blog">
<h2>Creating a site/blog</h2>
<p>Once installed, to create a new site, create a new folder and type:</p>
<pre class="literal-block">
$ pelican <my_folder_path>
</pre>
<p>This command will generate an <tt class="docutils literal">output</tt> folder with an entire blog site with the default content.
If you open the <tt class="docutils literal">index.html</tt> file inside <tt class="docutils literal">output</tt> you will see something similar to:</p>
<img alt="images/pelican_default.png" class="align-center" src="static/images/pelican_default.png" />
</div>
<div class="section" id="writing-posts">
<h2>Writing posts</h2>
<p>To start writing posts, do the following:</p>
<ul class="simple">
<li>Inside your site folder, create a new folder that will contain your rst sources:</li>
</ul>
<div class="highlight"><pre><span class="nv">$ </span><span class="nb">cd</span> <my_folder_path>
<span class="nv">$ </span>mkdir rst
</pre></div>
<ul class="simple">
<li>Create an rst file inside that directory with an example post:</li>
</ul>
<div class="highlight"><pre><span class="nv">$ </span>vim my_first_post.rst
</pre></div>
<div class="highlight"><pre><span class="gh">Starting with Pelican</span>
<span class="gh">#####################</span>
<span class="nc">:date:</span> <span class="nf">2012-03-30 23:47</span>
<span class="nc">:category:</span> <span class="nf">programming</span>
<span class="nc">:tags:</span> <span class="nf">python, blog, rst, pelican</span>
<span class="nc">:author:</span> <span class="nf">F\. Javier Alba</span>
<span class="nc">:excerpt:</span> <span class="nf">This is an excerpt of my post.</span>
<span class="gh">Introduction</span>
<span class="gh">------------</span>
Hi!
This is my first rst post!
And this is a link to a page_
<span class="p">..</span> <span class="nt">_page:</span> http://moliware.com/
</pre></div>
<ul class="simple">
<li>Now, run pelican indicating your rst directory:</li>
</ul>
<div class="highlight"><pre><span class="nv">$ </span>pelican rst/
</pre></div>
<ul class="simple">
<li>Open <tt class="docutils literal"><span class="pre"><my_folder_path>/output/index.html</span></tt> and you will see your post in html format:</li>
</ul>
<img alt="images/first_post.png" class="align-center" src="static/images/first_post.png" />
</div>
<div class="section" id="writing-pages">
<h2>Writing pages</h2>
<p>Pelican also support regular pages.</p>
<p>Imagine you want an "About" page apart from your blog posts.</p>
<p>All you have to do is create a <tt class="docutils literal">pages</tt> folder and create a new rst file with your page content:</p>
<div class="highlight"><pre><span class="nv">$ </span>mkdir <my_folder_path>/rst/pages
<span class="nv">$ </span><span class="nb">cd</span> <my_folder_path>/rst/pages
<span class="nv">$ </span>vim about.rst
</pre></div>
<div class="highlight"><pre><span class="gh">About me</span>
<span class="gh">########</span>
<span class="nc">:date:</span> <span class="nf">2012-03-30 23:47</span>
<span class="nc">:author:</span> <span class="nf">F\. Javier Alba</span>
This is an about page!
</pre></div>
<p>Run again the pelican script against your sources and it will generate also the new page:</p>
<img alt="images/page.png" class="align-center" src="static/images/page.png" />
</div>
<div class="section" id="configuring-your-blog">
<h2>Configuring your blog</h2>
<p>The <tt class="docutils literal">Pelican</tt> command optionally accepts a configuration file to customize some parts of your blog.</p>
<p>E.g: date formats, pagination, disqus comments, Twitter integration... all these aspects and several more can be configured in a python configuration file.</p>
<p>The following is an example of a Pelican configuration file:</p>
<div class="highlight"><pre>DEFAULT_CATEGORY = 'Uncategorized'
TWITTER_USERNAME = 'fjavieralba'
PDF_GENERATOR = False
REVERSE_CATEGORY_ORDER = True
LOCALE = ""
DEFAULT_PAGINATION = 10
FEED_RSS = 'feeds/all.rss.xml'
CATEGORY_FEED_RSS = 'feeds/%s.rss.xml'
SOCIAL = (('twitter', 'http://twitter.com/fjavieralba'),
('linkedIn', 'http://es.linkedin.com/in/fjavieralba/en'),
('github', 'http://github.com/fjavieralba'),)
# static paths will be copied under the same name
STATIC_PATHS = ["images"]
</pre></div>
<p>To tell pelican to use your configuration file simply run the command with the -s option:</p>
<div class="highlight"><pre><span class="nv">$ </span>pelican rst/ -s <CONF_FILE>
</pre></div>
<p>You can see more details about pelican configuration in <a class="reference external" href="http://pelican.readthedocs.org/en/2.8/index.html">the officcial Pelican documentation</a></p>
</div>
<div class="section" id="extending-pelican">
<h2>Extending Pelican</h2>
<p>If you have some coding skills or are used to web templates engines like <a class="reference external" href="http://jinja.pocoo.org/">Jinja</a>, you will find it easy to extend and adapt Pelican to fit your needs.</p>
<div class="section" id="modifying-default-themes">
<h3>Modifying default themes</h3>
<p>We have been using the default theme. But what if you want to customize a little bit more the look and feel of your blog?</p>
<p>One way of customization is via configuration file. But if you want to go further, you can directly change your theme files.</p>
<p>Themes usually consist in two parts: the <tt class="docutils literal">templates</tt> folder and the <tt class="docutils literal">static</tt> folder.
<tt class="docutils literal">static</tt> usually contains CSS files, images, etc. and <tt class="docutils literal">templates</tt> contains .html files that are actually <a class="reference external" href="http://jinja.pocoo.org/">Jinja</a> templates. Experimenting a bit and changing the CSS styles or templates of an existing template is sometimes all you need to personalize your new blog.</p>
<p><a class="reference external" href="https://github.com/ametaireau/pelican-themes">In this Github repo</a> you can find all the "officcial" Pelican themes.</p>
</div>
<div class="section" id="creating-your-own-theme">
<h3>Creating your own theme</h3>
<p>If you have a clear idea of how your site should be and look like, you can also create your own theme.</p>
<p>It's a good idea to start from a existing one. Again in the <a class="reference external" href="http://pelican.readthedocs.org/en/2.8/themes.html">project documentation page</a> you have more details on how to do that.</p>
<p>In fact, this blog is a Pelican site based on a theme I created (miserably copying the look and feel of <a class="reference external" href="http://lucumr.pocoo.org/">Armin Ronacher's blog</a>)</p>
</div>
<div class="section" id="deploying-your-site-to-heroku-or-github-pages-for-free">
<h3>Deploying your site to Heroku or Github Pages for free</h3>
<p>One of the advantages of having an static blog (apart from being the most modern of your colleagues) is that t
it's easy to host your blog/site for free.</p>
<p>Github Pages has a nice tutorial on how to do it with any Github repository.</p>
<p>You could also take advantage of the "free dino" that Heroku provides to serve your site. In only requires an <a class="reference external" href="http://kennethreitz.com/static-sites-on-heroku-cedar.html">easy extra step</a>.</p>
</div>
</div>
<div class=twitter>
<a href="https://twitter.com/share" class="twitter-share-button" data-via="fjavieralba">Tweet</a>
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
</div>
<p class=tags>This entry was tagged as
<a href="./tag/blog.html">blog</a>
<a href="./tag/rst.html">rst</a>
<a href="./tag/pelican.html">pelican</a>
</p>
</div>
<div class=footer>
<p>© Copyright 2012 by <a href="./pages/about-me.html">F. Javier Alba </a> </p>
<p> Powered by <a href="http://pypi.python.org/pypi/pelican/" target="_blank">Pelican</a></p>
<p>
License: <a href="http://creativecommons.org/licenses/by-nc-sa/3.0/">Creative Commons
attribution-noncommercial-sharealike License.</a>
</p>
<p>
Feeds: <a href="./feeds/all.rss.xml" rel="alternate" title="Recent Blog Posts">RSS</a>,
<a href="./feeds/all.atom.xml" rel="alternate" title="Recent Blog Posts">Atom</a>
</p>
<p>
<div class=social style="font-size: 27px;">
<ul>
<script language="JavaScript">
u = 'me';
s = 'fjavieralba.com';
document.write('<a href=\"mailto:' + u + '@' + s + '\" target=\"_blank\">');
</script>
<li><i class="icon-envelope icon-large"></i> </li>
</a>
<a href="http://twitter.com/fjavieralba" target="_blank"> <li> <i class="icon-twitter-sign icon-large"> </li></i> </a>
<a href="http://es.linkedin.com/in/fjavieralba/en"><li><i class="icon-linkedin-sign icon-large" ></i></li></a>
<a href="http://github.com/fjavieralba" target="_blank"> <li> <i class="icon-github-sign icon-large"></i> </li> </a>
<!--a href="https://plus.google.com/101878412015087797011">google+</a-->
</ul>
</div>
</p>
</div>
</div>
</body>
</html>