A quick meta-tutorial on how to setup a blog that will be generated from iPython notebooks (and including LaTex!). You should end with not only a finished product but a workflow for running a blog.

Why Jekyll?

I started using Jekyll because of its integration with iPython and the ease of including LaTex. It takes Markdown (.md) files, which can be generated by iPython, and parses them into what you see now. It also is compatible with GitHub Pages, and so it can be hosted from your account (as mine is). Jekyll is a static site generator and very minimalist compared to a blogging engine. In fact, it’s not considered a blogging engine at all. It however is used this way and I’m going to go through the easiest way to get a blog together using Jekyll.

Why this post?

Jekyll has been talked about a lot on the internet, but there are relatively few posts connecting the dots from start to finish. Some people have written scripts to convert iPython notebooks to Jekyll-ready Markdown, but they’re still not completely automated. I’m going to give you a manual approach which will give you an idea of the process so you can automate it yourself, if you’d like.

Installation

Setting up a Jekyll blog on GitHub

Jekyll can be tricky to install to the uninitiated. The easiest way is to fork the excellent Jekyll Now. The instructions are on the site. This gives you an out-of-the-box blog-like website ready to go with the file system necessary for Jekyll in place.

Note: The instructions say that once you do your first commit the page will be rebuilt and available to see. This is usually true, but it still took around 10 minutes for my blog to show up the first time.

Now, once you commit files in the appropriate folder, Jekyll will re-parse your site, regenerate all the pages, and they’ll be posted to your blog.

Installing Jekyll on your machine for local testing

The next thing you’ll want to do is clone your new repo after you’ve got it running from the instructions from the repo. Now, wouldn’t it be nice if you could make changes locally, spin up a server, and see the changes before pushing them? Well, you can– we just have to install Jeckyll locally. On Windows, you have to install Ruby, the DevKit, and then use gem to install Jekyll. You can get more details here. You will want it installed locally so you can spin up a server and see your page before you publish it online. When you want to see your blog locally, run “jekyll serve” in the base directory you cloned, and then go to the address http://127.0.0.1:4000/.

Workflow of an iPython Blog with Jekyll

The basic workflow gives you an idea of the process

Create an iPython Notebook and save it to Markdown
Add syntactic sugar (code highlighting, layout, LaTex)
Test locally
Push to GitHub

We’ll now go into details of step two.

Making an iPython Markdown file to blog ready

When you save an iPython file to Markdown, it’s almost ready to go– but there are a few changes you have to make to make it usable.

Add a layout

If you serve it up with Jekyll, you’ll notice it looks like a very plain HTML page without CSS. What gives? Well, in fact, it currently is only a bland HTML page without CSS. The first thing we have to do is attach our layout to the page by adding the following line to the top of the page:

---
layout: page
---

Now, if you run “jekyll serve” in the base directory, it should look more like your layout.

Code highlighting

Another pesky issue is syntax highlighting. Your Python code won’t be highlighted at this point (again, I’m assuming you’re using iPython, and in particular, Python). The “highlighter” is on by default in Jekyll Now which uses Rouge to highlight the code. To activate this, you can highlight tag embedded in the Liquid syntax. So you’ll simply have to wrap your indented code with some

{% highlight python linenos %}
	[Code here]
{% endhighlight %}

This will also put line numbers in your code.

Images

If you had used any images in your notebook you’ll have to move those as well and update the references in the Markdown code.

LaTex

I chose to use MathJax to render the LaTex. It’s pretty simple. First, in the _layout folder, add the line

to the top of the page.html template. Now you’ll be able to put LaTex on your page, but there’s a caveat on the syntax.

Your blog does not recognize the inline $’s out of the box. However, you can also use the following

# Not rendered
$ x+1 $ 

# Inline
$$ x+1 $$ 
\\( x+1 \\) 

# Block equation
\begin{equation}
x+1
\end{equation} 

Scott Rome

Blogging with iPython using Jekyll

Table of Contents