Blog with Nikola and Github: setup and workflow

Github blog with Nikola and Jupyter notebooks - setup and workflow

Setting up the github blog and creating a first post with Nikola was surprisingly easy, after having struggled with some alternatives. As easy as it was to set up, it is also easy to forget a few intricacies (although it really isn't that complicated) between one post and the next, a couple of weeks later. So here a short reminder on how to set Nikola up for Github and Jupyter notebooks, and how to post something new. It is assumed that there is already a Github account set up with a repository for your personal page.

There are several articles on the subject that might also be helpful, but they somehow didn't quite contain all my issues with Python (Anaconda), git and Nikola in one. So here it goes:

1. Getting started: Python environment, installing packages and Nikola, starting the git repo

This first part is rather dependent on setup and is documented more completely in various other places, such as the nikola site. Nevertheless, especially if you have Anaconda, the following could be useful.

Nikola has quite a few dependencies that are possibly different from those for everyday Python work. So it makes sense to create a new environment. This is easy with conda (I chose a prompt ending with # because of a conflict with the dollar sign within markdown quotations. I didn't actually do these commands as root, neither should you have to). By default, my conda installation will create Python 3.5, which is what we need.

user@macbook:~/Projects/ conda create --name blog
user@macbook:~/Projects/ source activate blog

Conda offers a possibility to copy an environment (using conda list --explicit) but this doesn't work cross-platform (I already had an environment set-up on Linux and wanted to have the same on my Mac. Alas.).

Using the list of commands outlined here (NB: check it if you start from scratch and also need to set up a Github account), one installs some necessary packages and Nikola with pip. But not before we have installed pip itself in our new environment:

(blog)user@macbook:~/Projects/ which pip 

Not located in our environment, so install pip first:

(blog)user@macbook:~/Projects/ conda install pip

That looks better. Now we can install in our environment with pip (NB: from now on, omitting the path and prompt):

pip install nikola pyzmq tornado jinja2 requests sphinx markdown ghp-import2

Upgrade nikola with extras, as recommended on the nikola site

pip install --upgrade "Nikola[extras]"

One thing is still missing: the Jupyter notebook, which adds a rather long list of more packages. Install with conda:

conda install notebook

In my most recent case, I did a git clone into my directory because I already had a Github repo with Nikola. Typically, you will first do a nikola init mysite, and add and commit this to a repo, and set a github location as your remote. I am using it for a personal page, so have the following remote:<user>/<user>

See here for some more hints with respect to the git repo. And I liked this post a lot too.

There is something important to keep in mind with the git repo: there is a source branch (src) and a branch where the HTML will be located, in this case master (for project pages this can be a directory "/docs" inside branch master or directly in a branch gh-pages).

A second thing related to git: make sure there is a .gitignore file as described in the nikola handbook. Fixing conflicts with files in /cache is no fun.

To see the file structure of what will be published on the site, do:

git checkout master

This will show an index.html, a directory blogs and several more site-related things. Going back to the src branch with:

git checkout src

you will see a file for Nikola, plus a bunch of other stuff.

By now, we have a Python environment with all necessary packages including Nikola, and a git repository that is linked to our personal Github repo

2. Adding a Jupyter notebook file as a post

Let's make the new post with a Jupyter notebook:

nikola new_post -f ipynb

Open the Jupyter console and navigate to the created, empty notebook.

jupyter notebook posts/new_post.ipynb

Now the actual fun starts: you can write text, equations (using the magic command %%latex) and of course Python code, including plots if you make them. This post was also written in a Jupyter notebook. You can see how your post is progressing, by telling nikola:

nikola auto -b

When you are done, save the notebook as you want it to appear. We haven't given any tags yet to the notebook, but that can easily be done now. For this post, I did:

nikola tags --add "nikola, conda, jupyter notebook" posts/blog-with-nikola-and-github-setup-and-workflow.ipynb

Note that this modifies your notebook file (metadata). Also note that if one desires to keep a post hidden from the public (for instance, when deploying the site when there is a post that is still under construction), it can be given the tag private. This can of course later be removed by nikola tags --remove

The last action: deploy the post on Github. Here, Nikola really shines by simplicity.

nikola github_deploy

Additional notes:

  • Jupyter notebooks support inline math using \$ . \$ . This doesn't work automatically for Nikola. The file contains some lines that need to be commented out (search for mathjax to find those lines).