/
creating-a-pelican-powered-ipython-notebook-blog.html
243 lines (205 loc) · 13.2 KB
/
creating-a-pelican-powered-ipython-notebook-blog.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
<!doctype html>
<html lang="">
<head>
<meta charset="utf-8"/>
<title>Creating a Pelican powered iPython notebook blog - blog.mortenvp.com</title>
<meta name="author" content="Morten V. Pedersen">
<meta name="description" content="During the last couple of months I've started to use the iPython notebook for more and more stuff. Inspired by Python Perambulations by Jake VanderPlas, I decided to also try to use it for blogging. In the following I'll try to document how I've setup things. Tools ...">
<link rel="stylesheet" href="http://blog.mortenvp.com/theme/css/main.css" type="text/css" />
<link href="http://blog.mortenvp.com/feeds/all.atom.xml" type="application/atom+xml" rel="alternate" title="blog.mortenvp.com Atom Feed" />
<script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML" type="text/javascript"></script>
<script type="text/javascript">
init_mathjax = function()
{
if (window.MathJax)
{
// MathJax loaded
MathJax.Hub.Config(
{
tex2jax:
{
inlineMath: [ ['$','$'], ["\\(","\\)"] ],
displayMath: [ ['$$','$$'], ["\\[","\\]"] ]
},
displayAlign: 'left', // Change this to 'center' to center equations.
"HTML-CSS":
{
scale: 100,
styles: {'.MathJax_Display': {"margin": 0}, '.MathJax':{"font-size": "100%", "color": "black"}}
}
styles: {'.MathJax_Preview':{"font-size": "100%", "color": "black"}}
});
MathJax.Hub.Queue(["Typeset",MathJax.Hub]);
}
}
init_mathjax();
</script>
</head>
<body>
<div class="container">
<header role="banner">
<div class="feeds">
<a href="http://blog.mortenvp.com/feeds/all.atom.xml" rel="alternate"><img src="http://blog.mortenvp.com/theme/images/icons/feed-32px.png" alt="atom feed"/></a>
</div>
<a href="http://blog.mortenvp.com" class="title">blog.mortenvp.com</a>
</header>
<div class="wrapper">
<div role="main" class="content">
<article class="full">
<h1>Creating a Pelican powered iPython notebook blog</h1>
<div class="metadata">
<time datetime="2015-02-26T15:00:00" pubdate>Thu 26 February 2015</time>
<address class="vcard author">
by <a class="url fn" href="http://blog.mortenvp.com/author/morten-v-pedersen.html">Morten V. Pedersen</a>
</address>
in <a href="http://blog.mortenvp.com/category/misc.html">misc</a>
</div>
<p>
<div class="cell border-box-sizing text_cell rendered">
<div class="prompt input_prompt">
</div>
<div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>During the last couple of months I've started to use the iPython notebook for more and more stuff. Inspired by <a href="https://jakevdp.github.io/blog/2013/05/07/migrating-from-octopress-to-pelican/">Python Perambulations</a> by Jake VanderPlas, I decided to also try to use it for blogging. In the following I'll try to document how I've setup things.</p>
<h2 id="tools-involved">Tools involved</h2>
<ul>
<li><a href="http://getpelican.com">Pelican</a>: Pelican is a static site generator, written in Python.</li>
<li><a href="http://ipython.com">iPython</a>: What we will use to write our notebooks in.</li>
<li><a href="http://docker.com">Docker</a>: Container for the tools</li>
<li><a href="http://fabfile.org">Fabric</a>: Automates tasks like building and publishing the site.</li>
</ul>
<h2 id="installing-pelican">Installing Pelican</h2>
<p>On the GitHub README.md for the Pythonic Perambulations blog Jake VanderPlas recommonds using Pelican 3.3+. Fortunatly Ubuntu 14.10 ships with 3.4.0 (run: <code>sudo aptitude show python-pelican</code> to check). So installation is easy:</p>
<pre><code>sudo aptitude install python-pelican</code></pre>
<h2 id="hosting-the-site">Hosting the site</h2>
<p>Here I will again follow the approach taken by Jake VanderPlas for his <a href="http://jakevpd.github.io">Python Perambulations</a> blog.</p>
<p>The basic idea is to create two <a href="http://github.com">GitHub</a> reporitories. The first contains the Pelican project files, notebooks, and other material used when generating the site. The second contains the generated html files etc. With this approach we can use <a href="https://pages.github.com/">GitHub Pages</a> for the second repository to make the site available on the web.</p>
<p>The first repoitory I named <a href="https://github.com/mortenvp/mortenvp-pelican">mortenvp-pelican</a> and the second <a href="https://github.com/mortenvp/mortenvp.github.io">mortenvp.github.io</a> which according to the GitHub Pages documentation is the mandtory name for a personal pages repository.</p>
<h2 id="generating-the-initial-project">Generating the initial project</h2>
<p>In this case I just follow the Pelican <a href="http://docs.getpelican.com/en/3.5.0/quickstart.html">quickstart</a> section to setup a basic site.</p>
<pre><code>git clone <git-url-to-mortenvp-pelican.git>
cd mortenvp-pelican
pelican-quickstart</code></pre>
<p>The quick start will ask you a bunch of questions, these were my answers:</p>
<pre><code>Welcome to pelican-quickstart v3.4.0.
This script will help you create a new Pelican-based website.
Please answer the following questions so this script can generate the files
needed by Pelican.
> Where do you want to create your new web site? [.]
> What will be the title of this web site? blog.mortenvp.com
> Who will be the author of this web site? Morten V. Pedersen
> What will be the default language of this web site? [en]
> Do you want to specify a URL prefix? e.g., http://example.com (Y/n)
> What is your URL prefix? (see above example; no trailing slash) http://blog.mortenvp.com
> Do you want to enable article pagination? (Y/n)
> How many articles per page do you want? [10]
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n)
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n)
> Do you want to upload your website using FTP? (y/N)
> Do you want to upload your website using SSH? (y/N)
> Do you want to upload your website using Dropbox? (y/N)
> Do you want to upload your website using S3? (y/N)
> Do you want to upload your website using Rackspace Cloud Files? (y/N)
> Do you want to upload your website using GitHub Pages? (y/N) Y
> Is this your personal page (username.github.io)? (y/N) y
Done. Your new project is available at /home/mvp/dev/mortenvp-pelican</code></pre>
<h2 id="plugin-enabeling-ipython-notebooks">Plugin enabeling iPython notebooks</h2>
<p>Support for including an iPython notebook is available in the <a href="https://github.com/getpelican/pelican-plugins/tree/master/liquid_tags">Liquid-style Tags</a> plugin. Following the <a href="https://github.com/getpelican/pelican-plugins">README</a> in the Pelican Plugins we add the pelican-plugins repository as a submodule:</p>
<pre><code>git submodule add git@github.com:getpelican/pelican-plugins.git</code></pre>
<p>and activate the liquid-style Tags:</p>
<pre><code>PLUGIN_PATHS = ['pelican-plugins']
PLUGINS = ['liquid_tags.img', 'liquid_tags.video',
'liquid_tags.youtube', 'liquid_tags.vimeo',
'liquid_tags.include_code', 'liquid_tags.notebook']</code></pre>
<p>You can choose the location for the notebooks by specifying:</p>
<pre><code>NOTEBOOK_DIR = 'notebooks'</code></pre>
<h3 id="including-the-notebook-css-in-our-choosen-theme">Including the notebook CSS in our choosen theme</h3>
<p>At the top of the pelicanconf.py add:</p>
<pre><code>from __future__ import unicode_literals
import os</code></pre>
<p>Which enables us to use (copied from <a href="https://github.com/jakevdp/PythonicPerambulations/blob/master/pelicanconf.py">here</a>):</p>
<pre><code># The theme file should be updated so that the base header contains the line:
#
# {% if EXTRA_HEADER %}
# {{ EXTRA_HEADER }}
# {% endif %}
#
# This header file is automatically generated by the notebook plugin
if not os.path.exists('_nb_header.html'):
import warnings
warnings.warn("_nb_header.html not found. "
"Rerun make html to finalize build.")
else:
EXTRA_HEADER = open('_nb_header.html').read().decode('utf-8')
</code></pre>
<h2 id="choosing-a-theme">Choosing a theme</h2>
<p>I'm not a big fan of the default Pelican theme, so instead I chose to use the <a href="https://github.com/fle/pelican-sober">Pelican-sober</a> theme.</p>
<p>Since the <code>EXTRA_HEADER</code> section (as described above) isn't present in the Pelican-sober theme's <code>templates/base.html</code>, we need to add it. To do this I forked the repository to my user and made the changes there.</p>
<p>Once this is done we can use our chosen theme by editing the <code>THEME</code> variable in <code>pelican.conf</code> (read about this <a href="http://nafiulis.me/making-a-static-blog-with-pelican.html#themes">here</a>), so to summarize:</p>
<ol style="list-style-type: decimal">
<li>Select a theme and ensure that it has the <code>EXTRA_HEADER</code> section.</li>
<li>Add the theme git repository as a submodule to our site repository <code>git submodule add git@github.com:url-to-repo.git</code></li>
<li>Add a <code>THEME = 'pelican-sober'</code> vaiable inside <code>pelicanconf.py</code></li>
</ol>
<h2 id="adding-a-post">Adding a post</h2>
<p>Adding a post is pretty easy, create a simple markdown file with some basic tags. As an example <code>constent/first_post.md</code>:</p>
<pre><code>Title: My fist post
Date: 2015-02-26 15:00
# About
Here we can write the blog post using markdown</code></pre>
<h2 id="including-a-notebook">Including a notebook</h2>
<p>To include a notebook called <code>filename.ipynb</code> copy it to the <code>content/notebooks/</code> directory and add it to a post using:</p>
<pre><code>{% notebook filename.ipynb %}</code></pre>
<h2 id="generating-the-site">Generating the site</h2>
<p>I generate the site using <a href="http://docker.com">Docker</a> and <a href="http://fabfile.org">Fabric</a>.</p>
<h3 id="docker">Docker</h3>
<p>Initially when I wanted to generate the site I got and error <code>Incomplete format</code></p>
<p>Searching the web the error seems to be related to a Mardown <a href="https://github.com/getpelican/pelican-plugins/pull/321">issue</a> with the pelican pugin. The issue was resolved, however comments later indicated that it did not work for everybody, including me.</p>
<p>One user confirmed that the error occured with Markdown 2.5 and that downgrading to 2.4 solved the issue. To verify this fix I decided to install pelican and the dependencies in a Docker container to not interfer with the system packages already on my system.</p>
<p>The Docker container I created for this purpose is available <a href="https://registry.hub.docker.com/u/mortenvp/mortenvp-docker/">here</a>. The container is invoked using fabric described next.</p>
<h3 id="fabric">Fabric</h3>
<p>Is a tool that can be use to automate performing some tasks either on the local or a remote machine. The <code>pelican-quickstart</code> already creates a <code>fabfile</code> for generating and deploying the site. I just adapted it to use If you check the <a href="https://github.com/mortenvp/mortenvp-pelican/blob/master/fabfile.py">fabfile</a> in the <a href="https://github.com/mortenvp/mortenvp-pelican">repository</a> for this site you will see how I use the docker container to generate the content and then move it to the gihub.io repository.</p>
</div>
</div>
</div></p>
</article>
<p>
<a href="https://twitter.com/share" class="twitter-share-button" data-via="" data-lang="en" data-size="large" data-related="">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>
</p>
</div>
<div class="sidebar">
<div class="sidebar-container" >
<nav>
<h2>Categories</h2>
<ul>
<li class="active"><a href="http://blog.mortenvp.com/category/misc.html">misc</a></li>
</ul>
</nav>
<aside>
<h2>Social</h2>
<ul class="social">
<li><a href="#">You can add links in your config file</a><i></i></li>
<li><a href="#">Another social link</a><i></i></li>
</ul>
</aside>
<aside>
<h2>Blogroll</h2>
<ul>
<li><a href="http://getpelican.com/">Pelican</a></li>
<li><a href="http://python.org/">Python.org</a></li>
<li><a href="http://jinja.pocoo.org/">Jinja2</a></li>
<li><a href="#">You can modify those links in your config file</a></li>
</ul>
</aside>
</div>
</div>
</div>
<footer>
<p role="contentinfo">
Morten V. Pedersen - Proudly powered by <a href="http://alexis.notmyidea.org/pelican/">pelican</a>. Theme <a href="https://github.com/fle/pelican-sober">pelican-sober</a>.
</p>
</footer>
</div>
</body>
</html>