Setting up nikola with deployment to github pages

Installing nikola and its dependencies

In the post that follows I document my experience getting nikola setup.

For starters, nikola was my top choice for a static site generator as it:

  • Is open-source python
  • Accepts ipython (Jupyter) notebook as an input format
  • Automatically deploys to github pages, i.e. free hosting!

The instructions on nikola's Getting Started page went smoothly, with one hiccup:

Error: Cannot remove entries from nonexistent file d:\anaconda32\envs\tst\lib\site-packages\easy-install.pth

I'm using ContinuumIO's Anaconda as my package manager, and a bug which is documented here causes any package relying on setuptools to fail, as Anaconda doesn't use easy install. The workaround was simply enough:

pip install --upgrade --ignore-installed "Nikola[extras]"

And with that setuptools is installed and the bug is fixed for the lifetime of that particular conda environment.

Configuring nikola for input from IPython Notebook

You want to be able to run:

nikola new_post -f pynb

in order to create your ipython notebook based blog post. If you try and do that off that bat, you'll get an error saying that the ipynb format hasn't been added to POSTS and PAGES tuples in your file. Initially I was following this post, but it seems that default nikola installation has changed slightly. In particular I only had to the following tuples to the POSTS and PAGES lists, respectively:

("posts/*.ipynb", "posts", "post.tmpl", True),

("stories/*.ipynb", "stories", "story.tmpl", False),

You can leave the default theme as bootstrap3, as this supports the ipython notebook format. With that, I was able to create my ipython NB blog posts and view them locally with nikola serve --browser

Deploying to github pages

I went with the simplest possible setup, which github really does make breathtakingly simple!

  1. Create a repo called and bam, you've got free static site hosting. From there simply upload your site contents (as generated by nikola in this case) to the master branch and visit enter for a pleasant reception.
  2. Follow these instruction from within your nikola site's directory to init and push the empty master branch.
  3. Run nikola github_deploy - and that's it!
In [ ]:


Comments powered by Disqus