Building a notebook shortcode for Hugo

Intro

While porting my website over to Hugo I knew one of the features I would miss is the plugins and especially the shortcode I made to convert jupyter notebooks on Wordpress! Taking learnings from the last plugin I've modularized it a lot more and made it easy to install and use with inbuilt JS and CSS.

Note: I had thought about using github actions to run nbconvert - however this would require much more integration and would perform relatively similarly.

Shortcode’s +/-’s

  • Very easy to use
  • Your code can be version controlled and updated without having to edit the raw HTML, simply trigger a rebuild of your site
  • Other people can work on the code, for example contributors to your GitHub page
  • Very easy to create a easy to by using this notebook plugin!
  • No iframes! You have complete control over your JS and CSS
  • Other people can change the notebooks (It's a blessing and a curse!)
  • Could potentially be slower to render as each time a user requests your page it will have to render the ipynb file

Possible improvements to be made

  • We could move the request into the JS but this would not version the static site - potentially add static/dynamic
  • Handle multiple hosting options of notebooks - only tested on github content
  • Add extra elements such as a github link onto the notebook div
  • Ensure full encapsulation of notebook CSS
  • Add mobile friendly CSS
  • Plus more! Let me know in the comments section below

How to use the shortcode

Assuming you have your project set up with your own theme and the additional shortcode git submodule you should just be able to take two steps! Create a new post and add in the shortcode with a url to where you're notebook resides.

1
 hugo new posts/test-notebook.md
1
 {{< notebook url="https://github.com/mqlaql/geospatial-data/blob/master/Geospatial-Data-with-Python.ipynb"  >}}

The output of which can be seen below! Note you may have some CSS issues - if you see problems, I'd be happy to take PR's!