Turning ripples into waves

Building this blog

People often ask me: How can I can build a blog similar to this one? What tools are you using? What is IPython notebook role in your blog?

If you are familiar with Pelican and want to jump ahead before reading the whole post, check out the blog code repository and have fun.

If you never used a static site generator like Pelican before keep reading.

Blog environment

Your Blog will be around a while (hopefully), but most of the tools used to build it are evolving and changing very quickly. In order to avoid future headaches I use a distinguish work environment every time I create a new web-page/blog. "Freezing" the tools I use for that particular project.

To accomplish that I use virtualenv to compartmentalize the environments, and virtualenvwrapper to manage the virtualenvs.

You can install both using your distro package manager (or with any other python package installer out there: easy_install, pip, conda etc). In my OpenSUSE box I just use zypper,

sudo zypper in python-virtualenvwrapper

and all the dependencies will be installed as well.

virtualenvwrapper extends virtualenv with the several commands, but I use just these three:

  • mkvirtualenv to create a new virtualenv;
  • workon to enter the virtualenv;
  • deactivate to exit the virtualenv.

The command to create the blog environment is

mkvirtualenv --distribute --no-site-packages blog

and to enter the environment,

workon blog

My environment is "frozen" following this requirements.txt, to get an environment identical to mine you need to download the file and install all the modules listed in there with pip:

pip install -r requirements.txt

Note that you do not need to be root to install inside the virtualenv. However, you do need to be inside the virtualenv.

Check if everything installed correctly by typing pip freeze and comparing with the original requirements.txt.

The blog environment is almost ready. There are only two other dependencies missing the theme and the plug-ins. Download them using git:

git clone
git clone

There are several other themes and plug-ins for pelican. I suggest you check them out. Just be aware that, if you are not using the octopress-theme, you must insert the _nb_header.html manually inside your theme style. That is necessary to display the IPython notebooks properly. More information on how to do this in Jake's blog.

The blog

Now there are two options to proceed:

  1. Clone my current blog and start from there;
  2. Start a new one using pelican-quickstart.

If you choose option 2 to start from scratch I recommend taking a look at both and from my repository. Here I will demonstrated the first option.

git clone

Now change into the python4oceanographers directory, modify path variable to point to where you cloned pelican-octopress-theme and pelican-plugins.

path = os.path.join(os.environ.get('HOME'), 'BLOG')
THEME = '%s/pelican-octopress-theme' % path
PLUGIN_PATH = '%s/pelican-plugins' % path

Compiling the blog

You can use make clean (or manually delete the output folder) to get a clean slate, and make html to generate a new output folder.

If everything is OK enter the output folder and type python -m SimpleHTTPServer 8080 to start serving the blog locally. Open your browser at http://localhost:8080 and check the results.

So far you should have a clone of my current blog.

The blog work flow

Pelican posts are just Markdown files with a date and a subject like If you look inside my files you will notice that I just write a minimal header like,

title: Building this blog
date:  2013-12-23 12:34
comments: true
slug: blog

{% notebook blogging.ipynb cells[1:] %}

and the actual post is an IPython notebook file converted from JSON to HTML using the liquid tags plug-in.

It is time to create your own posts. Just delete all the Markdown and ipynb files inside the content folder, create a new Markdown and corresponding ipynb file for your new post. Keep using make html+python -m SimpleHTTPServer 8080 to visualize the final format in your browser.

Once you are satisfied with the results use make deploy to publish at github. (Remember that you must edit the Makefile first to point to your page.)

If you are interested in alternatives to blog with IPython notebooks check:

Now go ahead and start your own blog! Create a github repository for your page, adapt the configuration to your needs and Good Luck!

In [2]:

This post was written as an IPython notebook. It is available for download or as a static html.

Creative Commons License
python4oceanographers by Filipe Fernandes is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
Based on a work at