Jupyterbook | 2i2c

Combining multiple repos into one site at jupyterbook.org

Mon, 06 Apr 2026 00:00:00 +0000

As part of an initiative to improve jupyterbook.org’s documentation, we refactored the site so that multiple repositories are served under one domain. We wrote up the details on the Jupyter Book blog.

Read the full post here:

How we combine multiple repositories into one website at jupyterbook.org.

Along the way we made several upstream improvements to the MyST Engine and the MyST theme:

parts: support for extends: and URL support as well so we can share a footer / navbar configuration across repositories
internal_domains option so that links to another repository’s content could still be treated as internal
Less aggressive citation parsing so that text like @githubhandle weren’t parsed as a citation
Several mobile and UX fixes (that’s one, there were many others!)

These all felt particularly relevant for documentation that our member communities manage, where you have content split across multiple repositories but served at a single domain.

Acknowledgements #

Thanks to Project Pythia and EarthScope for collaboration and feedback that helped shape this work. And thanks to our member communities whose memberships fund upstream contributions like these.

Multi-repo site support is also useful for training programs that span several content repositories, including NASA Open Science / ScienceCore.

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!

New Jupyter Book / MyST stack release (Jan 2026)

Thu, 29 Jan 2026 00:00:00 +0000

The MyST/Jupyter Book stack shipped new releases this week. Release pages:

Where we contributed #

We’ve spent extra time lately trying to fix bugs and generally improve stability, reliability, and UX papercuts. Here are some of the things we focused on:

Extra review time to get in concurrent executions in mystmd
Fixing broken edit URL logic so our community “edit buttons” worked again
Standardized link styles so users know what to expect from links
Added extra hover metadata for github issues and PRs for communities that often link to their GitHub issues
Made all of these releases and wrote up the release notes!

Most of our contributions were foundational in nature - we fixed a bunch of bugs, did review on the PRs of others, and managed the release process itself. Check out the changelogs for more details!

Acknowledgements #

Thanks to our member communities - their memberships cover the cost of foundational upstream contributions to projects like these.

Particular thanks to Project Pythia which currently supports much of our upstream contributions in Jupyter Book.

These releases also support training communities that author curricula in MyST, including NASA ScienceCore.

Creating a re-usable redirect generator for Jupyter Book 1 migrations

Wed, 12 Nov 2025 00:00:00 +0000

When migrating documentation from Jupyter Book 1 to Jupyter Book 2, URL structures change dramatically and break external links. We spent some time createing a re-usable tool to solve this problem across multiple projects.

You can check out the tool below:

jupyter-book/jb1-redirect-generator

It’s designed to be run in a self-contained way by putting the dependencies in script metadata at the top. This means you can run it like this:

uv run https://raw.githubusercontent.com/jupyter-book/jb1-redirect-generator/main/generate_redirects.py

This let’s you generate redirects from JB1 -> JB2 URL structures and dump them in a _build/html folder with your JB2 built pages.

We tested this out by converting the Jupyter Governance docs to Jupyter Book 2 and running it there. You can find a noxfile that runs these commands here:

jupyter/governance/blob/bcdae30efdecbe75bc4751ef1fe1e602fe82ee10/noxfile.py#L25-L37

And its use in a GitHub Workflow here:

jupyter/governance/blob/bcdae30efdecbe75bc4751ef1fe1e602fe82ee10/.github/workflows/deploy.yml#L39-L44

Learn more #

Refactoring Jupyter Book 2 documentation ahead of a major release

Sat, 01 Nov 2025 00:00:00 +0000

Documentation is what turns open source code into products that people actually want to use. We recently spent a few days refactoring the Jupyter Book documentation to prepare for the upcoming Jupyter Book 2 release, and we’re excited about how much clearer the docs have become!

What we did #

We restructured the docs using the Diataxis framework to better organize content by user type and task:

Reorganized into clear topic areas with landing pages for easier navigation
Added missing content like the feature voting table and contributing guides
Created upgrade guidance to help users understand the relationship between Jupyter Book 2 and MyST

This work helps users find what they need faster and gives the project a stronger foundation to build on going forward.

Why we’re excited about it #

Better documentation reduces maintainer burden by helping users answer their own questions, and it makes the project more welcoming and useful to new contributors. We hope this makes Jupyter Book more accessible to everyone and lays a good foundation for the new release!

We’re also excited because so many others helped provide edits and comments!

Learn more #

Acknowledgements #

Thanks to @rlanzafame, @FreekPols, and @bsipocz for their helpful reviews, edits, and feedback on the PR!
Project Pythia, CryoCloud, NASA Open Science / ScienceCore, and the Berkeley educational projects are our primary member communities using MyST and Jupyter Book. Their support covers the cost of these kinds of foundational contributions.

Open slides: Jupyter Book 2 and MyST at the UC Berkeley Data Science Education Summit

Tue, 01 Jul 2025 00:00:00 +0000

Chris gave a talk about Jupyter Book 2 and MyST at the UC Berkeley Data Science Education Program’s annual meeting. It covered the next direction for the Jupyter Book project, and its recent adoption of the MyST Document Engine for Jupyter Book 2.

You can view the full slide deck here.

Learn more #

Acknowledgements #

Thanks to Project Pythia for funding some of our work on the Jupyter Book and MyST ecosystem
Thanks to CloudBank for collaborating with us on adapting and deploying Jupyter Book for education and organizing this summit
Thanks to the Jupyter Book project for collaborating with us on these strategic efforts over the last years

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!

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.