Rendering Notebooks on GitHub

We are pleased to announce that, starting today, and as announced on the GitHub blog, Jupyter/IPython notebook (.ipynb) files will render directly on GitHub. This feature works for notebooks in any of the supported Jupyter programming languages on both public and private repos. This capability will complement nbviewer and make it easier for GitHub users to create, view and share notebooks on GitHub.

Here are some great examples of notebook based content that can now be viewed directly on GitHub:

• Cameron Davidson-Pilon’s Probabilistic Programming and Bayesian Methods for Hackers.
• Lorena Barba’s Aerodynamics-Hydrodynamics with Python.
• Benjamin Laken’s Monsoon Analysis.

We want to thank the GitHub team for bringing this new feature to GitHub. In particular @tclem, @arfon, @sshirokov, and @skalnik have all done an incredible job building this at GitHub. The first discussion of how to bring notebook rendering to GitHub happened almost 18 months ago, and a lot of work made this feature possible today. With over 200,000 notebooks available on GitHub, you already have a lot to read!

We are excited to see how this feature will impact science education and research on GitHub, as well as encourage the adoption of the Jupyter notebook as a standard file format across a wide range of fields. Jupyter notebook files are a JSON-based open document format that supports code and results, narrative text, images, and equations in one file. These documents simplify the creation and communication of computational narratives and make the sharing and replication of scientific results and data analyses simpler.

nbviewer

One key piece of infrastructure in sharing notebooks has been the nbviewer service, which started as a side project of mine in the late summer of 2012. Nbviewer has grown through deep integration with GitHub, with the ability to browse all public users, organizations, repositories, branches, tags, and even Gists. This would not have been possible without @rgbkrk and @bollwyvl, who handle the development and deployment of nbviewer. It would also not have been possible without Rackspace and Fastly, who provide free hosting and fast static asset distribution. Nbviewer has steadily grown to render hundreds of thousands of notebooks every week, and usage is still increasing. Based on this, we believe that rendering on GitHub will be a highly used and appreciated feature.

Although you can now view notebooks directly on GitHub, we are not planning to stop the development of nbviewer. While rendering directly in GitHub repositories is convenient and allows viewing notebooks in private repositories, there are number of reasons that nbviewer will continue to remain an important part of project Jupyter.

First, there are many notebooks not hosted on GitHub. As before, these notebooks can still be viewed on nbviewer. Furthermore, the Jupyter/IPython team are actively working on improving integration with other content providers, building on our experience with GitHub. For example, a recent pull request of @bollwyvl streamlines the process of adding new providers to nbviewer, with proposals for DropBox, GitLab, Google Drive, Stash, and other hosting and collaboration platforms.

Second, because of security concerns, some features available on nbviewer will not be available on GitHub. For example, GitHub will not render any dynamic output display that uses JavaScript, custom CSS, and most custom HTML embedded in Markdown or in outputs. When this is the case, and GitHub cannot fully render your notebooks, you will see an icon that allows you to view the full notebook on nbviewer.

Because nbviewer does not handle authentication, it will continue to support custom CSS, HTML and JavaScript in notebook. Thus, for highly customized or dynamic notebooks, nbviewer will still be the ideal place to share them.

We would love your feedback! If you have comments or find bugs with notebook rendering on GitHub or nbviewer, please open an issue on our nbviewer repo. Also, please send a few tweets to thank all the people without whom this would have not happened.

The Jupyter/IPython Team