Angus Hollands | 2i2c

Introducing Jupyter Book 2 at FOSDEM 2026

Fri, 06 Feb 2026 00:00:00 +0000

Our teammate Angus Hollands gave a talk at FOSDEM 2026: Introducing Jupyter Book 2.

The talk shares why the Jupyter Book 2 and MyST stack was rebuilt, and how it supports open, reusable computational publishing workflows.

Slide from the FOSDEM 2026 session introducing Jupyter Book 2.

Learn more #

Acknowledgements #

Thanks to Project Pythia and to BIDS for supporting deeper foundational contributions like this in Jupyter Book.
Thanks to the Jupyter Book team for helping out with slide creation and doing all the work Angus spoke about here!

Jupyter Book at the Scientific Python 2025 Developer Summit

Fri, 23 May 2025 00:00:00 +0000

Chris and Angus recently attended the Scientific Python 2025 Developer Summit on behalf of Jupyter Book, here’s a brief blog post about their experience written with the Jupyter Book team.

Launching Jupyter Book for 2i2c Communities

Thu, 08 May 2025 00:00:00 +0000

We’re excited to announce out-of-the-box support for Jupyter Book 2 for our community members. This allows communities to create and share knowledge bases together for their community workflows. This post describes the motivation behind this new functionality, and how you can learn more about the project.

⭐ Members of 2i2c’s community network can use this feature in their hubs by following our documentation and sharing guide.

A core component of our mission to make research and education more impactful, accessible, and delightful is leveraging our unique global network of communities to make meaningful improvements to the open-source tools that power their work. Learning from one community can then provide value to our entire network, e.g., our work with PACE on speeding up their CNN model training.

Central to our communities’ work is the importance of sharing new findings, best practices, and community resources. Across our network, we have seen communities creating their own “books” that provide a home for this kind of content. Many of these books feature the concept of a “landing page” that welcomes new members, establishes an identity, and provides jumping-off points (or “calls to action”) to more detailed resources.

Until now, each community has been required to undertake this work independently. 2i2c believes that by building upon existing open-source tools like Jupyter Book 2, we can help communities focus on the content of their home, rather than spending time worrying about its appearance. To that end, we have been working on an initiative to allow communities to rapidly build interactive starter documentation and provide users with a rich, interactive, and informative onboarding experience. Through this initiative, we have:

Improved the user experience of launching into interactive compute environments from a Jupyter Book.
Built components into the Jupyter Book “book theme” for low-density landing page content like call-to-action blocks.
Extended our service to co-locate community documentation alongside community hubs (i.e., docs.hub.2i2c.cloud).

(A screenshot of the 2i2c Showcase Hub landing page, featuring a simple banner image and call-to-action.)

To take advantage of this feature, communities can use the 2i2c-org/community-docs-template to deploy a Jupyter Book site to GitHub Pages. This template demonstrates simple usage of Jupyter Book 2 for computational content and landing page creation, and establishes the necessary CD workflows for web publication. Meanwhile, 2i2c can update our domain name management to point the docs.hub.2i2c.cloud nested subdomain to the newly deployed documentation.

For more information, see our community documentation for deploying Jupyter Books.

Developing these new capabilities taught us a lot about what makes building “good” community documentation so difficult. A wide range of bespoke website-building tools and integration quirks previously made it challenging for communities to both keep documentation current with internal changes and keep up with necessary software updates. We also learned that by trading bespoke complexity for simplicity and readability, we could build a solution that scales to multiple communities, with a consequently reduced maintenance burden.

With these improvements, we have initiated a conversation about what a more unified “look and feel” for our network might entail, and how it might benefit our communities. Much more can be done to build on this first step, and we are eager to gather feedback on how to improve these features for users.

To learn more about this work, consider exploring a minimal example on our Showcase Hub, and check out our service guide. Let us know what you think!

Designing for an ecosystem: a case study in cross-project open source contribution

Tue, 21 Jan 2025 00:00:00 +0000

