Why use MyST over HTML with Jupyter notebooks

[atharvaaalok]

The executable books project seems really interesting for producing scientific writing that is heavy on computational content.

But what are it's advantages over using plain Jupiter notebook with its markdown and additional capacity using HTML and latex?

Why would one learn another markdown syntax when they can do the same thing with HTML which can be used for other tasks as well?

[agoose77]

Hi @atharvaaalok!

This is a good question that cuts right through to why we are excited about Jupyter Book and the MyST engine. Thanks for asking! There's a lot of nuance to be found in your question, which makes it somewhat hard to answer in one paragraph! I'll do my best to give my take on what you're asking, and how it fits into the wider project.

The important distinctions that we need to start with are MyST Markdown vs Jupyter Book (or the MyST Engine):

MyST Markdown is just a markup language, like CommonMark or reStructuredText (reST), that makes it easy to write elegant prose. Unlike CommonMark, both MyST Markdown and reST include constructs that are designed to make authoring scientific documents easier e.g. admonitions, figures, footnotes, field lists, comments, etc.

Jupyter Book is a tool (that uses the mystmd engine) to do a few interesting things:

• Connect multiple documents together to support cross-referencing
• Consume MyST Markdown, LaTeX, and Jupyter Notebooks, and produce static exports and interactive websites
• Build a structured representation of the above for use with other tools, archival services, etc.

I still haven't answered your question!

It might be helpful to start from a different angle. Why not write scientific articles entirely in HTML? It is the standard for web-communication, so it can produce very rich outputs that are structured. The reason, in my view, is that writing HTML detracts from the readability. Markdown finds that middle ground where you can express structure through markup that is more readable, at the cost of less expressiveness.

When you're writing Markdown, and suddenly have to jump into HTML, it feels like a symptom of a lack of expressiveness. We are aiming with MyST Markdown to make the number of times you need HTML for scientific communication near-zero. If you know Markdown (CommonMark), MyST Markdown is just CommonMark plus some new features. You don't have to use any of the new features until you're ready to do so.

Above all, though, the most important part of this ecosystem is probably not the exact dialect of Markdown (MyST Markdown) that we are building. Rather, it's the tooling around that markup variant that is exciting. The mystmd engine that powers Jupyter Book provides all kinds of interesting features that are not inherently tied to the Markdown flavour.

I think there's so much more to say here,but my short answer for "why Jupyter Book / mystmd?" is "try it and find out!"