Jupyter Book vs. MyST Engine - a brief guide to using and contributing to each one

[choldgraf]

We've had a bunch of people ask about the differences between Jupyter Book and the MyST Document Engine. This write-up provides my understanding of the difference between the two. My goal is to clarify the relationship between Jupyter Book and the MyST Engine, and provide guidelines for how to decide where to focus your time and effort! I tried to consolidate content from places where this has been discussed (see the bottom for that list).

Note

Please ask questions and suggest changes to this guide and we can update it!

A note on terminology

"Jupyter Book" has three meanings that can cause confusion:

1. Jupyter Book 1 - the original tool built on Sphinx - https://jupyterbook.org/v1
2. Jupyter Book 2 - the current tool built on MyST Engine - https://jupyterbook.org/stable
3. The Jupyter Book project/community - the broader initiative - https://compass.jupyterbook.org

This means you can have "a jupyter book built with MyST made by the Jupyter Book team." In this document, "Jupyter Book" refers to Jupyter Book 2 unless otherwise specified.

Who should use Jupyter Book vs. MyST?

Use Jupyter Book if you're creating books, documentation sites, or community websites with standard needs. Use MyST Engine if you need heavy customization, are building your own publishing tools and applications, or want fine-grained control over the pipeline.

Jupyter Book is designed for typical users with an opinionated, accessible tool focused on multi-page documents and the "book theme" aesthetic. Think: educational materials, research documentation, community websites where sensible defaults "just work."

The MyST Engine is a power-user tool emphasizing flexibility, modularity, and control. It's agnostic about output formats and features an extensive plugin ecosystem for custom publishing workflows or building tools on top of MyST.

This is a pattern that we wish to encourage and grow in the MyST ecosystem. Tools like the MyST Document Engine aim to be unopinionated, modular, configurable, and extendable. They’re primarily meant for use by power users and developers who are interested in configuring MyST tools for their own needs/community, or building MyST tools into separate applications. Jupyter Book 2 is meant for end-users like researchers and educators who want an opinionated system for communicating computational narratives that “just works”.
-- from the JB2/MyST paper

Technical relationship

MyST is the engine, Jupyter Book is an opinionated distribution built on top of it. This mirrors how Jupyter Book 1 related to Sphinx: Sphinx was the engine, JB1 provided a configurable theme, workflows, and configurations for books.

Currently (early 2025), Jupyter Book 2 and MyST are very similar in practice. The vision is for them to diverge over time: MyST remains the flexible foundation, while Jupyter Book adds features particularly useful for books and websites (specialized directives, book-specific themes, workflow tooling).

Why documentation is intermixed

Jupyter Book 2 launched with new architecture, but documentation is still catching up. MyST is reaching feature parity with JB1's Sphinx-based capabilities (see known limitations of JB2), and some content documented in MyST first needs proper integration or cross-references in JB docs.

This creates confusion about where to find information and where to report issues. The team is actively working to clarify this as both projects mature!

Documentation guidelines for contributors

Document in Jupyter Book if it's about using JB's curated workflow with standard configurations. Document in MyST Engine if it's about core engine features, plugins, or heavy customization. When in doubt, write in one location and cross-link from the other.

The guidance follows the Diátaxis framework: Jupyter Book focuses on tutorials and how-to guides for typical workflows (creating books, configuring themes, exporting with default settings), while MyST provides reference documentation, engine explanations, and customization guides (re-use MyST components in applications, plugin APIs, build your own themes).

Examples: "How to create your first book" goes in Jupyter Book. "MyST directive syntax reference" goes in MyST Engine. "Enabling a plugin in your book" and "Write a basic plugin" goes in Jupyter Book with a link to the plugin docs in MyST for full customizability.

Long-term vision

This split is a "best-effort description" that continues to evolve. The team will reassess as Jupyter Book 2.0 matures and user patterns become clearer. The goal: make Jupyter Book highly accessible for typical workflows, keep MyST flexible for advanced users, minimize confusion through clear cross-references, and avoid content duplication while ensuring each tool has standalone documentation.

References where this has been discussed before

1. This section of the JB2/MyST paper
2. Clarify the difference between Jupyter Book and the MyST engine and when to use each jupyter-book#2394
3. Planning: Short-term plan for Jupyter Book 2.0 documentation vs. mystmd.org/guide jupyter-book#2239
4. https://github.com/orgs/jupyter-book/discussions/1774
5. MyST Documentation: JB vs MyST section

[KirstieJane]

The logic makes sense to me 💯

Maybe worth also adding here that there are THREE meanings of "Jupyter Book":

• Jupyter Book 1: built with sphinx
• Jupyter Book 2: built with MyST

These are both documented in @choldgraf's post above 👆🌟

👉 The project and community are also called Jupyter Book 😄

And the MyST engine sits within that project.

So you can have a "jupyter book" built with "MyST" made by the "Jupyter Book" team ❤️

[choldgraf]

done!