Jupyter Blog - Jupyter Book

Navigating the Post-Workshop Fog: a Path to Myst

2026-07-09T15:15:00+00:00

by Chiara Marmo and Serena Bonaretti

From June 15th to 17th 2026 a Jupyter Workshop took place at Paris-Saclay University : “Demystifying MyST Markdown in education”. The workshop combined presentations in the mornings with collaborative sprints during the afternoons. It has been funded by the Jupyter Foundation and SaclAI-School.

Milestones

Improving documentation and tools for easier deployment even for non-specialists.

Freek Pols from Delft University and Brigitta Sipočz form CalTech presented some examples and challenges in publishing courses and documentation at large scales. Angus Hollands, MyST maintainer, made an in depth presentation of Myst and JupyterBook2. Guided tutorials introduced participants to complete a Jupyter Book workflow. The participants learned how to create their first Jupyter Book, and how to publish it.

Text notebooks as first citizens.

Marc Wouts and Yahya Heni discussed the path from jupytext to jupyter-plainb to open and execute plain markdown text notebooks directly in Jupyter Lab. Two Jupyter Enhancement Proposals (JEP) has been discussed together with Jupyter Lab and MyST maintainers:

One step at a time

Over 30 issues and pull requests have been opened in the whole Jupyter ecosystem:

documentation items: for example, about text notebooks in jupyterlite or publishing on different hosting solutions;
feature requests: for example, single document feature in JupyterBook2, non-default application to open files in Jupyter Lab;
adopt JupyterBook2 for software documentation: for instance itables and travo.

Sidewalks

The workshop provided the opportunity to continue previous discussions about AI in education: some participants attended the workshop “AI in Jupyter” and were able to pick up the conversation from there.

Relationships between Academia and Open Source Software communities were also topic of conversation: about Open Source Program Offices (OSPOs) and how their action can be connected to education strategies.

Wandering

Collaboration is a matter of trust. That’s why it is still important for people to meet in person and to know each other. It is about exchanging details, like keys to decrypt characters and aspirations. One might discover a shared passion for shoes. Another may finally enjoy long French-style lunch breaks.

When the time comes to resume the path, important steps have already been taken in the right direction.

Becoming the new JupyterHub and Jupyter Book community manager

2026-06-15T07:01:00+00:00

There are moments in life when things, simply, converge. You work and study, study and work, and then, simply, it happens. It starts one day when somebody tells you “there is this new thing called Jupyter Notebook, you should give it a try!”. So you install it, play around with it. It works like a charm. It’s easy, fast, nearly playful. It’s beautiful–and if you grow up in Italy, beauty always matters. Then, you have the urge to tell others about it. You organize a workshop at a conference in musculoskeletal image analysis and introduce marvelous novel tools for computational research: “You know? Nowadays we can do open science easily because somebody has created Jupyter Notebook, Binder, new Python libraries!” And then, together with some friends, you write a proposal for a Jupyter Community Workshop, and–unbelievable!–you get it. Initially, you think you are just organizing a workshop. But somehow, the number of people interested becomes larger and larger, and you find yourself co-founding and coordinating what is now the Open and Reproducible Musculoskeletal Imaging Research (ORMIR) Community. In ORMIR’s Python packages, the examples are in Jupyter Notebook, the documentation is in Jupyter Book. Sooner or later, we will have our JupyterHubs too; it’s just a matter of time. In parallel, life gives you some professional challenges. So you start teaching Python online, one-to-one. You look for material that fits your style, but you cannot find any. So you start teaching it your way, using Jupyter Notebook in JupyterLab and it works. Students find it easy, independent of their background. The teaching material seems to work, so you transcribe it into a book entitled Learn Python with Jupyter, and you make it open. At the same time, you are obsessed with keeping up to date. You go to JupyterCon, meet the people, watch their YouTube videos, participate in online meetings. And then, there is a job posting for a community manager. And you are like: “Nah, they will never hire me”, so you set it aside. But then somebody out of the blue tells you to apply because “100% of lottery winners played!”. So you give it a chance, and here I am: my name is Serena Bonaretti and I am the new JupyterHub and Jupyter Book community manager!

