Blogging with jupyter notebooks and jekyll
One of the last parts before my full-fledged transition to github pages from wordpress was figuring out how to post nicely formatted jupyter notebooks. This was actually the reason I wanted to switch in the first place, but it turns out it wasn’t as straightforward as I’d hoped! I think I’ve found an acceptable, though imperfect, way to do this: here’s the general process I’ve settled on.
- Write the jupyter notebook in the
- When it’s finished,
jupyter nbconvert <nb> --to markdown
- Move it to the
- Move the images to the
/images/to all image paths in the markdown file
Some things I learned along the way:
Keep notebooks in a separate folder
The majority of my blog posts are me just writing things and thus just normal markdown files. At first, I was trying to troubleshoot my coding posts by putting the jupyter notebook in the
_posts folder. This ended up rendering the json under the notebook as the blog post, even if I converted the notebook to a markdown file. As long as the
.ipynb file was in there, that’s what was being processed and displayed by jekyll. One way to get around this is to include an exclusion for
*.ipynb files in the
config.yml file, as described in this helpful blog post. However, I confess that I don’t know all that’s going on my
config.yml file, and I didn’t really want to troubleshoot to figure out where that should go. Also, I think it will be nice to separate my coding posts from other, more text-based posts.
Convert to markdown
Thankfully, this is very easy with jupyter’s
nbconvert tool. A note that the markdown file name should have the same format as other blog posts, starting with
YYYY-MM-DD. Also, it seems that jekyll doesn’t need the header with the post metadata in order for the post to show up, but you may want to add that to your post.
Move the images
Here again, it’s probably possible to configure jekyll to look for images in the
_jupyter folder, where the
nbconvert command will have created a folder with all associated images. However, partially to avoid troubleshooting this and also partially to stay consistent with other images, I’m planning just to move the whole folder over to my
Fix image paths
This was the part that took me a bit to figure out, which is probably just because I really don’t know what’s going on under the hood. For the images to show up, you need to provide the full path to the image from the root directory of the repo. In my case, that means adding
/images/ to each image path, since that’s the folder that they’re all in.
Things I still need to fix
I don’t love how the code blocks are showing up - the text is too small and I don’t think the color highlighting is standard Python coloring. Also, my cell blocks are missing the In  and Out  execution counters, which I’d like to have show up. But for now, I think this is good enough. Maybe one day I’ll figure out where I can edit how these styles, perhaps starting from this blog post…