Like any developer with a blog, I occasionally talk about blog\ntooling. Sorry. I just went through ye olde blog overhaul for the\nfirst time in years, so the sensitive should stop reading now and the\nrest of you have been warned. Stick around for a short story about a\nsmall “good” hack for blogging about Jupyter notebooks.
\nStatic Site Generators (SSGs) have been around for a while and are the\nbee’s knees. But now they are becoming the next generation markdown\nfiles – the front end explorable explanations to repos, which can\noptionally be wired up to kernel VMs for execution by the more curious\nreader.
\nFor this rebuild, I used two SSGs: Gatsby and Jupyter Book. The Gatsby\npart is just another story of a classic Jekyll to Gatsby\nmigration\nso let’s not talk about it.
\nThe other part of the SSG story is about Jupyter\nBook, which is used in the rebuild to SSG\ngit repos that are full of Jupyter notebook *.ipynb files. This is the\npart of the story that is interesting because it is about emerging tech, to\nbe described herein.
\nI’m only going to go over the truly novel bit, which as the title\nimplies is the integration of Jupyter Book and Google’s\nColab, their free Jupyter hosting\nservice. That is, Jupyter Book renders Jupyter notebook files\n(*.ipynb) for static hosting on tigue.com. Additionally, links into\nColab are made available to spin up a kernel VM for any reader wishing\nto execute a notebook they read on tigue.com.
\nThe contextual goal is a static site for a software developer. The\nsite’s front consists of a blog and set of projects. The latter\ninvolves a lot of Jupyter notebooks, which are static hostly on the\nstatic site as HTML snapshots of pre-run notebooks. Additionally,\nreader can easily execute the notebooks, without any admin hassles nor\ncosts for me, by clicking through to Google Colab.
\nThe “clicking through to Google Colab” hack is the novel bit. Jupyter\nBook usually clicks through to JupyterHub or Binder via the Interact\nbuttons on the top of the page, not to Colab.
\n(Of course, if executing on Colab, it would be really helpful and more\ninteresting if those notebooks being clicked through to had been\npreviously tested to run on Colab; but that topic is out of the scope\nof this post.)
\nI’ve been a long time believer in static site generators (SSGs). For\nthis blog rebuild, I’m using two SSG tools: Gatsby and Jupyter Book. I\nuse Gastby to SSG the blog, and I use Jupyter Book to SSG repos of\nnotebook which act as the demo/web presence for the code projects. The\nSSG notebooks have links into Google Colab if folks want to actually\nrun a given notebook on a VM, rather than just read a static notebook\nrendering.
\nGatsby was the obvious choice since I’ve been using React and GraphQL\nfor a while now. And Jupyter Book is simply the best in class for its\ntask (notebook SSGing). I can report that SSG tooling has come along\nnicely over the last few years.
\nJupyter Book generates the “static site” for a given git repo full of\nnotebooks (*.ipynb files). The static site will have pre-run notebook\nweb pages i.e. cell outputs will be included to demonstrate what the\nsoftware can do.
\nAdditionally if the reader wishes they can interact with the notebook:\na link in the Jupyter Book generated notebook pages will have a link\nto Colab which will grab the notebook clean from GitHub and provision\na virtual machine within which to run and interact with the notebook.
\nCombined these two SSG tools enable a projects-and-blog web presence\nfor a developer to be run completely staticly, without involving say\nMedium for blog hosting and MSFT GitHub for notebook rendering, yet\ncode can also be run “dynamically” on Colab. It makes for a low hassle\nyet high functionality coder’s blog.
\nI want readers to be able to expeditiously run and interact with\nthe code in said notebooks statically hosted on tigue.com. And I don’t\nwant to manage that nor pay for the provioning of VMs, thank you very\nmuch. Google Colab fits the bill perfectly.
\nJupyter Book has a lot of nice functionality already. I don’t know of\na better equivalent. Nonetheless, for my React-based blog there is\nfunctionality overlap between Gatsby and Jupyter Book. E.g., the\nlatter uses Jekyll for static page generation, which the former is\nalso doing.
\nConceivably, much of Jupyter Book could be reproduced by\nGatsby. But Gatsby is JavaScript; that’s getting away from the Python\nworld so it’s unlikely in the short term. So for now: blog is Gastby\nbased and repo-of-notebooks is Jupyter Book based.
\nSo, with the context set, the solution boils down to a small hack of\nthe HTML templates in Jupyter Book. It’s not even really a hack, just\nan unexpected novel use, which good technologies enable.
\nJupyter Book already has a customization hook for providing a button\nuses can click to be taken to some site where JupyterHub (or Docker)\nis running. The code where the hook is used in in the\njupyterhub.html\ntemplate. It’s a bit gruesome but the point is all the info needed\nto build the equivalent URL for Colab is there: site, repo, branch, etc.:
\n{% capture interact_url_jupyterhub %}hub/user-redirect/git-pull?repo={{ site.binder_repo_base }}/{{ site.binder_repo_org }}/{{ site.binder_repo_name }}&branch={{ site.binder_repo_branch }}&subPath={{ page.interact_link | url_encode }}&app={{ hub_app }}{% endcapture %}\n{% capture interact_icon_jupyterhub %}{{ site.images_url | relative_url }}/logo_jupyterhub.svg{% endcapture %}\n<a href=\"{{ site.jupyterhub_url }}/{{ interact_url_jupyterhub }}\"><button class=\"interact-button\" id=\"interact-button-jupyterhub\"><img class=\"interact-button-logo\" src=\"{{ interact_icon_jupyterhub }}\" alt=\"Interact\" />{{ site.jupyterhub_interact_text }}</button></a>So, the “hack” is simply a modification of one of the HTML templates that are in the content repo, not part of the jupyter-book tool’s repo. So this is a good hack. Just change the above to:
\n{% capture interact_url_jupyterhub %}{{ site.binder_repo_org }}/{{ site.binder_repo_name }}/blob/{{ site.binder_repo_branch }}/{{ page.interact_link }}{% endcapture %}\n{% capture interact_icon_jupyterhub %}https://colab.research.google.com/assets/colab-badge.svg{% endcapture %}\n<a href=\"{{ site.jupyterhub_url }}/github/{{ interact_url_jupyterhub }}\"><button class=\"interact-button\" id=\"interact-button-jupyterhub\"><img class=\"interact-button-logo\" src=\"{{ interact_icon_jupyterhub }}\" alt=\"Interact\" />{{ site.jupyterhub_interact_text }}</button></a>