diff --git a/content/blog/2024/jupyter-book-2/featured.png b/content/blog/2024/jupyter-book-2/featured.png new file mode 100644 index 00000000..5be01b98 Binary files /dev/null and b/content/blog/2024/jupyter-book-2/featured.png differ diff --git a/content/blog/2024/jupyter-book-2/index.md b/content/blog/2024/jupyter-book-2/index.md new file mode 100644 index 00000000..b00cc97f --- /dev/null +++ b/content/blog/2024/jupyter-book-2/index.md @@ -0,0 +1,102 @@ +--- +title: Announcing the Jupyter Book 2 alpha +date: "2024-11-18" +banner: + image: "featured.png" +authors: ["Jenny Wong"] +tags: [open-source] +categories: [] +featured: false +draft: false +--- + +*Cross-posted from the [Jupyter Book blog](blog.jupyterbook.org/). Note that some MyST functionality is not supported on the 2i2c website – please see the original post for previews.* + +![Jupyter Book 2 logo](featured.png) + +Over the last ten months, the Jupyter Book team have been hard at work; Jupyter Book has [become a Jupyter subproject](https://github.com/jupyter/governance/pull/229), and the team[^jb-eb] announced a [plan to release Jupyter Book 2][plan]. This post announces the **alpha release of Jupyter Book 2.0**, which has been re-written from the ground up to use the new MyST-MD engine. + +Over the next few months, we will work in preparation for the full release of Jupyter Book 2. Stay tuned for more! The initial documentation for the alpha release can be found at: + + + +## Install the Jupyter Book 2 Alpha + +The Jupyter Book 2 alpha is available from PyPI.org. You can install it with `pip`, using + +```shell +pip install -U jupyter-book==2.0.0a0 +``` + +If you use `pipx`, it's recommened to run Jupyter Book 2 using + +```shell +pipx run jupyter-book==2.0.0a0 +``` + +Jupyter Book 2 needs Node.js installed on your computer. If this is not the case, running `jupyter book` will prompt you to install it using the `nodeenv` package that ships with Jupyter Book 2: + +``` +❗ Node.js (node) is required to run Jupyter Book, but could not be found`. +❔ Install Node.js in '...'? (y/N): +``` + +Press `y` and `Enter` to proceed. + +{{% callout note %}} +The Jupyter Book 2 project is a complete re-write of Jupyter Book. We expect there to be bugs and breakages! Please use our support channels to keep us up to date with your findings! + +- [Discord](https://discord.mystmd.org/) +- [GitHub Issues](https://github.com/jupyter-book/jupyter-book/issues/new?template=prerelease.yml) +{{% /callout %}} + +## New Features in `2.0 alpha` + +### Rich Hover Previews + +Try hovering over [this tooltip about tooltips!](https://en.wikipedia.org/wiki/Tooltip). The new MyST book and article themes provide useful hover previews for links to other MyST content, Wikipedia, GitHub issues, and many more. + + + +### Share & Embed Content + +Content from other websites built with the MyST engine can be embedded in your own sites and PDFs: + +![Image of a mountain range.](https://cdn.curvenote.com/0192bff5-9c9d-722f-92bf-e702aa8e1f46/public/c8830546aa82907becb6cd46c414a80c.webp "Cross-referenced content can easily be embedded and re-captioned into other pages and projects, such as this figure to .") + +### Simple Instant Search + +A new client-side search uses a simple, modern algorithm for fast _local_ search that finds the results that you care about. + +![Screenshot of a search bar.](https://github.com/jupyter-book/blog/blob/main/media/search.png?raw=true "Client-side search uses simple, modern, [Algolia](https://algolia.com)-inspired search algorithm to provide _useful_ search results. We will be iterating on this in the near future for even richer search results!") + +### High Quality PDFs + +PDF documents can now be built with Typst, a high-quality typesetting engine that produces readable error messages and beautiful documents. This feature was the basis for the 2024 [SciPy proceedings][proceedings], which is now built on MyST Markdown and will be accepting Jupyter Notebooks in 2025. + +![An example preprint using the LaPreprint template.](https://raw.githubusercontent.com/rowanc1/LaPreprint/68f5ccbf1e1e26819149bcea1d547dfdfc5ceecd/example/files/screenshot.png "Example of the LaPreprint Typst template for rendering PDFs from Jupyter Book (via the MyST Engine).") + +## Coming Soon in `2.0 beta` + +### Custom Styles & Scrips + +Jupyter Book 2 will make it easy to tweak your website styles, and add new website behaviors. + +### Generate Markdown from Code Cells + +The MyST engine is on-track to support the inclusion of references and other markup features generated by code cells. + +### Control Cell Visibility with Tags + +In the beta release, Jupyter Book 2 will once-again be able to show and hide content according to cell tags. + +## Jupyter Book 2 vs MyST-MD + +At this early stage, the new Jupyter Book application `jupyter book` behaves identically to the `mystmd` engine that it is built upon; as outlined in [our Jupyter Book 2 plan][plan], we intend for Jupyter Book to be an "opinionated distribution" of `mystmd` that shares the same configuration format and CLI. This contrasts with Jupyter Book 1, which was built on top of the Sphinx documentation engine, but offered its own CLI and configuration files. In future, the `jupyter book` and `mystmd` CLIs may diverge from one another, but we expect that this will be handled in a graceful manner: `mystmd` commands should always be compatible with the `jupyter book` application. + +[proceedings]: https://proceedings.scipy.org +[plan]: https://executablebooks.org/en/latest/blog/2024-05-20-jupyter-book-myst/ + +[^jb-eb]: Jupyter Book project has historically been a _technical_ project of the Executable Books organisation. In 2024, the establishment of a Jupyter subproject means that the Jupyter Book project now has its own identity outside of Executable Books.