Jupyter Blog - MyST

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.

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.

What’s New in MyST Markdown 1.8.2

2026-03-26T15:10:00+00:00

The Jupyter Book team just released mystmd 1.8.2 and a new version of the MyST react theme! Below are a few things that stand out.

Interactive widgets with the `{anywidget}` directive

You can now embed JavaScript widgets in your MyST pages using the new {anywidget} directive. Widgets follow the anywidget specification, which gives plugin authors an extension point for embedding JS capabilities in their documents.

A widget is a JavaScript module that exports a render function. You pass it initial state as JSON in the directive body, and it renders an interactive element on the page. You could use this for interactive figures, explorable explanations, or custom visualizations without leaving MyST.

A little confetti demo that we use to show off embedding widgets in a MyST document with anywidget!

Note*: Widget support is experimental. The interfaces may change as we learn more about usage patterns. Only load widgets from sources you trust, since they execute JavaScript in the reader’s browser!*

Table of contents improvements

The {toc} directive now supports a children context option, which lets you display only the child pages of the current page rather than the full project table of contents. Use it on landing pages and index pages that introduce a section and link to its sub-pages. You can see an example in the Jupyter Book getting started guide.

Better link handling across multi-site projects

If your project spans multiple domains (e.g., a docs site and a blog), you can now configure a domain to be treated as “internal” for link styling. Links to that domain will look like in-site navigation instead of external links. Check out the Getting Started guide for an example.

Upgrade

To get the latest version of mystmd:

npm install -g mystmd

or for pip users:

pip install -U mystmd

The theme updates automatically. Delete your _build folder and mystmd will download the latest theme on your next build.

Changelogs

Find an ongoing list of releases in the Jupyter Book ecosystem here:

jupyterbook.org/releases

You can also read the original mystmd release notes and myst-theme release notes.

Jupyter Blog - MyST

Navigating the Post-Workshop Fog: a Path to Myst

Milestones

One step at a time

Sidewalks

Wandering

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

What’s New in MyST Markdown 1.8.2

Interactive widgets with the {anywidget} directive

Table of contents improvements

Better link handling across multi-site projects

Upgrade

Changelogs

Shared configuration with `extends`

One gotcha: `BASE_URL` for asset paths

`internal_domains` for cross-site navigation

Interactive widgets with the `{anywidget}` directive