🧘‍♀️ Relax some new toc opinions

docs/table-of-contents.md

@@ -34,7 +34,11 @@ project:
 
 ### URL entries
 
-URLs can be defined in the TOC. These links will show up in web exports, and will be ignored for non-web exports.
+URLs can be defined in the TOC. These URLs are links to external references within your table of contents. URLs are ignored in non-web exports.
+
+:::{warn}
+Currently these URLs are also ignored in MyST sites. Support will be added in a future release.
+:::
 
 :::{code} yaml
 :filename: myst.yml
@@ -77,7 +81,6 @@ project:
     - file: root.md
     - file: first-child.md
     - file: second-child.md
-    - url: https://google.com
 :::
 ::::
 :::::
@@ -123,23 +126,6 @@ project:
         - file: part-2-second-child.md
 :::
 
-## Define document parts for exports
-
-A MyST document [can be split into several "parts"](document-parts.md#known-frontmatter-parts) that correspond to distinct components (e.g. "abstract" or "acknowledgements"). Each TOC entry can be given a `part` key that corresponds to one of these recognized parts, e.g.
-
-:::{code} yaml
-:filename: myst.yml
-
-version: 1
-project:
-  toc:
-    - file: root.md
-    - file: abstract.md
-      part: abstract
-    - file: acknowledgements.md
-      part: acknowledgements
-:::
-
 
 ## Implicit Table of Contents from filenames
 
@@ -208,3 +194,37 @@ See [](xref.md) for more details on how cross-references are stored.
 :::{note} URL Nesting
 URL nesting that matches the folder structure is a requested feature that is being tracked in [#670](https://github.com/executablebooks/mystmd/issues/670).
 :::
+
+:::{note} Compatibility with JupyterBook
+:class: dropdown
+
+## Defining a `_toc.yml` using Jupyter Book’s format
+
+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
+```
+:::

packages/myst-cli/src/build/site/watch.ts

@@ -142,14 +142,18 @@ function watchProcessor(
     }
     session.store.dispatch(watch.actions.markReloading(true));
     session.log.debug(`File modified: "${file}" (${eventType})`);
-    await processorFn(session, file, eventType, siteProject, serverReload, opts);
-    while (selectors.selectReloadingState(session.store.getState()).reloadRequested) {
-      // If reload(s) were requested during previous build, just reload everything once.
-      session.store.dispatch(watch.actions.markReloadRequested(false));
-      await processorFn(session, null, eventType, null, serverReload, {
-        ...opts,
-        reloadProject: true,
-      });
+    try {
+      await processorFn(session, file, eventType, siteProject, serverReload, opts);
+      while (selectors.selectReloadingState(session.store.getState()).reloadRequested) {
+        // If reload(s) were requested during previous build, just reload everything once.
+        session.store.dispatch(watch.actions.markReloadRequested(false));
+        await processorFn(session, null, eventType, null, serverReload, {
+          ...opts,
+          reloadProject: true,
+        });
+      }
+    } catch (err: any) {
+      session.log.error(`Error during reload${err.message ? `:\n${err.message}` : ''}`);
     }
     session.store.dispatch(watch.actions.markReloading(false));
   };

packages/myst-cli/src/project/load.ts

@@ -55,27 +55,41 @@ export async function loadProjectFromDisk(
   let newProject: Omit<LocalProject, 'bibliography'> | undefined;
   let { index, writeTOC } = opts || {};
   let legacyToc = false;
+  const sphinxTOCFile = validateSphinxTOC(session, path) ? tocFile(path) : undefined;
   if (projectConfig?.toc !== undefined) {
     newProject = projectFromTOC(session, path, projectConfig.toc);
-    if (writeTOC) session.log.warn('Not writing the table of contents, it already exists!');
-    writeTOC = false;
-  } else if (validateSphinxTOC(session, path)) {
-    // Legacy validator
-    legacyToc = true;
-    if (!writeTOC) {
-      // Do not warn if user is explicitly upgrading toc
-      const filename = tocFile(path);
+    if (sphinxTOCFile) {
       addWarningForFile(
         session,
-        filename,
-        `Encountered legacy jupyterbook TOC: ${filename}`,
+        sphinxTOCFile,
+        `Ignoring legacy jupyterbook TOC in favor of myst.yml toc: ${sphinxTOCFile}`,
         'warn',
         {
           ruleId: RuleId.encounteredLegacyTOC,
-          note: 'To upgrade to a MyST TOC, try running `myst init --write-toc`',
         },
       );
     }
+    if (writeTOC) session.log.warn('Not writing the table of contents, it already exists!');
+    writeTOC = false;
+  } else if (sphinxTOCFile) {
+    // Legacy validator
+    legacyToc = true;
+    if (!writeTOC) {
+      // Do not warn if user is explicitly upgrading toc
+      // TODO: Add this back as a warning rather than debug as we surface this feature more
+      session.log.debug(`Encountered legacy jupyterbook TOC: ${sphinxTOCFile}`);
+      session.log.debug('To upgrade to a MyST TOC, try running `myst init --write-toc`');
+      // addWarningForFile(
+      //   session,
+      //   filename,
+      //   `Encountered legacy jupyterbook TOC: ${sphinxTOCFile}`,
+      //   'warn',
+      //   {
+      //     ruleId: RuleId.encounteredLegacyTOC,
+      //     note: 'To upgrade to a MyST TOC, try running `myst init --write-toc`',
+      //   },
+      // );
+    }
     newProject = projectFromSphinxTOC(session, path);
   } else {
     const project = selectors.selectLocalProject(state, path);