You can convert Jupyter Notebooks into HTML documents to easily host and share on the web. See how to automate the process with Gatsby.

Everyone acquainted with data science knows that Jupyter Notebooks are the way to go. They easily allow you to mix Markdown with actual code, creating a lively environment for research and learning. Code becomes user-friendly and nicely formatted — write about it and generate dynamic charts, tables, and images on the go.

Writing Notebooks is so good that it is only natural to imagine that you might want to share them on the internet. Surely, you can host it in GitHub or even in Google Colab, but that will require a running kernel, and it’s definitely not as friendly as a good ol’ webpage.

Before we go any further, it’s important to understand that a Jupyter Notebook is nothing more than a collection of JSON objects containing inputs, outputs, and tons of metadata. It then constructs the outputs and can easily be converted into different formats (such as HTML).

Knowing that Notebooks can become an HTML document is all we need — what remains is finding a way to automate this process so a .ipynb file can become a static page on the internet. My solution to this problem is to use GatsbyJS — notably, one of the best static site generators out there, if not the single best.

Gatsby easily sources data from different formats — JSON, Markdown, YAML, you name it — and statically generate webpages that you can host on the world wide web. The final piece then becomes: instead of transforming Markdown into a post, do the same with a .ipynb file. The goal of this post is to walk you through this process.

Technical challenges

A quick search on the web will show you gatsby-transformer-ipynb. Basically, this is a Gatsby plugin that is able to parse the Notebook file in a way that we can access it later in our GraphQL queries. It’s almost too good to be true!

And, in fact, it is. The hard work was done by the fine folks of nteract. However, the plugin hasn’t been maintained in a while, and things don’t simply work out of the box — not to mention the lack of customization that one would expect from a plugin.

I’ll spare you the boring stuff, but after fussing around the dark corners of GitHub, and with significant help from this post by Specific Solutions, I managed to create my own fork of gatsby-transformer-ipynb, which solves my problems and will suffice for the purpose of this post.

Note, however, that I have no intention of become an active maintainer, and most of what I’ve done was solely to get what I need to work — use it at your own risk!

Enough with the preambles, let’s get to some code.

#gatsby #jupyter-notebooks #programming #developer #web-development