Thread by @choldgraf

After many months of work we are excited to announce the new Jupyter Book!

blog.jupyter.org/announcing-the…

This is a complete re-write of Jupyter Book to make it more modular, powerful, customizable, and easy to use. See this 🧵 for some highlights!

First off, Jupyter Book is now built entirely on top of the excellent Sphinx documentation engine (sphinx-doc.org). This means Jupyter Book is much more modular and has all the documentation features of Sphinx (while still letting you write in markdown)

Why use Sphinx? It means that we can get publication-quality features and syntax out of the box. For example, here's how to add citations to your book:

"But Chris", you ask, "I thought that Sphinx uses reStructuredText?!".

Well I'm glad you asked. Jupyter Book also supports a flavor of Markdown that lets you use all of Sphinx's functionality in 💯 markdown. It's called Markedly Structured Text, or MyST

jupyterbook.org/content/myst.h…

did I mention that the new Jupyter Book is modular and builds on other OS tools? That's right - you can also use MyST markdown totally independently of Jupyter Book, e.g., as a Sphinx extension for your documentation:

myst-parser.readthedocs.io

another benefit of the new build system is that you only need Python to build your book's HTML, no more painful Jekyll installs. Just `pip install jupyter-book` and `jupyter book build mybookname/`

It also means that we can add support for many more book outputs, such as PDF via HTML or Latex (if you're into that kinda thing)

jupyterbook.org/advanced/pdf.h…

You can still write your content in Jupyter Notebooks:

jupyterbook.org/content-types/…

Though with MyST Markdown notebooks, you can also write Jupyter Notebooks entirely in markdown!

jupyterbook.org/content-types/…

You can also execute your content and insert inputs/outputs into the book:

jupyterbook.org/content/execut…

and *cache* the execution results so you only re-run execution when you update the code

jupyterbook.org/content/execut…

This allows for some pretty cool experimental functionality like storing the outputs of your code and inserting it across pages:

jupyterbook.org/content/glue.h…

And if you want a "fully functional notebook environment", you can still connect your book's content to a JupyterHub, BinderHub instance, or a number of cloud provider platforms.

jupyterbook.org/interactive/la…

All of this is possible with a collection of modular and open source tools:

- Parse MyST markdown: myst-parser.readthedocs.io/en/latest/
- ipynb tools for Sphinx: myst-nb.readthedocs.io/en/latest/
- a book theme: sphinx-book-theme.readthedocs.io
- execute/cache notebooks: jupyter-cache.readthedocs.io/en/latest/

to name a few

It's also possible because of the excellent ExecutableBooks community and project, which is the new steward of the project:

executablebooks.org/en/latest/

Jupyter Book and this ecosystem still has a *lot* to improve-upon. If you're interested in helping out and joining the community, we welcome you!

- jb contributing: jupyterbook.org/contribute/int…
- ebp contributing: executablebooks.org/en/latest/cont…
- features votes: executablebooks.org/en/latest/feat…

we are excited for you to try it out! please give your feedback, ideas, and any contributions you're willing to make! Jupyter Book is still quite young, so your contribution can help shape the project!

Many thanks to all of the EBP community members that made this possible! And many thanks to @epistemographer and the Sloan foundation for providing core support for this re-write.

We look forward to seeing what you all come up with, and hope to see you around the Jupyter Book repositories ✨

/🧵