Jupyter Notebook extensions and embedding a gist

Get the JN gist extension & embed a gist in a medium blog

(Last updated October 19, 2018)

This article has 5 parts:

  • Part A: Get the Jupyter Notebook Gist Extension
  • Part B: Turn a Jupyter Notebook into a Gist
  • Part C: Embed a gist in a Medium blog
  • Part D: Debugging (i.e. Troubleshooting)
  • Part E: Reflection on changes that occurred within a month

Part A: Get the Jupyter Notebook Gist Extension

There is an extension that allows you to share a Jupyter Notebook as a gist. According to GitHub, a gist is a way to share single files, parts of files, and full applications, but not directories with other people. Every gist is a git repository, so people can view the full commit history, complete with differences (diffs), as well as Fork and Clone them. In my case a gist will be a single Jupyter Notebook. I am figuring this out because I want to include a Jupyter Notebook gist along with each of my blogs.

To turn a notebook into a gist, first I need to add the Nbextensions tab (Figure 1).

Figure 1. Nbextensions tab

At the time of re-writing and testing this, I just updated (actually totally un- and re-installed) Anaconda3 v5.3.0.

The official docs for Jupyter’s nbextensions are here.

Five steps to get nbextensions are:

  1. Make sure Jupyter Notebook is closed
  2. Open a terminal window
  3. Type the following command: conda install -c conda-forge jupyter_contrib_nbextensions
  4. Open a Jupyter Notebook & celebrate if you see the tab!
  5. Tic the boxes of the extensions you want to use

Other than gist-it, I’m using the following extensions: Code Font Size, Codefolding, Collapsible Headings, Hide Header, plus the ones that are ticked by default. If you want more, here’s one post on the top 5 extensions from Eliot Andres, a machine learning engineer. What are your favorite extensions?

As of now nbextensions doesn’t work in Jupyter Lab. If you see this change please comment below to let me know!

Part B: Turn a Jupyter Notebook into a gist

Hypothetically, this should take three steps and they are outlined directly below. However, nothing related to computers seems to work without a glitch. Due to my biology background, I’m used to the term ‘troubleshoot’ in regard to fixing problems. As a microbiologist with an affection for ‘bugs’, it is very hard for me to switch to the term ‘debugging’, but I’m trying. To keep the most important steps of this blog near the top, I moved the debugging to the end. If you get an error message along the way search for the debugging header in the lower part of this blog.

  1. Generate a personal access token

To allow Jupyter Notebooks access to a personal GitHub API, go to the Github token generator page, enter your password, and click “Generate new token”. On the next page create a token description, select scope = gist, and click “Generate token”. (In case this changes, here’s a link to the jupyter_contrib_nbextention docs.)

2. Enter access token

Return to the Jupyter Notebook nbextensions tab and click on the text of “Gist-it”, so that “Gist-it” becomes highlighted in blue as show in the bottom right corner of Figure 2.

Figure 2. Click on word Gist-it (not the check box)

Scroll down to Gist-it and click “Disable” so that Enable is now blue (Figure 3).

Figure 3. Disable to Enable

Paste in your Github token, tic the box that says “Gists default to public”, and click “Enable”.

3. Gist a Jupyter Notebook

From a Jupyter Notebook, click on the GitHub icon, the symbol in the bottom right corner of Figure 4.

Figure 4. Github icon (bottom right of image)

The window shown in Figure 5 should pop up.

Figure 5. Gist it!

Leave the Gist id blank. You can use the same name as your file name or edit it here. I think that keeping the .ipynb is important, but I haven’t experimented with removing it. Click “Gist it!” and the window will change to look like Figure 6.

Figure 6. Gist link is generated

Click on the big long blue number link and you should see something that looks like Figure 7.

Figure 7. Copy link from “Embed” field

Celebrate — you have published a gist on Github!

Part C: Embed a gist in a Medium blog

Technically, this only takes one step. For me it took two because I needed to iterate. Also, there are a number of things that look right or wrong that can lead you down the wrong path or make you think you were not successful. All are noted below.

Copying and pasting the line displayed when “Embed” is selected in Figure 7 does not work in a Medium blog because the syntax, as shown below, is for embedding directly into an html file.

`<script src=”https://gist.github.com/Deena-B/5e2123058923e7bbd5821a6ef8745801.js"></script>`

  1. Instead, copy and paste the link from the “Share” option (Figure 8). The line will look like this: `https://gist.github.com/Deena-B/5e2123058923e7bbd5821a6ef8745801`. It will lead to an inserted image like that seen in Figure 9.
Figure 8. Copy link from “Share” field
Figure 9. Result of pasting link from “Share” field

While in blog-editing mode, the gist above does not scroll. However, in the published version it will scroll, but only after the reader clicks on the image! :P

2. To update an image you have to re-gist it in the Jupyter Notebook, by clicking on the Github icon and “Gist it!” (see Figures 4 & 6). Then when you re-fresh your blog page it will automatically update.

Thanks for reading this post. Please give me some claps so I can feel the love. Happy gist-ing! — Deena

Debugging (i.e. Troubleshooting)

I ran into two bugs while implementing the steps above.

  1. If you get the error in Figure 10, which reads: “The ajax request to Github went wrong: “message”: “Requires authentication”….
Figure 10. Authentication error

This means that you need to generate a personal access token and enter it in the nbextensions tab (see Part B, steps 1 & 2 above).

2. If you get the error in Figure 11, which reads “This nbextension’s require url (gist_it/main) is referenced by two different yaml files on the server…”

Figure 11. Duplication of yaml files error

This means that you likely installed jupyter_contrib_nbextensions in two distinct locations. I had one set of nbextension folders installed at ~/Library/Jupyter/nbextensions and another at ~/anaconda3/share/jupyter/nbextensions. To fix it, run the command below:

jupyter contrib nbextension uninstall --user

Then restart Jupyter Notebooks and return to the nbextensions tab.

Alternatively, you could uninstall the other set of nbextension folders by using --sys-prefix. For more information, read about this error in the nbextension issues on Github here and here.

An asside:

My chosen command deleted the copy at ~/Library/Jupyter/nbextensions. I wonder if I can delete the whole Jupyter folder from my ~/Library since it seems like the functional version is in my anaconda3 folder? My ~/Library folder has the following in it:

Figure 12. Can I delete these files?

These look different from what is in ~/anaconda3/share/jupyter/nbextensions:

Figure 13. Comparing files

So, I’m decided not to delete them… for now.

Part E: Reflection on changes that occurred within a month

My how things change quickly! When I first wrote this post, on September 19th, I also had to use the two more commands, a month later and they are no longer needed. Thank you Conda for making my life easier!

Here is the OLD version of steps I followed on Sept 19: