NBBinder module to generate table of contents, navigator links, and badge links for a collection of notebooks

Hi, all,

This is my first post in this forum!

I have been working on a module to bind a collection of Jupyter notebooks, generating a book-like structure with a table of contents, a header, navigator links, and badges to run each notebook in the cloud or to open slides.

It is based on some scripts by Jake VanderPlas’s that are part of his Python Data Science Handbook.

One can configure the binding process with a YAML config file and simply call a bind('config_file.yml') function in the module to process the notebooks.

See for example, the rendered notebook 00.00-Water_Contents.ipynb. The slides are automatically generated, in bulk, via nbconvert.

The module is available on PyPI and the code is in the Github repository for NBBinder. The README.md gives a good idea of the module and there are further info in readthedocs.

I am done working on it for now, but I am still leaving it in alpha stage just in case. If everything goes well in the following weeks, I should upgrade it to beta stage.

Bear in mind that this is my first attempt in packaging a module, so let me known if there is anything that I should do better (of course there are always many things to be improved, but let me known about anything that stands out).

I hope the module is useful for some people. I used a previous version of it in a course I taught last year and I will use the current version in my next course starting in March.

Sorry for the long first post.



Hi Ricardo,

This module looks really solid!

Just out of curiosity, what’s your take on the Jupyter Book tool? As far as I’m aware it does a similar job to your module.

I realize that Jupyter Book was only released at the end of 2018 and is still in beta, so may not have been what you needed at the time.

Hi, @maystey, thanks for the comments!

When I found out about Jupyter Book, I already had my previous version of nbbinder (with a different name) working as I wanted, and I didn’t have the time to learn how to use Jupyter Book. Besides, at first glance, it seemed it would not work quite as I wanted. The simple links, in each page, to open the notebooks in mybinder.org were all I needed and I didn’t see how to do that in Jupyter Book.

Now, looking again at Jupyter Book, it is visible that it produces a much more cohesive and prettier online-book. And it does have a way to open a live version of the notebooks in jupyterhub. For comparison, I would distinguish the following points:

  • Jupyter Book keeps the original Jupyter notebooks and markdown files untouched and produces cohesive and nicer-looking html pages, while NBBinder simply modifies, minimally, the Jupyter notebooks, in particular with the option to export the notebooks to slides and other ‘nbconvert’ formats.

  • Jupyter Book allows opening the Jupyter notebooks in a Jupyter Hub server, which requires quite a lot of human effort and computational cost, while NBBinder allows opening each notebook in mybinder.org, google colab, or so, which don’t require any setup. Please, correct me if the same can be done in Jupyter Book.

  • NBBinder takes into account the metadata configuration of the cells in regards to slides and generates a slide presentation associated to each notebook, which is perfect for lecture notes. One can have a more complete set of cells in a notebook available to the students, while only showing some highlights of it in the slides. I don’t known whether Jupyter Book can easily do that.

These are the most visible differences I noticed now.


Well, I looked again at Jupyter Book and noticed the session Features, which mentions the options to hide and show the input or the output of cells, which is pretty nice, and also comment on the option to add links to interact with the notebook in mybinder.org, besides a jupyterhub server. So it seems Jupyter Book could indeed work for me after all. I should give it a try at some point.

Apologies for the late response. I was going to mention the binder compatibility.

One thing Jupyter Book doesn’t have is automatically generating lecture slides, but I suppose you could use your NBBinder code for that.

I’m using Jupyter Book myself for my own lecture notes. I was toying with the idea of making a script to automatically generate the slides from the notes themselves, but I think making them separately helps my creative process.

Jupyter Book is really neat, I should give it a try next time. And it shouldn’t be hard for them to add the ability to generate slides with nbconvert. Maybe we should file an enhancement request.

Meanwhile, I will keep using nbbinder, the slides are an integral part of the lecture.

By the way, at the request of Project Binder, I will rename nbbinder to something else, to avoid conflict with mybinder.org. I haven’t decided the new name, yet.