In this new role, I am very much looking forward to working with the JupyterHub and Jupyter Book communities! I will collaborate with maintainers to understand and document projects’ priorities and define the best processes to achieve their vision. I will support contributors in finding their way into the projects and make the real-world impact that they hope to achieve. I will dialogue with users to make sure that the tools we create are useful for their work. And I will share our activities monthly and what we learn with anybody interested, so that we can all benefit from this journey!

And you? How did you start using the tools of the Jupyter ecosystem? Do you work in JupyterHub? Have you ever written a Jupyter Book? Would you like to be a contributor? Are you an enthusiastic user? Write me on Discord (Jupyter Book/MyST) or Zulip (JupyterHub). The JupyterHub and Jupyter Book communities and I are looking forward to getting to know you!

A Jupyter Workshop: Demystifying MyST Markdown in Education

2026-04-30T15:05:00+00:00

A new Jupyter Workshop is happening June 15–17, 2026 in Orsay, France. Demystifying MyST Markdown in Education is a three-day workshop organized by the Jupyter community, focused on helping science educators adopt Jupyter Book and the MyST document engine for their teaching materials.

What’s it about?

The workshop aims to remove barriers for educators who want to use Jupyter Book and MyST to publish accessible, reproducible pedagogical content. Here are the broad topics of each day of the event:

Teaching use cases and needs : what educators actually need from tools like Jupyter Book.
Contributor tutorials and onboarding : how to get involved with the project.
MyST Markdown as a text representation for Jupyter notebooks : writing and sharing computational narratives.

Attendees will learn how to contribute to the Jupyter Book community, collaborate with maintainers, and advocate for the needs of their users.

Have a look to the workshop agenda and if you have ideas you would like to be discussed there, please share them in the related issue.

Where and how to join

The workshop is hosted by Laboratoire Interdisciplinaire des Sciences du Numérique (LISN) and supported by SaclAI-School at Université Paris-Saclay.
Travel funding is available, apply here for travel funding.

Registration and full details are on the event page.

Thanks

A huge thank you to the whole Jupyter community supporting the event and to the Jupyter Foundation for making it possible.

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

2026-04-22T13:01:00+00:00

The Jupyter Book project has content in a bunch of different repositories — user docs, a blog, a team compass, and project & community pages. We recently finished an initiative to serve each set of content at jupyterbook.org, while keeping the source files separated in their repositories.

Jupyter Book builds tools and standards for communicating and publishing computational narratives.

Getting there required a combination of Netlify configuration and several improvements to MyST and the MyST theme along the way. This post walks through the pieces and how they fit together, so you can do something similar with a multi-repo project.

Cross-posted with this Jupyter Book blog post where you can see the MyST engine in action.

Why is this useful?

Two things bugged us about the old setup:

We had multiple types of content embedded in one repository. In particular we had versioned user documentation alongside evergreen community documentation (e.g., the roadmaps page). This meant we had duplicated content for some user documentation, and a slow lag time before it’d make it’s way into /stable.
Search engines treat subdomains as separate websites, so blog.jupyterbook.org wasn’t helping jupyterbook.org in search rankings.

We wanted jupyterbook.org, jupyterbook.org/blog, jupyterbook.org/stable, jupyterbook.org/compass all under one roof, with each repo still deploying on its own via static websites.

We accomplished this with Netlify proxy rules and shared MyST configuration!

Proxying sub-sites with Netlify rewrites

