This post was written in a Jupyter Notebook. Here’s how I got it onto my Jekyll website.

Download code: Venture here and download the following GitHub gists (thanks to cscorley and tgarc for putting these together): jekyll.py and jekyll.tpl.

  • I put the jekyll.py file in my GitHub pages folder (i.e. ~/username.github.io/). Make sure you read the comments and update the settings where appropriate.
  • The jekyll.tpl file is a template file that we’ll give to Jupyter to convert our notebook, so put it somewhere you put your Jupyter templates.

Create and convert your notebook: Go over to your ~/username.github.io/_posts folder and fire up Jupyter:

~/username.github.io/_posts $ jupyter notebook

Once you’re finished writing your notebook, save it, then convert it using the jekyll.tpl template:

~/username.github.io/_posts $ jupyter nbconvert --to markdown
<notebook_filename>.ipynb --config ../jekyll.py

Mind your filename: Jekyll needs your post markdown files named in a specific way in order to pick them up to build, i.e. “YYYY-MM-DD-title-of- blogpost.md”. If you name your notebook with that in mind (e.g. “2017 07 04 How to Publish Jupyter Notebooks to Your Jekyll Static Website”), it will automatically be in the right file name format when you convert it. Once your finished editing just update the title of the post in the markdown file.

Move images: When Jupyter converts the notebook, it saves images into a sub- directory of the current directory (in our case, _posts/). Unfortunately there is a bug in Jekyll that throws an exception if it finds a .png file in the _posts folder (read about the issue here). Pratically that means you have to cut+paste the images that were saved in the sub-directory into the ~/username.github.io/images/ folder. If this issue gets fixed that shouldn’t be a problem anymore and the jekyll.py code can be updated to point to the saved images in the sub-directory.

Final Steps: After you’ve converted your notebook to jekyll markdown, it’s time to build. Before you do, go into the markdown and make any final changes, such adjusting the post title or turning comments on (here’s how you can add disqus to your site]. Also make sure that the images have been moved so that the .png files don’t throw an error when you build. Once everything looks good, run jekyll build and the html files will be generated.

Example

In [1]:

# Normal Distribution
import numpy as np
import matplotlib.pyplot as plt
%matplotlib inline

In [2]:

plt.hist(np.random.normal(size=100000), bins=30)
plt.show()

png