We’ve published a new paper in the SciPy Proceedings from 2025 It describes the design principles and architecture of Jupyter Book 2 and the MyST Document Engine. Read the full paper here.
Figure 1:High-level overview of Jupyter Book 2 components. JB2 combines several components in the MyST ecosystem, configured for multi-document workflows such as community knowledge bases, websites, and books. The MyST Document Engine parses MyST Markdown (and other flavors of text-based content) into an Abstract Syntax Tree (AST) that follows the MyST Document Specification. It resolves and transforms this AST to enrich it with extra document metadata (such as resolving DOIs). The engine then renders this AST to React components that are bundled with the Book Theme, which makes up the end-user application most-often used with JB2.
Key principles¶
The paper outlines five design principles that guide Jupyter Book 2 and the MyST ecosystem:
Simple to use, easy to extend: A rich plugin ecosystem lets you customize MyST’s behavior without modifying core code.
Canonical and machine-readable: Content is represented as a structured abstract syntax tree (AST) that can be easily parsed and transformed.
Modular and composable: Documents can be easily parsed, transformed, and remixed across projects.
API-accessible and federated: MyST sites expose their content as structured data, enabling cross-project references and content embedding.
Computation is first-class: Jupyter notebooks and computational outputs are treated as core content types, with built-in execution and caching.
Join us¶
We’re inviting the community to explore these ideas, try out Jupyter Book 2, and help shape the next generation of scientific publishing tools. Check out the paper to learn more about the technical details and design decisions.
Links:
- Jupyter, P., Bolyen, E., Caporaso, J. G., Cockett, R., Garside, D., Holdgraf, C., Hollands, A., Kent, J., Koch, F., Madge, J., McKay, M., Morrison, M., Pérez, F., Purves, S., Kelley, M. R., Rose, B. E. J., Sharan, M., Sipőcz, B. M., Walt, S. J., & Whitaker, K. J. (2025). Jupyter Book 2 and the MyST Document Stack: A modular, extensible, web-native stack for authoring and publishing computational narratives. Proceedings of the 24th Python in Science Conference, 173–193. 10.25080/hwcj9957