Entertainment at it's peak. The news is by your side.

Converting Jupyter Notebooks into Blog Posts with Gatsby


This text used to be first and predominant posted within the LogRocket weblog.

Converting Jupyter Notebooks Into Blog Posts With Gatsby

Each person acquainted with data science is conscious of that Jupyter Notebooks are the skill to head. They without considerations mean it’s doubtless you’ll mix Markdown with precise code, developing a active atmosphere for research and discovering out. Code turns into shopper-optimistic and properly formatted — write about it and generate dynamic charts, tables, and photos on the stride.

Writing Notebooks is so trusty that it’s miles most efficient natural to take into consideration that that it’s doubtless you’ll are searching to fragment them on the earn. Absolutely, it’s doubtless you’ll host it in GitHub or even in Google Colab, nonetheless that will require a running kernel, and it’s positively no longer as optimistic as a trusty ol’ webpage.

Sooner than we stride any extra, it’s important to know that a Jupyter Notebook is nothing bigger than a series of JSON objects containing inputs, outputs, and heaps of metadata. It then constructs the outputs and can without considerations be remodeled right into a form of codecs (equivalent to HTML).

Colorful that Notebooks can develop into an HTML doc is all we need — what stays is discovering a blueprint to automate this assignment so a .ipynb file can develop into a static web page on the earn. My resolution to this misfortune is to make exercise of GatsbyJS — particularly, one in all the finest static set aside generators available, if no longer the one simplest.

Gatsby without considerations sources data from a form of codecs — JSON, Markdown, YAML, you name it — and statically generate webpages that it’s doubtless you’ll host on the area-huge-web. The profitable share then turns into: in decision to transforming Markdown right into a submit, discontinuance the a similar with a .ipynb file. The goal of this submit is to stroll you via this assignment.

Technical challenges

A brief search on the earn will prove you gatsby-transformer-ipynb. Veritably, here’s a Gatsby plugin that is ready to parse the Notebook file in a technique that we are in a position to get right of entry to it later in our GraphQL queries. It’s nearly too trusty to be trusty!

And, if fact be told, it’s miles. The labor used to be completed by the gorgeous other folks of nteract. On the opposite hand, the plugin hasn’t been maintained rapidly, and things don’t simply determine of the box — no longer to claim the dearth of customization that one would set aside a question to from a plugin.

I’ll spare you the dreary stuff, nonetheless after fussing around the darkish corners of GitHub, and with important assist from this submit by Remark Alternatives, I managed to create my rep fork of gatsby-transformer-ipynb, which solves my considerations and will suffice for the explanation of this submit.

Display, nonetheless, that I rep no scheme of develop into an active maintainer, and most of what I’ve completed used to be totally to get what I rep to work — exercise it at your rep menace!

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

Making a mission

Before the entirety, the provision code for what we’re going to perform would possibly per chance well additionally be stumbled on here on GitHub. We’ll originate by developing a Gatsby mission. Method particular you would rep Gatsby set aside in, and create a brand original mission by running:

gatsby original jupyter-weblog
cd jupyter-weblog

Fling gatsby originate and stride to http://localhost: 8000/ to make certain the entirety is working gorgeous.

Abolish your first Notebook

Since Jupyter Notebooks will most definitely be the tips provide for our price-original weblog, we rep to originate at the side of issue material. Within your mission folder, stride to src and create a notebooks folder. We’ll be particular to read from this folder later.

It’s time to create our first Notebook. For the functions of this tutorial, I’ll exercise this straightforward Notebook as a unsuitable. You would peek the dynamic output in GitHub, nonetheless be contented to make exercise of whichever you admire to rep.

After all, it’s price pointing out that some effectively to set aside outputs equivalent to dynamic charts generated by Plotly would possibly per chance well need extra care — let me know at the same time as you happen to know to rep me to cowl that in a later submit! To glean this submit rapid, nonetheless, we’ll address most efficient static photos, tables, and Markdown.

Now that you just would rep a Gatsby mission with data, the subsequent step is to impeach of it the usage of GraphQL.

Querying data

One among the largest advantages of Gatsby is flexibility when sourcing data. With reference to anything else you admire to rep can develop into a data provide that would possibly per chance well additionally be extinct to generate static issue material.

As mentioned above, we’ll be the usage of my rep version of the transformer. Hotfoot forward and set up it:

story add @rafaelquintanilha/gatsby-transformer-ipynb

