Jupyter Book: publication-quality books from Markdown and notebooks

What the tool does, stated as a list of four capabilities

The README describes Jupyter Book as an open-source tool for building publication-quality books and documents from computational material, and then enumerates what that means in four bullets.

You write content in Markdown files or Jupyter notebooks. You can include computational elements such as code cells in either format, which is the part most documentation tools cannot do. You can include rich syntax covering citations, cross-references and numbered equations. And with a single command you run the embedded code cells, cache the outputs, and convert the whole thing into both a web-based interactive book and a publication-quality PDF.

Producing both formats from one source is the point of the project. A lecture-notes or textbook workflow usually ends with either a website nobody can print or a PDF nobody can search. Running the code cells and caching their outputs is also what makes the book reproducible: if a figure in chapter four came from a cell, the cell is still there and still runs.

The project is an official sub-project of Jupyter, with governance described in the Jupyter Team Compass, which is worth noting because it means release decisions are not made by a single maintainer's schedule. It is primarily developed by the Jupyter Book Project.

Version 2 replaced Sphinx with MyST, and v1 moved to a branch

The most consequential line in the README is a note, not a paragraph. It reads: are you trying to access Jupyter Book v1, the Sphinx-based documentation engine? That package now resides in the `v1` branch of this repository.

That single sentence tells you the project was rebuilt rather than iterated. The v1 line was a Sphinx extension, so it inherited Sphinx's plugin ecosystem, its theme machinery and its Python build system. The v2 line is built on MyST, a Markdown flavor that parses into an internal AST, and the repository language on GitHub is now TypeScript. In the tree, `ts/` is the engine and `py/` is the packaging layer, alongside `package-lock.json` and `package.json` on one side and `pyproject.toml` on the other.

So the version choice is not incremental. If you have an existing Sphinx-based book, your extension plugins and theme overrides do not carry over. If you are starting fresh, v2 is the only thing worth evaluating, and you should read the current documentation at jupyterbook.org rather than searching for Sphinx-era tutorials, which will describe an engine this version no longer uses.

The repository also carries `flake.nix` and `flake.lock` alongside `noxfile.py`, so there is a Nix path for reproducible development environments and a nox path for task running. Both exist for contributor ergonomics rather than for end users.

The 2.1.x releases are mostly upstream dependency moves

Three releases are visible and they land about two months apart: v2.1.4 on 2026-04-01, v2.1.5 on 2026-05-02 and v2.1.6 on 2026-07-05. The last push to master was 2026-09-09.

Reading their notes tells you how the project actually works now. v2.1.6 is described as maintenance and upkeep, and the first item is a bump of myst-cli to v1.10.1 with the pull request and author named. v2.1.4 is the same shape, bumping the myst version. v2.1.5 is the informative one: it says it brings in two new releases plus several bugfixes, accessibility improvements and enhancements in mystmd and myst-theme, then links directly to the release notes for mystmd 1.9.0 and myst-theme.

So Jupyter Book v2 is a thin, well-maintained layer over two upstream projects that carry most of the weight. That is a good thing if you want bugfixes and accessibility improvements to arrive without waiting for a Jupyter Book release, and it is a thing to be aware of if you hit a behavior you cannot explain, because the fix may live one repository over. The upstream version is part of your effective version, whether or not the changelog for this project mentions it.

Each release note also links a full changelog comparison, which is the fastest way to see whether a patch release contains anything you actually need.

What to look at in the tree if you want the internals

Beyond the standard project files, the tree has a few directories worth knowing about. `docs/` holds the documentation for Jupyter Book itself. `py/` is the Python package, which is what you install. `ts/` is the TypeScript implementation, which is the part that grew when the project moved off Sphinx.

There is a `RELEASE.md` at the root, which tells you the release process is documented rather than tribal, and `CHANGELOG.md` plus `CONTRIBUTING.md` for the day-to-day. `CONTRIBUTING.md` is linked prominently from the README with a request that covers both typos and features, which is a reasonable ask for a documentation tool.

For contributors, `noxfile.py` is the important file. Combined with the flake, it means there is a defined local development path rather than an ad-hoc virtualenv. There is also a `.readthedocs.yaml`, so the project's own documentation builds on Read the Docs.

Licence is BSD-3-Clause, which is permissive and appropriate for a build tool. The DOI badge in the README exists so you can cite the software in academic work, which matters more here than in most projects, because Jupyter Book is itself a tool for producing citable documents.

Editorial conclusion

Jupyter Book is the right tool when your documentation needs to be a book: numbered equations, citations, cross-references, executable code cells and a PDF at the end, all authored in Markdown or notebooks. The v2 line is the one to use, and it is a genuinely different engine from v1 rather than a feature release, since the Sphinx base was replaced by MyST and the package itself is now primarily TypeScript with a Python wrapper. Two cautions. The README's own note sends v1 users to a branch rather than a release, so treat v1 as end-of-life and plan around it. And the release notes are mostly dependency bumps into myst-cli and myst-theme, which means the interesting changes arrive when those projects move rather than when this one does. Read the docs at jupyterbook.org, check the `ts/` directory if you want to understand the engine, and set up `noxfile.py` if you plan to contribute, since that is how the project expects local work to happen.

Frequently asked questions

Official sources

1. jupyter-book/jupyter-book on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases