📖 Update documentation for Jupyter Book V2 vs V1 references (#1732)

docs/accessibility-and-performance.md

@@ -44,9 +44,9 @@ Some performance and accessibility considerations:
 
 ````{seealso}
 :class: dropdown
-# Comparing to Jupyter Book & Quarto
+# Comparing to Jupyter Book V1 & Quarto
 
-As a comparison to Jupyter Book or Quarto, which are both static site generators for scientific content, and assets built by Sphinx and Pandoc, respectively. There are improvements possible primarily in the bundling of Javascript assets, which is very difficult to do in the Sphinx build process, for example.
+As a comparison to Jupyter Book V1 or Quarto, which are both static site generators for scientific content, and assets built by Sphinx and Pandoc, respectively. There are improvements possible primarily in the bundling of Javascript assets, which is very difficult to do in the Sphinx build process, for example.
 
 ```{figure} ./images/lighthouse-jb-2022_09_15.png
 :label: lighthouse-jb

docs/admonitions.md

@@ -134,7 +134,7 @@ GitHub markdown transforms blockquotes that start with a bold `Note` or text wit
 ::::{tip} Compatibility with Pandoc & Quarto
 :class: dropdown
 In Quarto/Pandoc markdown admonitions are styled with special classes like `{.callout-note}` or `{.callout-tip}`).
-If you are using Jupyter Book or Sphinx documentation, use an {myst:directive}`admonition` directive with the specific class, for example:
+If you are using Jupyter Book V1 or Sphinx documentation, use an {myst:directive}`admonition` directive with the specific class, for example:
 
 ```{myst}
 ::: {.callout-tip}
@@ -149,7 +149,7 @@ This is an example of a callout with a caption.
 :class: dropdown
 In Sphinx, all named admonitions (e.g. `{note}` or `{tip}`), have **no arguments**.
 If you place content on the first line it will instead be prepended to the admonition body.
-If you are using Jupyter Book or Sphinx documentation, use an {myst:directive}`admonition` directive with the specific class, for example:
+If you are using Jupyter Book V1 or Sphinx documentation, use an {myst:directive}`admonition` directive with the specific class, for example:
 
 ```{myst}
 :::{admonition} The Title

docs/background.md

@@ -9,40 +9,35 @@ This page discusses high-level questions about the MyST Markdown ecosystem, hist
 
 MyST Markdown (Markedly Structured Text) is a markup language that builds on standard markdown and is designed to create publication-quality documents, books, presentations, and websites written entirely in Markdown. The [ExecutableBooks] team received a grant from the [Sloan Foundation](https://sloan.org) to build, enhance, and promote a new path to document creation and publishing for next-generation scientific textbooks and lectures ([Grant #9231](https://sloan.org/grant-detail/9231)).
 
-The initial use case driving the development and design of MyST Markdown has been [Jupyter Book], which allows you to create educational online textbooks and tutorials with Jupyter Notebooks and narrative content written in MyST. The extensions and design of MyST is inspired by the [Sphinx] and [reStructuredText](https://docutils.sourceforge.io/rst.html) (RST) ecosystems. Jupyter Book is considered a [distribution of Sphinx](xref:jupyterbook#explain/sphinx), and builds on the Sphinx and [Docutils] Python packages.
+The initial use case driving the development and design of MyST Markdown has been [Jupyter Book], which allows you to create educational online textbooks and tutorials with Jupyter Notebooks and narrative content written in MyST. The extensions and design of MyST is inspired by the [Sphinx] and [reStructuredText](https://docutils.sourceforge.io/rst.html) (RST) ecosystems. Jupyter Book V1 is considered a [distribution of Sphinx](xref:jupyterbook#explain/sphinx), and builds on the Sphinx and [Docutils] Python packages.
 
 MyST Markdown enables rich content generation and is a powerful textual format for scientific and technical communication with potential for broad adoption in modern publishing workflows. In 2022, the Executable Books team started work to document the specification behind the markup language, called [myst-spec](https://github.com/jupyter-book/myst-spec), this work has enabled other tools and implementations in the scientific ecosystem to build on MyST Markdown (e.g. [scientific authoring tools](https://curvenote.com/for/writing), and [documentation systems](https://blog.readthedocs.com/jupyter-book-read-the-docs/)).
 
-The `mystmd`[^naming] command line tools were developed as a collaboration between [Curvenote], [2i2c] and the [ExecutableBooks] team. The initial version was release by [Curvenote] as the [Curvenote CLI](https://curvenote.com/docs/cli) under the MIT license, and later transferred to the [ExecutableBooks] team. The goal of the project is to enable the same rich content and authoring experiences that Sphinx allows for software documentation, with a focus on web-first technologies (Javascript), interactivity, accessibility, scientific references (e.g. DOIs and other PIDs), and professional PDF outputs.
+## What is the MyST Document Engine and Myst Markdown?
 
-In June, 2024 the `mystmd` project became an official Jupyter project [See #123](https://github.com/jupyter/enhancement-proposals/pull/123).
+The `mystmd`[^naming] document engine and its ecosystem of tools were developed as a collaboration between [Curvenote], [2i2c] and the [ExecutableBooks] team. In addition to building websites, `mystmd` can also help you create scientific PDFs, Microsoft Word documents, and presentations.
 
-[^naming]: Originally `mystmd` was called `mystjs`, but was changed as we matured the command-line interfaces.
+`mystmd` uses existing, modern web-frameworks in place of the [Sphinx] build system. These tools come out-of-the-box with prefetching for faster navigation, smaller network payloads through modern web-bundlers, image optimization, partial-page refresh through single-page application. Many of these features and performance improvements are difficult (if not impossible) to create inside of the [Sphinx] build system.
 
-## How do Jupyter Book and `mystmd` relate?
+The javascript packages in the `mystmd` ecosystem also power web-native extensions, such as [JupyterLab-myst], which renders MyST markup directly in JupyterLab.
 
-The current toolchain used by [Jupyter Book] is based on [Sphinx], which is an open-source documentation system used in many software projects, especially in the Python ecosystem. `mystmd` is a similar tool to [Sphinx], however, designed for scientific and technical content. In addition to building websites, `mystmd` can also help you create scientific PDFs, Microsoft Word documents, and presentations.
+## How was the MyST Engine Developed?
 
-`mystmd` uses existing, modern web-frameworks in place of the [Sphinx] build system. These tools come out-of-the-box with prefetching for faster navigation, smaller network payloads through modern web-bundlers, image optimization, partial-page refresh through single-page application. Many of these features and performance improvements are difficult (if not impossible) to create inside of the [Sphinx] build system.
+The initial version was released by [Curvenote] as the [Curvenote CLI](https://curvenote.com/docs/cli) under the MIT license, and later transferred to the [ExecutableBooks] team. The goal of the project is to enable the same rich content and authoring experiences that Sphinx allows for software documentation, with a focus on web-first technologies (Javascript), interactivity, accessibility, scientific references (e.g. DOIs and other PIDs), and professional PDF outputs.
 
-The javascript packages in the `mystmd` ecosystem also help power web-native extensions, such as [JupyterLab-myst], which renders MyST markup directly in JupyterLab.
+In June, 2024 Jupyter Book was incorporated as a Jupyter sub-project, standardizing on using and stewarding the MyST document engine (`mystmd`). [See #123](https://github.com/jupyter/enhancement-proposals/pull/123).
 
-`mystmd` can render [Jupyter Book] content, however, it cannot work with custom extensions or themes developed for Sphinx. As `mystmd` continues to improve, we will ensure smooth paths for content authors to choose between these different rendering engines.
-
-## Can I use Jupyter Book and `mystmd` together?
+[^naming]: Originally `mystmd` was called `mystjs`, but was changed as we matured the command-line interfaces.
 
-Yes! There **is** overlap in functionality for creating websites, however, you can also use `mystmd` with your Jupyter Book content to:
+## How do Jupyter Book and `mystmd` relate?
 
-- Create a [professional PDF](./creating-pdf-documents.md)
-- Export to [Microsoft Word](./creating-word-documents.md)
-- Create a presentation
-- Write in JupyterLab, using [JupyterLab-myst]
+Jupyter Book V2 is a distribution of the MySTMD document engine.[^jbv1] Jupyter Book V2 is pre-configures functionality in MyST with a focus on multi-page documents and documentation.
 
-If you want, you can also try a `mystmd` website to view your Jupyter Book (try the [online tool provided by Curvenote](https://try.curvenote.com), to test with your Jupyter Book), or run `myst` in your Jupyter Book directory. `mystmd` provides improved interactivity around [cross-linking content](./cross-references.md), [performance and accessibility](./accessibility-and-performance.md) improvements.
+See [next.jupyterbook.org](https://next.jupyterbook.org) for more information.
 
-Jupyter Book and `mystmd` both use MyST Markdown for content and read Jupyter Notebooks, and we have made reasonable efforts to ensure that your content can be read by both renderers. However, no custom Sphinx extensions that you may have added to your Jupyter Books will work. If you find something that doesn't work with `mystmd` from your Jupyter Book content, please [let us know on GitHub](https://github.com/jupyter-book/mystmd/issues) and we will try to support it!
+Under the hood, Jupyter Book is "just MyST", meaning that you can re-create anything in MyST directly if you wish. We envision the MyST engine to be a more usecase-agnostic engine for serving many workflows in scientific communication and publishing, and Jupyter Book to focus on community documentation and multi-page books. MyST will likely be more modular and lightweight, with an extensive plugin ecosystem, while Jupyter Book will be an opinionated configuration of that ecosystem.
 
-Jupyter Books are an excellent medium for tutorials, textbooks & software documentation but are currently less well suited to content such as blogs, lab-websites, and journal articles. Additionally, Jupyter Book cannot create scientific PDFs that are submission ready.
+[^jbv1]: Jupyter Book V1 is a distribution of [Sphinx], which is an open-source documentation system used in many software projects, especially in the Python ecosystem. `mystmd` can render [Jupyter Book] content, however, it cannot work with custom extensions or themes developed for Sphinx. If you find something that doesn't work with `mystmd` from your Jupyter Book V1 content, please [let us know on GitHub](https://github.com/jupyter-book/mystmd/issues) and we will try to support it!
 
 ## How do `mystmd` and Sphinx relate?
 

docs/citations.md

@@ -99,7 +99,7 @@ This syntax follows the [pandoc citation syntax](https://pandoc.org/MANUAL.html#
 
 ## Citation Roles
 
-MyST also provides a number of roles for compatibility with Sphinx and Jupyter Book. To create a citation role in Markdown, use either a parenthetical or textual citation:
+MyST also provides a number of roles for compatibility with Sphinx and Jupyter Book V1. To create a citation role in Markdown, use either a parenthetical or textual citation:
 
 ```md
 This is a parenthetical citation {cite:p}`cockett2015`.

docs/contribute-add-feature.md

@@ -52,7 +52,7 @@ MyST is cool!
 
 ## Defining a Role
 
-The core specification for the MyST markup language is defined in [the MyST spec](https://mystmd.org/spec). Most features in MyST should, over time, be incorporated into this specification so that consumers of MyST documents (such as `myst-parser` from the Jupyter Book software stack) agree on the manner in which the content should be parsed and rendered. The process of adding features to the MyST Spec is more formalized, and is described in the [MyST Enhancement Proposals](https://mep.mystmd.org). This tutorial does not cover updating the MyST Spec.
+The core specification for the MyST markup language is defined in [the MyST spec](https://mystmd.org/spec). Most features in MyST should, over time, be incorporated into this specification so that consumers of MyST documents (such as `myst-parser` from the Jupyter Book V1 software stack) agree on the manner in which the content should be parsed and rendered. The process of adding features to the MyST Spec is more formalized, and is described in the [MyST Enhancement Proposals](https://mep.mystmd.org). This tutorial does not cover updating the MyST Spec.
 
 We should begin by asking the question "What is a role?" The spec [defines roles](https://mystmd.org/spec/overview#roles) as:
 

docs/contribute-docs.md

@@ -80,3 +80,19 @@ Configuration for our Netlify build exists in the [`netlify.toml` configuration
 
 Any team members can have `Developer` access to our shared Netlify account, and Steering Council members can have `Owner` access.
 If you'd like access, please ask a maintainer.
+
+## Documenting in jupyterbook.org vs. mystmd.org
+
+:::{warning} We're still figuring this out!
+This is a best-effort description of our approach to documentation, based on some conversations we had in https://github.com/jupyter-book/jupyter-book/issues/2239. We'll re-assess this as the documentation of each project evolves.
+:::
+
+Jupyter Book and the MyST Document Engine have heavily overlapping functionality, so it may be unclear whether something should be documented at mystmd.org or jupyterbook.org. That's OK and expected - here are some guidelines for where to document things:
+
+- The MyST document engine will be a **power user tool**. It will be more flexible and modular, with an extensive plugin ecosysytem. It will be agnostic to build output, and single- or multi-page documents.
+   - MyST should have the complete reference documentation for the MyST engine, as well as longer explanatory content about the MyST ecosystem.
+   - As functionaliy is moved into plugins, we similarly prioritize reference documentation and explanation in those spaces.
+   - MyST should be a standalone tool and have enough information for a power user to use on its own.
+- Jupyter Book will be a **tool for typical users** focused around multi-page documents and websites. It will be opinionated, focused around the "book themes", and be more accessible to a new user or someone unfamiliar with JavaScript workflows.
+   - Jupyter Book should focus on **How-Tos** and **Tutorials** that are driven by use-cases in multi-page workflows (e.g., documentation, books, community websites, etc).
+   - Focus on keeping documentation outcome-oriented, and link heavily to the MyST engine docs for more complete reference information and explanation.

docs/creating-pdf-documents.md

@@ -247,7 +247,7 @@ exports:
 ---
 ```
 
-As an alternative to listing articles in MyST frontmatter, you may specify a table of contents using the [Jupyter Book format](#toc-format):
+As an alternative to listing articles in MyST frontmatter, you may specify a table of contents using the [Jupyter Book V1 format](#toc-format):
 
 ```{code-block} yaml
 :filename: article.md

docs/execute-notebooks.md

@@ -51,7 +51,7 @@ print("Hello" + 10001)
 
 ## Skip particular code-cells
 
-Sometimes, you might have a notebook containing code that you _don't_ want to execute. For example, you might have code-cells that prompt the user for input, which should be skipped during a website build. MyST understands the same `skip-execution` cell-tag that other Jupyter Notebook tools (such as Jupyter Book) use to prevent a cell from being executed.
+Sometimes, you might have a notebook containing code that you _don't_ want to execute. For example, you might have code-cells that prompt the user for input, which should be skipped during a website build. MyST understands the same `skip-execution` cell-tag that other Jupyter Notebook tools (such as Jupyter Book V1) use to prevent a cell from being executed.
 
 For [Markdown notebooks using the {myst:directive}`code-cell` directive](notebooks-with-markdown.md#code-cell), the `skip-execution` tag can be added as follows:
 

docs/external-references.md

@@ -102,7 +102,9 @@ It is also a machine-readable record that can be used for analyzing the cross-re
 MyST can integrate directly with other Sphinx documentation, which is used in many Python projects including the [standard library](https://docs.python.org/).
 This re-uses the reference specification defined by [the intersphinx plugin for Sphinx](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html).
 
-Similar to [MyST cross references](#myst-xref), use the `references` object to list Sphinx projects. For example, in the demonstration below we will load the Python 3.7 documentation and Jupyter Book docs, both of which use sphinx and expose cross references through an `objects.inv` file.
+% TODO: Update this when we release Jupyter Book V2 because /stable will no longer be a Sphinx site.
+
+Similar to [MyST cross references](#myst-xref), use the `references` object to list Sphinx projects. For example, in the demonstration below we will load the Python 3.7 documentation and Jupyter Book V1 docs, both of which use sphinx and expose cross references through an `objects.inv` file.
 
 (intersphinx-config)=
 

docs/index.md

@@ -49,7 +49,7 @@ We think {abbr}`MyST (Markedly Structured Text)` is really cool, some of the fea
 :::{seealso}
 :class: dropdown
 
-# Coming from Jupyter Book or Sphinx?
+# Coming from Jupyter Book V1 or Sphinx?
 
 👋 We are glad you are here! 💚
 

docs/table-of-contents.md

@@ -211,39 +211,12 @@ URL nesting that matches the folder structure is a requested feature that is bei
 
 (toc-format-legacy)=
 
-## Defining a `_toc.yml` using Jupyter Book’s format
+## Defining a `_toc.yml` using Jupyter Book v1 format
 
 :::{warning}
 Support for `_toc.yml` exists only for compatibility reasons, and will be removed in future.
 New users should use `myst.yml` instead.
 :::
 
-Site table of contents may be defined with a `_toc.yml` file, following the Jupyter Book format. The documentation for this format is fully described in [Jupyter Book](https://jupyterbook.org/en/stable/structure/toc.html). Briefly, it defines a `format` as `jb-book` and can list a number of `chapters` with files. The file paths are relative to your `_toc.yml` file and can optionally include the extension.
-
-```yaml
-format: jb-book
-root: index
-chapters:
-  - file: path/to/chapter1
-  - file: path/to/chapter2
-```
-
-For larger books, you can group the content into `parts`. Each `part` has a `caption` and a list of `chapters` files can define children using a list of `sections`.
-
-```yaml
-format: jb-book
-root: index
-parts:
-  - caption: Name of Part 1
-    chapters:
-      - file: path/to/part1/chapter1
-      - file: path/to/part1/chapter2
-        sections:
-          - file: path/to/part1/chapter2/section1
-  - caption: Name of Part 2
-    chapters:
-      - file: path/to/part2/chapter1
-      - file: path/to/part2/chapter2
-```
-
+Jupyter Book v2 uses the MyST engine, but Jupyter Book v1 uses a different configuration structure that is designed for Sphinx. However, you can currently use a Juypter Book v1 Table of Contents file (`_toc.yml`) with MyST.The documentation for this format is fully described in [Jupyter Book](https://jupyterbook.org/en/stable/structure/toc.html).
 ::::