Machine Learning Blog/Website Design

Est. read time: 2 minutes | Posted: January 16, 2021 by John Gentile

Building a technical blog or website of any kind poses many unique challenges, but there’s nearly infinite ways to design a site; you can choose from many different content management frameworks and site generator tools. For me, I decided to use Jekyll static website generator because of the many FOSS extensions and development flexibility, as well as the low-cost (often free, like GitHub Pages) hosting ability of static websites. With this base framework, I found a couple great add-ons and tools that help to make a great blog for technical notes, especially when working with Machine Learning notebooks.

Jupyter Notebooks are currently a very popular way for taking notes on research to prototyping Python code on a variety of frameworks. Jupyter Notebooks are great because the text and equations can be easily entered as Markdown, and the Python code blocks are interactive and executable. The challenge this presents is when you have valuable notes and/or code that you want to maintain as part of a Jupyter Notebook, but still want to have the ability to post the notebook as part of your website (or any HTML medium really).

I’ve tried more intensive methods such as embedding notebooks using binder or embedding Google Colab notebooks in Medium posts, however the easiest tool I’ve found is the convenient Jekyll plugin red-data-tools/jekyll-jupyter-notebook.

What’s great is, once its installed, you can simply embed a Jupyter Notebook into a static webpage using a simple code block within your Markdown page:

{::nomarkdown}
{% jupyter_notebook "/path/to/notebooks/my_notebook.ipynb" %}
{:/nomarkdown}

The result is a perfectly formatted, rendered output of your notebook, directly within your post:

For documentation and website purposes, the non-interactive, static presentation should be fine; any necessary support for actual code edits or dynamic response should simply be handled with a link to the Notebook in a full environment with execution support, such as Google Colab. What’s also great about Google Colab is that you can directly run and edit notebooks on GitHub, similar to the “Open in Colab” badge in the above example.

Another great plugin for technical research blogging is inukshuk/jekyll-scholar; this plugin inserts and formats bibliographies for Jekyll posts and makes citing sources very easy, similar to the process used in LaTeX documents. You can set the citation style to a variety of publication standards, as well as reference standard *.bib and *.bibtex bibliography files.

From there, depending on the exact format used, the insertion of a bibliography can be done with a Liquid tag:

{% bibliography %}

Then, citations can be made in text, similar to LaTeX \cite{author} style, using another inline Liquid tag:

{% cite author %}

These, and even more FOSS plugins, make for an easy pipeline for deploying technical research to static webpages, especially when dealing with Jupyter Notebooks for topics like Machine Learning.