Your next step is to configure the plugins. In gatsby-config.js, add the next to your plugins array (it’s doubtless you’ll repeatedly check GitHub when uncertain):

  get to the underside of:  `gatsby-provide-filesystem`,
  choices:  {
    name:  `notebooks`,
    direction:  `${__dirname}/src/notebooks`,
    ignore:  [`/.ipynb_checkpoints`],
  get to the underside of:  `@rafaelquintanilha/gatsby-transformer-ipynb`,
  choices:  {
    notebookProps:  {
      displayOrder:  ["image/png", "text/html", "text/plain"],
      showPrompt:  fraudulent,

Let’s destroy it down.

First, we add a gatsby-provide-filesystem risk within the array. We are telling Gatsby to see recordsdata in src/notebooks, where our .ipynb recordsdata dwell. Next, we are configuring the transformer and atmosphere some props:

  • displayOrder – MIME form of the outputs we are showing
  • showPrompt – whether or no longer the suggested is displayed

Whereas prompts execute sense in Notebooks, in static pages, they lose their reason. For that subject, we can cowl them in negate to rep particular issue material.

Time to study whether or no longer the entirety went basically based fully on thought. Launch GraphiQL by going to http://localhost: 8000/___graphql and speed the next question of:

question of MyQuery {
  allJupyterNotebook {
    nodes {

Success! Display how the HTML of our notebooks used to be generated. All that is left is to inject this HTML right into a React divulge and our assignment will most definitely be entire.

Generating posts automatically

The worst is on the assist of us now. Your next step is to impeach of this data in gatsby-node.js so we are in a position to generate static pages for every Notebook in src/notebooks.

Display, nonetheless, that we rep so as to add extra metadata to our Notebook, e.g., creator and submit title. There are rather a lot of recommendations of doing it, and the finest would possibly per chance well very effectively be to defend discontinuance relief of the fact that .ipynb recordsdata are JSON and exercise their rep metadata self-discipline. Launch the .ipynb and add the tips you wish:

 "metadata":  {
  "creator":  "Rafael Quintanilha",
  "title":  "My First Jupyter Post",
  "language_info":  {
   "codemirror_mode":  {
    "name":  "ipython",
    "version":  3
   "file_extension":  ".py",
   "mimetype":  "text/x-python",
   "name":  "python",
   "nbconvert_exporter":  "python",
   "pygments_lexer":  "ipython3",
   "version":  "3.7.4-profitable"
  "orig_nbformat":  2,
  "kernelspec":  {
   "name":  "python3",
   "display_name":  "Python 3"
 "nbformat":  4,
 "nbformat_minor":  2,
 "cells":  [

Expert tip: Have to you’re the usage of VS Code, opening the file will potentially originate the Jupyter kernel. You would disable it within the configs to edit the raw issue material, nonetheless I in general correct originate the file with but every other editor (equivalent to gedit or Notepad++).

The assignment now would possibly per chance well be precisely the a similar for any data provide with Gatsby. We’ll question of the tips in gatsby-node.js and stride the relevant data to a submit template, which, in turn, will develop into a obvious web page in our domain.

Sooner than attending to that, nonetheless, originate gatsby-node.js and add the next:

exports.onCreateNode = ({ node, actions }) => {
  const { createNodeField } = actions
  if (node.interior.form === 'JupyterNotebook') {
      name:  'slug',
      price:  node.json.metadata.title
        .split(' ')
        .blueprint(token => token.toLowerCase())
        .be half of('-'),

The above excerpt will, for every node created in GraphQL, check those that are a Jupyter Notebook and extend them with a brand original self-discipline, slug. We are the usage of a naive skill here, nonetheless it’s doubtless you’ll exercise a sturdy library equivalent to slugify. The original self-discipline will most definitely be queried and extinct to generate the submit direction. Within the a similar file, add the next:

const direction = require(`direction`)
exports.createPages = async ({ graphql, actions:  { createPage } }) => {
  const blogPostTemplate = direction.get to the underside of(`src/templates/BlogPost.js`)
  const results = await graphql(
        allJupyterNotebook() {
          nodes {
            fields {
  const posts =
  posts.forEach(submit => {
      direction:  submit.fields.slug,
      divulge:  blogPostTemplate,
      context:  {
        slug:  submit.fields.slug,

This in most cases queries data by slug and sends them to BlogPost.js. Let’s create it now:

import React from 'react'
import { graphql } from 'gatsby'
import Search engine advertising and marketing and marketing from '../parts/web page positioning'

const BlogPost = ({
  data:  {
    jupyterNotebook:  {
      json:  { metadata },
}) => {
  return (
      <SEO title={metadata.title} />
      <p>Written by {metadata.creator}p>
      <div dangerouslySetInnerHTML={{ __html:  html }} />
export default BlogPost
export const question of = graphql`
  question of BlogPostBySlug($slug: String!) {
    jupyterNotebook(fields: { slug: { eq: $slug } }) {
      json {
        metadata {

And that’s it! Soar over to http://localhost: 8000/my-first-jupyter-submit and peek your Notebook as a static HTML web page.


Because it’s doubtless you’ll peek, loads would possibly per chance well additionally be improved upon thru styling and manufacture. That is beyond the scope of this submit, nonetheless as a hint, it’s doubtless you’ll exercise CSS Modules to toughen the layout and decide pointless stdout (text output that you just don’t care about in a weblog submit). Abolish BlogPost.module.css and add the next:

.issue material {
  max-width:  900px;
  margin-left:  auto;
  margin-gorgeous:  auto;
  padding:  40px 20px;

.issue material :world(.nteract-prove-home-stdout),
.issue material :world(.nteract-outputs > .cell_display > pre) {
  prove:  none;

.issue material :world(.nteract-outputs > .cell_display > img) {
  prove:  block;

.issue material :world(.input-container) {
  margin-bottom:  20px;

.issue material :world(.input-container pre.input) {
  border-radius:  10px !important;
  padding:  1em !important;
.issue material :world(.input-container code) {
  line-height:  1.5 !important;
  font-size:  0.85rem !important;

.issue material :world(.input-container code:empty) {
  prove:  none;

@media most efficient show veil and (max-width:  940px) {
  .issue material {
    max-width:  100%;
    padding-left:  20px;
    padding-gorgeous:  20px;
    box-sizing:  border-box;

Now return to BlogPost.js and add the class to our div:

import css from "./BlogPost.module.css"
return (
  <div className={css['content']}>

Display how grand cleaner it appears to be like now. The profitable consequence (with minor tweaks) is hosted in Netlify. All adjustments are within the provide code.

Ultimate tips

Reworking Jupyter Notebooks into HTML pages is no longer advanced nonetheless does hold substitute little steps and adjustments. With any luck, this submit is a manual on originate with it.

There are heaps of adjustments and enhancements that would possibly per chance well additionally be completed, admire supporting effectively to set aside outputs (equivalent to a dynamic chart), enhancing mobile ride, larger metadata management, and further.

Notebooks are versatile and fun to work with, and automatically converting them right into a webpage is a extremely wonderful function of them.

Read More

Leave A Reply

Your email address will not be published.