What is mean by "opinionated distribution" of mystmd (Jupyter Book 2)?

[scottyhq]

Hi! I'm really excited about the new features of Jupyter Book 2 and appreciate the recent blog posts to clarify the interconnected projects. Today I looked at the pre-release for the first time and the new website for Jupyter Book 2 and have a question

https://next.jupyterbook.org/start states:

Jupyter Book means building a MyST project. In fact, if you’re a power user and prefer a more flexible and less-opinionated workflow, we suggest you use the MyST engine directly

I've been using Jupyter Book 1 for some time, but I'm not sure how to evaluate this opening statement. Am I a power user? Or, to help guide someone looking into these new tools, what does the "opinionated distribution" consist of?

I wasn't sure of specific current or planned differences after having a look at https://executablebooks.org/en/latest/blog/2024-05-20-jupyter-book-myst/#next-steps-for-jupyter-book and https://blog.jupyterbook.org/posts/2024-11-15-jupyter-book-2-alpha#jupyter-book-2-vs-myst-md. And I think it's also important to mention that I'm thinking about starting a new book-themed website from scratch rather than converting an existing JupyterBook 1 website.

[agoose77]

I've been using Jupyter Book 1 for some time, but I'm not sure how to evaluate this opening statement. Am I a power user? Or, to help guide someone looking into these new tools, what does the "opinionated distribution" consist of?

This is a good question!

Right now, mystmd and jupyter-book>=2.0.0a0 barely differ. That is because we put a lot of work into developing mystmd and ensuring that it works well with jupyter-book use cases. Over time, we anticipate that mystmd will be more of a "core" distribution and jupyter-book will be "bells-and-whistles". What that actually looks like is unclear at this stage — we've never done this before! Examples of "bells-and-whistles" might include things like the {card} directive, which is only really useful for websites, not PDFs.

My suggestion is that jupyter-book is the right place to start unless you know that you want to use mystmd. In your case, I'd suggest jupyter-book!