We discovered that Netlify reverse proxy rules are a great way to accomplish this. These essentially intercept queries to a URL path (eg. /blog/**) and serve content at that path from elsewhere (e.g., blog.jupyterbook.org). The browser sees jupyterbook.org/blog, but Netlify fetches the content from a totally different site behind the scenes.

We set up a “jupyterbook.org” repo that serves the landing page and our evergreen community documentation, and proxies everything else:

/ - served directly from the jupyterbook.org repo (served on Netlify)
/blog - proxied from the blog repo (served on Netlify)
/compass - proxied from the team-compass repo (Served on Netlify)
/stable - proxied from the jupyter-book repo (served on ReadTheDocs)

Here’s what the netlify.toml looks like (simplified):

# Blog: proxied from another Netlify site
[[redirects]]
  from = "/blog/*"
  to = "https://jupyter-book-blog.netlify.app/blog/:splat"
  status = 200
  force = true

# User docs: proxied from ReadTheDocs
[[redirects]]
  from = "/stable/*"
  to = "https://jupyter-book.readthedocs.io/stable/:splat"
  status = 200
  force = true

Each repo deploys independently, meaning we can update the content at whatever cadence is best for that repository. The jupyterbook.org repo only needs updating when the nav structure changes. But making it all feel like one site took some work on the MyST side.

Shared configuration with `extends`

MyST’s extends: configuration lets one project inherit configuration from another. We use this to share navbar, logo, and favicon config across all sub-sites from a single site.yml in the core repo:

# In the blog's myst.yml
extends:
  - https://github.com/jupyter-book/jupyterbook.org/raw/refs/heads/main/docs/_site/site.yml

If we change the configuration at that file, it’ll automatically be inherited in every other repository when we re-build it (usually done on each commit, or on a daily CRON job with GitHub Actions).

Here are a few useful things that we’ve shared across sites via the pattern above:

Navigation bar URLs
Site footer configuration
Site branding (logo, titles, etc)
Announcement bars (when we need a temporary announcement to show up everywhere)
Internal domain configuration (see above)

Along the way we added parts: support to the extends: key to get this working.

One gotcha: `BASE_URL` for asset paths

MyST bakes BASE_URL into CSS, JS, and image paths at build time. If you build with BASE_URL=/ but serve at /blog, none of those load properly.

To fix this, each sub-site builds with BASE_URL set to its final path on jupyterbook.org. For example, here’s some Netlify config from the blog that does this:

[build]
  publish = "publish"
  # This ensures that `/blog` is appended to asset paths
  environment = { BASE_URL = "/blog" }
  command = """
    cd docs && myst build --html && \
    mkdir -p ../publish/blog && \
    # Here we move the HTML assets to the blog
    mv _build/html/* ../publish/blog/
  """

`internal_domains` for cross-site navigation

BASE_URL fixes asset loading, but it doesn’t fix navigation. Jupyter Book used to treat full URLs as “external” links, adding an extra icon and opening a new tab when clicked. This led to a bunch of tabs any time you navigated around jupyterbook.org, and was also reported by the Project Pythia team.

We added an internal_domains option to fix this:

site:
  options:
    internal_domains: jupyterbook.org

Now the theme treats any link to jupyterbook.org as internal. It provides same-tab navigation and no external link icon, even though the link is technically a full URL.

Want to do this too?

Hopefully this is a useful workflow for communities that have multiple repositories of content.

All of the config is in jupyter-book/jupyterbook.org, and the tracking issue with the full story is jupyter-book/jupyter-book#2528.

If you’ve got questions about this work, come chat with us at discord.mystmd.org.

Acknowledgements

Thanks to Project Pythia for providing additional guidance, collaboration, and support for this work.
Thanks to EarthScope for giving user feedback about the usefulness of this as they explore converting their docs to the new MyST engine.

The MyST AnyWidget Directive

2026-04-16T15:28:00+00:00

Authors of MyST Markdown can now embed interactive JavaScript widgets directly in content using the new {anywidget} directive.

What this means

You can now add any javascript interactivity to your MyST Markdown website or Jupyter Book.

Here’s an example that creates a clickable button 👇 to see an interactive version check out the post on the Jupyter Book blog.

How we got here

The idea of a portable widget interface for interactive computing isn’t new: anywidget has been an emerging standard in the Jupyter community for a while, leveraging modern Javascript principles (via ESM Modules), and giving you a simple initialize({ model }); render({ model, el })[1] contract so that widgets can be written once and reused across notebooks. AnyWidget in Jupyter interfaces supports tight integration with the kernel, allowing interactions similar to ipywidgets[2].

From the MyST Markdown and Jupyter Book point of view, we’ve focussed on supporting the render() side of the AnyWidget interface (see AnyWidget Frontend Modules) to allow MyST users to bring any kind of javascript-based interactivity into their articles and books without having to lean on Jupyter at all.

That part of the story started at SciPy 2024 with Trevor Mantz and Steve Purves hacking through a proof of concept during the sprints. Curvenote built working support for AnyWidgets as a MyST Markdown extension while working with researchers to support domain specific visualizations, and then upstreamed the implementation to create the {anywidget} directive that has just been released in mystmd and jb2.

The new directive in mystmd and the respective supporting package in @myst-theme/anywidget evolved with input from the JupyterBook team. Here’s how it is currently structured:

anywidget is a new node in the MyST AST, meaning first-class support for this capability outside of notebooks.
mystmd will bundle ESM and CSS modules at build time, ensuring dependencies are packaged with the book/article when it is published or deployed.
The ESM and CSS modules can either be (a) hosted remotely (which makes sense for shared widgets that many people are using or collaborating around) or (b) added as local files (which makes sense for widgets specific to a single book/website).
The NodeRenderer part of the release is an independent package @myst-theme/anywidget that can be optionally adopted by theme developers (it’s already built into the core themes).
For mystmd and Jupyter Book users, to upgrade to the latest theme. Run myst clean --templates before you next start your server and the latest version will be downloaded.

Usage

From an author’s perspective, point the directive at an ESM module (either a URL to a hosted script or a local path) and the widget runs in the page with its own state and DOM. You may optionally pass in a CSS URL/path and a JSON body of props to initialize the widget model.

To understand how to build your own widgets, the MyST widgets guide walks through the render({ model, el }) signature, styling with Shadow DOM, and cleanup on unmount. It’s the same mental model as anywidget in Jupyter, so if you’ve written or seen Jupyter AnyWidgets, you’re already most of the way there.

If you want to try it, the example-widgets repo has small demos (confetti, div-map, etc. Contributions are welcome!), and the opensci.dev blog has some live examples using scientific datasets.

What’s next

Widget support in MyST is still marked experimental so the details may evolve. There are still some things on the roadmap for {anywidget} which will no doubt expand as we hear of new requirements from widget creators, but we expect the following to be close to the top of the stack:

The model part of the interface, which will allow multiple instances of a widget to communicate on the page[1]
Shipping additional dependencies like static files that the widgets may need

The JupyterBook team is actively working on improving and evolving the widget model and integrating with Jupyter. We look forward to seeing what the community builds — visit the discord to showcase what you have built!

Acknowledgements

A shout out to my co-contributors on this work; to @mantz for the original hacking, @rowanc1 and @fwkoch for iterating on the downstream code, @agoose77 for working with me on the upstream changes, @choldgraph for insightful reviews and a docs! and the broader Jupyter Book Team for all the reviews and feedback.

Call for applications: Community Manager for JupyterHub and Jupyter Book

2026-03-05T16:44:00+00:00

The JupyterHub and Jupyter Book communities are hiring a community manager.

Join our community and support us all to grow, nurture, and build things together. Credit: The Turing Way and Scriberia, used under a CC-BY license https://doi.org/10.5281/zenodo.3332808

In JupyterHub, we are democratizing access to interactive computing environments to allow everyone, no matter where they are, to explore data, develop code, and advance knowledge without barriers. In Jupyter Book, we are building the next generation of open, community-driven technical publication tooling, leveraging the MyST document engine to create modular, reusable, and reproducible computational narratives.

We are excited to fund dedicated time for someone — maybe you! — to join these teams.

The community manager will be responsible for identifying and developing activities and communication pathways that align maintainer and contributor actions with the goals of each project, and that build bridges across the Jupyter ecosystem.

You can read more about our motivation for this role in the proposal, part of the Jupyter Foundation’s Community Funding initiative. We particularly encourage applicants to review the section “Impact Metrics: How do we define success?”

In this blog post we have outlined the community manager’s responsibilities, their preferred expertise, and how to apply.

This is a contract role, funded at $90,000 to be spent by the end of April 2027. The community manager will be engaged as a contractor of the Linux Foundation and will follow the standard Linux Foundation contractor onboarding process.

The deadline to apply is 29 March 2026.

Responsibilities

Strategic alignment and contributor guidance

Collaborate with the maintainer teams from both projects to understand, document, and broadcast each project’s priorities to their communities.
Actively connect contributors to open issues and workstreams that align with the respective project’s goals, and redirect well-intentioned contributions that are not aligned with the project’s currently prioritized efforts.
Efficiently connect contributors with maintainers to provide them the guidance and review needed to make efficient progress, managing workload on both sides of the mentorship pair.

Contributor growth and leadership development

Design, visualize, and manage a clear contributor journey, including identifying requisite skills and project context knowledge, for each community.
Identify engaged community members and create pathways for them to take on more responsibility, such as triaging issues, reviewing pull requests, or mentoring others within their project of interest.

Fostering knowledge sharing and collaboration

Identify and create opportunities for the community of each project to share information, best practices, and technical knowledge, while respecting their distinct roadmaps.
Facilitate cross-community events, such as running “collaboration cafes” for both JupyterHub and JupyterBook, and strategically shape them into meetings that provide value and foster connection for both projects.
Develop re-usable templates for explaining contributor pathways, such as onboarding documentation, skills maps/matrices for progression into contribution and maintenance roles, and collaboration cafe guides.

Learn in the open

Ensure all materials are publicly available and discoverable, including progress against our community health metrics described below.
Promote these learnings across the Jupyter community including within the Zulip channel, at regular community calls, and by “visiting” other sub-projects (at synchronous meetings or in asynchronous discussion spaces) to discuss community management efforts as requested.
Join the Jupyter Community Building Working Group and be an active member throughout their paid time on the project.

Preferred expertise

We have not marked any of the expertise categories listed here as required. We recognize that we are looking for a unicorn, and they are curiously hard to find! If you do not have expertise across all of these categories we encourage you to apply. We are looking forward to getting to know candidates better, including where they have identified opportunities for career and skill development as part of the JupyterHub and Jupyter Book teams.

Our assessment pathway is included as part of this list to guide applicants in curating their strongest application. If you are uncertain how to answer any of the questions and/or prompts, please ask in our Jupyter Hub Zulip channel or email Kirstie Whitaker directly at kirstie.whitaker@berkeley.edu.

Track record of contributions to open source projects.

Assessment: Cover letter & links

Understanding of multi-stakeholder, community governed open source community dynamics.

Assessment: Interview question. Describe two situations — one featuring a success and one a failure — where you have sought to align diverse stakeholders around a common goal. For both, share what you learned from the experiences.

Understanding of the challenges that Jupyter Hub and Jupyter Book are designed to solve (or reduce) in the world.

Assessment: Interview question. Describe two deployments — one each of Jupyter Hub and Jupyter Book — that each meet a need in either education, research or technical development. You do not need to have run these deployments yourself.

Technical skills in Python and/or TypeScript.

Assessment: Cover letter & links

Track record of identifying and completing tasks in the presence of significant uncertainty.

Assessment: Cover letter

Ability to work effectively with two distinct and diverse teams whose community members are geographically distributed with significant time zone differences.

Assessment: Cover letter. All instructions from this recruitment call followed, the letter is clearly and concisely written, includes concrete examples, and publicly accessible links where appropriate.
Assessment: Interview question. Given your knowledge of Jupyter Hub and Jupyter Book, and your previous experience, how will you know if you are working effectively within these two communities?

Ability to ask for help and self manage time allocations and tasks.

Assessment: Interview question. Which aspects of this role do you think will be hard for you? Which aspects will be easy (or easier) for you? Where do you expect to ask for help and/or support in the role?

How to apply

Submit a cover letter and resume through this Google Form: https://forms.gle/Qw6ddyJ8rzZY5vQm6

Please include:

Your motivation to apply for this role.

Links to up to 3 publicly available GitHub repositories that highlight engagement in issues, pull requests, community discussions (or equivalent conversations on alternative git forge platforms).

If you don’t have publicly available links, provide a letter from a team member from a private initiative who can endorse these collaboration skills.
If you can not meet this requirement, please note that in your application.

Links to up to 3 examples of code you have written in Python and/or TypeScript.

If you don’t have publicly available links, provide a letter from a team member on a private initiative endorsing these development skills.
If you can not meet this requirement, please note that in your application.

A description of a previous role (paid or volunteer) where you have identified and delivered outcomes in the presence of uncertainty.

Include links to task documentation (issue / PR / report) if publicly available.
If you can not meet this requirement, please note that in your application.

What to expect

We’ll accept applications from now through 29 March, 2026.

Once applications are in, here’s our process:

Resume and cover letter review: The recruitment panel will review all applications and invite up to 5 applicants for an interview on zoom at a time that is convenient for the applicant and the panel members.
Interview: The recruitment panel will meet with applicants for 30 minutes over Zoom. They will ask the same questions of every applicant.
Panel discussion & alignment: The recruitment panel will discuss interview outcomes and align on a decision.
Offer: We expect to communicate a final decision to all applicants by 30 April, 2026.

Timeline

29 March 2026, AoE: Deadline for resume and cover letter applications.
Before 5 April 2026: Invite up to 5 applicants to interview.
8 April — 17 April 2026: Interviews conducted over Zoom.
Before 11 May 2026: Communicate final decision to all applicants.
May 2026: Post holder coordinates a contract with the Linux Foundation, following their standard onboarding process.

Acknowledgements

This job description was co-created by April Johnson, Yuvi, and Kirstie Whitaker, with guidance from Chris Holdgraf, Min Ragan-Kelley, Raniere Silva, and Stéfan van der Walt, along with community input at the JupyterHub and Jupyter Book collaboration cafes.

Announcing the new Jupyter Book

2020-08-12T19:55:00+00:00

Note: this announcement is cross-posted between the Jupyter Blog and the Executable Book Project updates blog

Jupyter Book is an open source project for building beautiful, publication-quality books, websites, and documents from source material that contains computational content. With this post, we’re happy to announce that Jupyter Book has been re-written from the ground up, making it easier to install, faster to use, and able to create more complex publishing content in your books. It is now supported by the Executable Book Project, an open community that builds open source tools for interactive and executable documents in the Jupyter ecosystem and beyond.

The new Jupyter Book interface, highlighting how you can insert code outputs into your content

This post is a short overview of the new features in Jupyter Book, and gives some background on the future of the project.

You can also browse the new Jupyter Book documentation, or check out the Jupyter Book GitHub repository.

❗❗ Jupyter Book is still in beta, so things are always changing. We’d love your feedback, ideas, and PRs for how to make the project better!❗❗

What does the new Jupyter Book do?

The new version of Jupyter Book will feel very similar. However, it has a lot of new features due to the new Jupyter Book stack underneath (more on that later).

The new Jupyter Book has the following main features (with links to the relevant documentation for each):

✅ Write publication-quality content in markdown
You can write in either Jupyter markdown, or an extended flavor of markdown with publishing features. This includes support for rich syntax such as citations and cross-references, math and equations, and figures.

✅ Write content in Jupyter Notebooks
This allows you to include your code and outputs in your book. You can also write notebooks entirely in markdown to execute when you build your book.

✅ Execute and cache your book’s content
For .ipynb and markdown notebooks, execute code and insert the latest outputs into your book. In addition, cache and re-use outputs to be used later.

✅ Insert notebook outputs into your content
Generate outputs as you build your documentation, and insert them in-line with your content across pages.

✅ Add interactivity to your book
You can toggle cell visibility, include interactive outputs from Jupyter, and connect with online services like Binder.

✅ Generate a variety of outputs
This includes single- and multi-page websites, as well as PDF outputs.

✅ Build books with a simple command-line interface
You can quickly generate your books with one command, like so: jupyter-book build mybook/

These are just a few of the major changes that we’ve made. For a more complete idea of what you can do, check out the Jupyter Book documentation

Major changes

In the next few sections we’ll talk about some major changes that you may notice in Jupyter Book.

An enhanced flavor of markdown

The biggest enhancement to Jupyter Book is support for the MyST Markdown language. MyST stands for “Markedly Structured Text”, and is a flavor of markdown that implements all of the features of the Sphinx documentation engine, allowing you to write scientific publications in markdown. It draws inspiration from RMarkdown and the reStructuredText ecosystem of tools. Anything you can do in Sphinx, you can do with MyST as well.

MyST Markdown is a superset of Jupyter Markdown (AKA, CommonMark), meaning that any default markdown in a Jupyter Notebook is valid in Jupyter Book. If you’d like extra features in markdown such as citations, figures, references, etc, then you may include extra MyST Markdown syntax in your content.

For example, here’s how you can include a citation in the new Jupyter Book:

A sample citation. Here we see how you can include citation syntax in-line with your markdown, and then insert a bibliography later on in your page.

And here’s how you can include a figure:

A sample figure. Here we see how you can insert a figure with a caption into your book, and control some aspects of how the figure is displayed with options.

A smarter build system

While the old version of Jupyter Book used a combination of Python and Jekyll to build your book’s HTML, the new Jupyter Book uses Python all the way through. This means that building the HTML for your book is as simple as:

jupyter-book build mybookname/

In addition, the new build system leverages Jupyter Cache to execute notebook content only if the code is updated, and to insert the outputs from the cache at build time. This saves you time by avoiding the need to re-execute code that hasn’t been changed.

An example build process. Here the jupyter-book command-line interface is used to convert a collection of content into an HTML book.

More book output types

By leveraging Sphinx, Jupyter Book will be able to support more complex outputs than just an HTML website. For example, we are currently prototyping PDF Outputs, both via HTML as well as via LaTeX. This gives Jupyter Book more flexibility to generate the right book for your use case.

You can also run Jupyter Book on individual pages. This means that you can write single-page content (like a scientific article) entirely in Markdown.

A new stack

The biggest change under-the-hood is that Jupyter Book now uses the Sphinx documentation engine instead of Jekyll for building books. By leveraging the Sphinx ecosystem, Jupyter Book can more effectively build on top of community tools, and can contribute components back to the broader community.

Instead of being a single repository, the old Jupyter Book repository has now been separated into several modular tools. Each of these tools can be used on their own in your Sphinx documentation, and they can be coordinated together via Jupyter Book:

The MyST markdown parser for Sphinx allows you to write fully-featured Sphinx documentation in Markdown.
MyST-NB is an .ipynb parser for Sphinx that allows you to use MyST Markdown in your notebooks. It also provides tools for execution, cacheing, and variable insertion of Jupyter Notebooks in Sphinx.
The Sphinx Book Theme is a beautiful book-like theme for Sphinx, build on top of the PyData Sphinx Theme.
Jupyter Cache allows you to execute a collection of notebooks and store their outputs in a hashed database. This lets you cache your notebook’s output without including it in the .ipynb file itself.
Sphinx-Thebe converts your “static” HTML page into an interactive page with code cells that are run remotely by a Binder kernel.
Finally, Jupyter Book also supports a growing collection of Sphinx extensions, such as sphinx-copybutton, sphinx-togglebutton, sphinx-comments, and sphinx-panels.

We’ll write a more developer-focused post in the future to describe each of these components in more detail.

What next?

Jupyter Book and its related projects will continue to be developed as a part of the Executable Book Project, a community that builds open source tools for high-quality scientific publications from computational content in the Jupyter ecosystem and beyond.

If you’d like to learn more about Jupyter Book or get started building your own books, then check out the new Jupyter Book documentation. Jupyter Book is still in beta and is constantly being improved, so your feedback and contributions are always welcome.

If there are particular features you’d like to see, open an issue or give a 👍 to a pre-existing issue, and it will be bumped up on the feature request leaderboard.

Get involved

If you’d like to contribute to any of the projects listed in this post, you are highly encouraged to do so! The Executable Book Project (and thus Jupyter Book) is run as an open project that welcomes contributions from others.

We are excited about all the new features and improvements in the new Jupyter Book, and look forward to seeing the new books that the community creates with this stack!

Jupyter Blog - Jupyter Book

Navigating the Post-Workshop Fog: a Path to Myst

Milestones

One step at a time

Sidewalks

Wandering

Becoming the new JupyterHub and Jupyter Book community manager

A Jupyter Workshop: Demystifying MyST Markdown in Education

What’s it about?

Where and how to join

Thanks

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

Why is this useful?

Proxying sub-sites with Netlify rewrites

Shared configuration with extends

One gotcha: BASE_URL for asset paths

internal_domains for cross-site navigation

Want to do this too?

Acknowledgements

The MyST AnyWidget Directive

What this means

How we got here

Usage

What’s next

Acknowledgements

Call for applications: Community Manager for JupyterHub and Jupyter Book

Responsibilities

Preferred expertise

How to apply

What to expect

Acknowledgements

Announcing the new Jupyter Book

What does the new Jupyter Book do?

Major changes

An enhanced flavor of markdown

A smarter build system

More book output types

A new stack

What next?

Get involved

Shared configuration with `extends`

One gotcha: `BASE_URL` for asset paths

`internal_domains` for cross-site navigation