Computational Science and Data Science

Hans Fangohr

Blogging with the IPython Notebook

Read at the bottom of the post first for most recent updates.

Original entry from April 2014

After setting up this blog late in 2012 (using pelican), I have experimented with different ways of including IPython Notebooks in the blog.

Initially (late 2012), I converted the notebook to restructured text (using existing ipython notebook code), and added some custom parsing of notebook cells so that metadata information (such as publication date, tags, etc to be used by pelican) could be included in the notebook. I then extended the pelican.conf file to automatically carry out this conversion for all .ipynb files it can find.

This worked okay, but I was using custom code which I didn't tidy up sufficiently to want to inflict it on anybody, and which was difficult to keep up-to-date: pelican changed a little, and so did the notebook, and it difficult to re-install my setup. However, what I liked, was that I could include arbitrary restructured text commands in the notebook, and that pelican would run these through the normal restructuredtext parsing when it creates the html pages. This allowed to create, for example, a table of contents at the beginning of longer notebooks, using the normal restructuredtext .. contents:: tag. On the negative side, the metadata in the notebook may be undesired if the notebook is used outside the blogging context.

However, with the rapid pace of IPython and Pelican development, I have recently evaluated options again, and came across the nice blog entry from Jake VanderPlaas, which explains his transition from Octopress to Pelican, including the use of IPython notebooks for blogging.

I installed Jake's tools, and to make it all work quickly initially, I also used his pelican-octopress-theme. It looks nice and modern, so I kept it.

In this set up, I need to write my blog entries in Markdown (where in the past I preferred restructuredtext - but that's no big deal).

To include a notebook, I need to include a (liquid) tag such as

{ % notebook blogging-with-the-ipython-notebook-example.ipynb %}

and this will automatically convert the notebook and include it in the static webpage.

The metadata information is now not included in the notebook, but instead I have to write a 'normal' pelican markdown file to create a blog entry, and this includes the notebook. Of course the file could be empty other than including the notebook. So this is quite elegant, and I am happy with it.

I include an example notebook below. Other notebooks that are converted in this way are

The only thing I haven't figured out yet, is how to include a table of contents for a blog entry at the beginning of the blog entry - this is particularly useful for longish ipython notebooks.

Here is an example ipython notebook converted to a blog entry.

You can download this notebook.

Thanks to Jake, the IPython and Pelican team for making all this work.

Additional information on blogging with the IPython notebook:

Update 10 May 2015

The liquid tags extension is not yet working with IPython notebook 3. The easiest workaround I found was to install ipython-notebook 2.4.1 in a dedicated anaconda environment. At least it seemed easier than updating the liquid tags code.

Update 13 September 2016

Ignore the material above, and work through this blog entry:

This all works nicely, making use of the pelican-ipynb plugin.