A key challenge in the open source space is that projects are often independent and autonomous, with relatively few formal ways to collaborate and coordinate efforts. While this usually isn’t a big deal, it means that there is a missed opportunity to grow the impact of an ecosystem because it requires coordinated development among multiple stakeholders within it.

This is one of the reasons we created 2i2c’s open community hub platform. By deploying a single platform that utilizes entirely open infrastructure that we contribute back to, we have visibility over a variety of projects along with the need to combine them together for a specific end-user outcome. One-such development scenario recently came up involving Jupyter Book 2 and JupyterHub.

Allowing readers to “bring their own Binders” #

We’ve recently been working to integrate Jupyter Book 2 workflows with our community hubs for a more seamless experience (for example, having book pages link back to interactive cloud sessions that allow users to interact with the content). We imagine a network of Jupyter Books that all build upon the same core infrastructures (JupyterHub, Binder, etc) for cloud-based computing. Our hope is to allow a user to bring their own Binder with them so that they can interact with another book’s content with their own cloud infrastructure. For example:

A student with access to binder.myuniversity.edu could read a Jupyter Book created by a professor at otheruniversity.edu.
The Jupyter Book is defined with a Binder specification that has a recipe for re-building the environment needed to run te book’s content.
From the professor’s book, the student can choose to launch an interactive Binder sessions on their university’s Binder, allowing them to interact with the book’s content on their own infrastructure.

We want a workflow like this to be as seamless and un-complicated as possible. We also want it to follow the same fundamental workflow as the nbgitpuller-based launch buttons. Along the way, we realized that we needed to coordinate development across Jupyter Book 2, JupyterHub, and BinderHub.

The three projects (Jupyter Book, BinderHub, and JupyterHub) that needed to work together to enable ‘bring your own binderhub’ workflows.

Getting Jupyter Book to discover Jupyter Hub #

As we began developing this workflow, we realized that there was a blocker in the JupyterHub and BinderHub ecosystem that needed to be fixed. We needed a way to ask a JupyterHub whether it had an unauthenticated end-point for service discovery. Basically, a way to ask a hub “what kind of hub are you, and how can we launch an interactive session on you?” Doing this is simple-enough - JupyterHub already has a way of reporting its version and application type, which allows us to infer how to launch interactive sessions. But, we hit a snag in an HTML context.

By default, JupyterHub disallows certain kinds of Cross-Origin Resource Sharing (CORS) requests, in order to restrict other applications from abusing a JupyterHub’s API. If you hit parts of a JupyterHub API from the command line, things work fine. But if you do the same thing via JavaScript from a website, the request is disallowed. This was a problem if we want Jupyter Book (a web application) to be able to make requests of JupyterHub’s API.

So, we realized that we needed to make an upstream contribution in JupyterHub in order to enable an interaction between JupyterHub and Jupyter Book. In this case, it was a relatively simple fix: allowing CORS requests for the specific API endpoint we needed (which is a very lightweight endpoint that is not vulnerable to security risks, and is broadly useful to make accessible)¹. That resulted in two PRs:

jupyterhub/jupyterhub#4966 allows CORS requests for the API that was needed for service discovery in JupyterHub.
jupyterhub/binderhub#1906 enables this workflow on a BinderHub so that its services can be discovered.
jupyter-book/myst-theme#503 adds new launch button functionality to Jupyter Book 2 that allows readers to bring their own Binder / JupyterHub links for launching. (this is what necessitated the above two PRs)

As a result of this upstream contribution loop, JupyterHub can now accept API requests at its “service discovery” endpoint, which means that Jupyter Book (and any other web application) can more easily learn about a hub’s capabilities and version.

We wanted to share this short vignette because it’s a good reflection of the kind of value that 2i2c tries to provide, given its role in helping to build and enhance networks of infrastructure, domain communities, and open source communities. In this case, we enabled a cross-project workflow that required knowledge of each project, and a vision for how they could be used together in a way that exceeded the sum of their parts.

We think there’s a lot more potential in these kinds of workflows, and are eager to continue our work to identify and enhance community-centric infrastructure for interactive computing.

