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:
-
a related post commenting on how to modify the style file for this theme.
-
Just today, the question of blogging with the IPython Notebook was discussed on the IPython-dev mailing list, providing other useful pointers.
-
Building this (pelican/ipython) blog python4oceanographers
-
Introduction to Blogging with Pelican by Oliver Laslett
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:
https://www.dataquest.io/blog/how-to-setup-a-data-science-blog/
This all works nicely, making use of the pelican-ipynb plugin.