New release: myst-theme 2.0 with an upgraded web stack, breadcrumbs, and redirects

We’ve just released myst-theme 2.0.0!^[1] This brings in a full-upgrade of the infrastructure behind our web stack. It will make it more performant, easier to build into modern web applications, and easier to extend in the future. It is incompatible with some older versions of mystmd, which is why this is a major release. This release also comes with a few new features for authors, like breadcrumbs and redirects.

For authors¶

• Breadcrumbs in the book theme. Pages now show a breadcrumb trail above the title, like 🏠 › Reference › Admonitions. It follows the nesting of your table of contents, so readers can see where they are in the context of your book or documentation. You can turn it off with site.options.hide_breadcrumbs: true.

• Redirects for moved pages. If you rename or move a page, you can now redirect the old URL to the new one with site.options.redirects, so old links keep working (only in the book theme for now).

• WebM videos. The theme now plays .webm files as videos.

• Bug fixes. Navbar links now look like the other navbar items, and the mobile sidebar can be dismissed on pages that use hide_toc.

For developers building on MyST¶

• The theme now uses React Router 8 and Vite. We upgraded the theme from Remix to React Router 8, the successor to Remix. This puts the theme on tooling that is more actively maintained, and should make it easier to build on. If you’ve customized or forked the theme, you may need to update your code!

• Native static HTML builds. The theme now renders its own static HTML using the render command added in mystmd 1.11.0 (previously, mystmd would start a server and crawl every page). This should be more efficient and reliable. The theme also ships with its dependencies fully-bundled, so it no longer needs to install dependencies on your machine.

• Multi-project sites are no longer supported. The 2.0 theme drops support for sites made of multiple projects. These have been 🟢 deprecated for some time, and this removes multi-project logic from the theme.

Changelogs¶

You can also read about this release at jupyterbook.org/releases. For more details, see the myst-theme release notes.

Upgrade notes¶

Upgrade mystmd or jupyter-book first, then delete _build so the new theme is downloaded on your next build.

npm install -g mystmd

pip install -U mystmd

pip install -U jupyter-book

rm -rf _build

Try it out!¶

This is a big change under the hood, so we’d love your feedback! Try the new release and open an issue if something breaks.

Thank you contributors!¶

This release would not have been possible without the help of our community! Thanks to everyone who contributed discussions, ideas, code, and review across this release: @agoose77, @choldgraf, @goekce, @pancakereport, @rowanc1, and @stefanv.