Acknowledgements #

Thanks to the JupyterHub and Jupyter Book communities for collaboration and review on this work.

This “bring your own Binder” workflow benefits NASA training communities including NASA Open Science / ScienceCore, which partially supports this work.

This actually required an interesting bit of team discussion that was much easier with a few 2i2c staff on the JupyterHub team. The original request from Angus was interpreted as opening up the entire hub API to external requests (which is a bad idea!) but we were able to quickly discuss this with the JupyterHub team to clarify that this was only about a very specific API endpoint. This is the kind of communication loop that often goes haywire when you have people contributing to a project without historical relationships to the project’s maintainers. ↩︎

MyST Mini-Hackathon with the DeepLabCut Team

Mon, 02 Sep 2024 00:00:00 +0000

The DeepLabCut Team #

Animal pose estimation using deep neural networks. Courtesy of the DeepLabCut Jupyter Book

The DeepLabCut team is a group of researchers and developers who are working on open source tools for analyzing animal pose estimation by training deep neural networks on videos.

Chris Holdgraf visited the lab in early August to learn more about how the group were using open-source tools to document and share their work.

Jupyter Book and MyST #

Extensive documentation for using the DeepLabCut software package is already available as a Jupyter Book. The group was interested in adopting MyST Markdown to stay ahead of the curve and upgrade their Jupyter Book (see the related announcement Jupyter Book 2 will be build upon the MyST-MD engine).

Chris led a mini-hackathon to introduce the group to MyST and collect feedback on where enhancement features could be made in the future. Here’s a summary of the outcomes:

Many improvements were made to the MyST documentation 📖
- The MyST Quick Start Guide was used to onboard new users. Amendments were upstreamed to the MyST docs directly and were immediately available to all.
- A tutorial on executable documents was added to the collection of MyST tutorials.
- MyST-MD installation instructions were simplified using mamba.
A bunch of enhancement features were requested ✨
And we found a bug in the table of contents validation 🐞

Summary #

Hackathons are a great way for quickly imparting knowledge and gathering feedback in a short space of time. The event spurred rapid contributions to the MyST ecosystem – embracing reuse of the MyST quick start guides saved time and effort, while engaging with users directly closed a tight feedback loop for enhancements.

Acknowledgments #

Thank to the Mackenzie Mathis Lab for hosting Chris Holdgraf at EPFL, Lausanne, Switzerland.
Thanks to the Jupyter Book team for collaborating on this with us.

Hacking the Project Pythia Cook-off with MyST Markdown

Tue, 18 Jun 2024 00:00:00 +0000

Photo courtesy of Dr Debanjana Das

What is Project Pythia? #

Project Pythia is the education working group for Pangeo, a community platform for Big Data geoscience in which 2i2c operates a cloud hub. The core aim of Project Pythia is to spearhead the creation and curation of community-driven, open-source documentation, in the form of “cookbooks”, to enable the adoption of open, scalable and reproducible workflows for geoscientists.

What did 2i2c do? #

Jenny, James and Angus from the 2i2c team participated in the annual Project Pythia Cook-off 2024, a hackathon where cookbook authors and collaborators can spend dedicated time on creating and maintaining their content using Jupyter Book and deploying their cookbooks with GitHub actions.

2i2c teamed up with the infrastructure breakout group during the hackathon, led by Katelyn FitzGerald ( UCAR) and Kevin Tyle ( University at Albany), and members of the Curvenote team also joined the group.

Day 1 #

2i2c deployed and demonstrated a dedicated BinderHub service for Project Pythia that allowed hackathon participants to “self-serve” images of their software environment, which were specified by including a list of packages in an environment.yml file placed in their GitHub cookbook repository. Participants could then pull the image from a container registry into their 2i2c hub (or indeed, any other JupyterHub server) to share and reproduce their computational environments with ease.

Day 2 #

During the first half of the day, we quickly identified a number of issues that were proving to be a maintenance headache for the Project Pythia infrastructure group:

Configuration files for each cookbook were difficult to update at scale. Project Pythia currently have a gallery of over 30 cookbooks!
Changes to Sphinx-based themes inherited from upstream were prone to breaking custom Project Pythia branding downstream.
Executable content was not able to run on the Project Pythia’s dedicated BinderHub hosted on JetStream2 (operated by NSF).
Cookbooks frequently cross-referenced materials from other cookbooks to build upon pre-existing knowledge, but this was not easy to author and the reader experience was not as smooth as it could be.

Following the announcement that Jupyter Book 2.0 will use MyST last month, Rowan (Curvenote) and Angus (2i2c) delivered a compelling demonstration of the MyST ecosystem centered around modern web-first technologies (JavaScript/TypeScript) that offers improved interactivity and accessibility.

In the second half of the day, we decided to use the hackathon to explore migrating the Pythia cookbooks from using a Sphinx-based to a MyST-based document structure and engine. Within one afternoon, the group migrated four cookbooks to use MyST MD

This moment was palpably exciting! It was evident that MyST MD supported backwards compatible content out of the box, which alleviated fears of sunk cost into existing Sphinx-based cookbooks. The migration workflow was as simple as executing the following commands

conda install mystmd

myst.

Day 3 #

We spent this day tackling support for managing a gallery of Project Pythia cookbooks at scale. See the Executable Books blog post for technical details on how we

Centralized configuration
Prototyped a gallery plugin in Python
Fixed a number of bugs related to integrated computation with Binder and JupyterLite
Embraced the referencing and reuse of content with simple markdown syntax for hover-references.

Day 4 #

Looking to the future, we spent time reflecting on our experiences and discussing the potential, transformative impact MyST MD tooling could have in the hands of the scientific community at large, including the communities served by 2i2c. Knowledge-sharing based on static figures and PDFs would fall obsolete and give way to a dynamic, web-first approach to sharing interactive narratives backed by compute from a Jupyter server.

Throughout the course of the hackathon, the rate of iterated development for both end users of the community cookbook and the developers of the open-source tooling was astounding. For example, we were able to quickly expose small bugs ( e.g. support for HTML video tags) in the MyST MD tooling, which were immediately fixed upstream and released within minutes. The feedback loop that connected the user experience with the software tooling was incredibly synergistic, with immediate impact both upstream and downstream that 2i2c hopes to continue replicating across many facets of their operations.

Beyond the Project Pythia Cook-off, the breakout group will continue conversations around strengthening their community of practice and hopefully advocating for wider adoption of MyST MD amongst the scientific community (say hello to some of our group members at SciPy 2024 in July!).

Acknowledgements #

University at Albany (NSF award 2324302): Led the funding acquisition, helped organize and facilitate the event
UCAR (NSF award 2324303): Led the planning and logistics for the event
Project Pythia for organizing this workshop.
Jupyter Book for providing development and collaboration at this workshop.
2i2c / Code for Science and Society (NSF award 2324304): Provided tailored compute services and on-site support
Curvenote: Contributed engineering cycles to MyST MD development.

Jupyter Book 2.0 will use MyST

Tue, 21 May 2024 00:00:00 +0000

See the Executable Books blog for a post on the future directions of the Jupyter Book project, which will be built on top of the MyST Markdown engine.

Acknowledgements #

This post relates to our ongoing collaboration with the Jupyter Book project.
Thanks to Project Pythia for funding part of our work on Jupyter Book.

Angus Hollands

Mon, 01 Jan 0001 00:00:00 +0000

Angus Hollands is an Open Source Applications Engineer at 2i2c. He was previously a post-doctoral researcher in the Computational High Energy Physics group at Princeton University. He has a long-standing history of working collaboratively in open source projects, such as Executable Books, Jupyter, scikit-hep, and Blender. He is motivated by open-source, open-science, and the FAIR principles to build a more accessible, empowering future for scientific research and publication. He obtained his PhD in nuclear structure from the University of Birmingham, and later worked as a postdoctoral researcher for the Princeton Institute for Computational Science and Engineering (PICSciE).