mystmd 1.1.56__py3-none-any.whl → 1.2.1__py3-none-any.whl

mystmd_py/myst.cjs

@@ -193279,7 +193279,7 @@ var {
 } = import_index.default;
 
 // src/version.ts
-var version = "1.1.56";
+var version = "1.2.1";
 var version_default = version;
 
 // ../myst-cli/dist/build/build.js
@@ -194274,6 +194274,7 @@ var AFFILIATION_KEYS = [
 ];
 var AFFILIATION_ALIASES = {
   ref: "id",
+  // Used in QMD to reference an affiliation
   region: "state",
   province: "state",
   zipcode: "postal_code",
@@ -194619,6 +194620,7 @@ var PERSON_KEYS = [
 ];
 var PERSON_ALIASES = {
   ref: "id",
+  // Used in QMD to reference a contributor
   role: "roles",
   "equal-contributor": "equal_contributor",
   affiliation: "affiliations",
@@ -194881,7 +194883,6 @@ var FRONTMATTER_ALIASES = {
 // ../myst-frontmatter/dist/project/types.js
 var PROJECT_AND_PAGE_FRONTMATTER_KEYS = [
   "date",
-  "name",
   "doi",
   "arxiv",
   "open_access",
@@ -194898,6 +194899,7 @@ var PROJECT_AND_PAGE_FRONTMATTER_KEYS = [
   "exports",
   "downloads",
   "settings",
+  // We maybe want to move this into site frontmatter in the future
   // Do not add any project specific keys here!
   ...SITE_FRONTMATTER_KEYS
 ];
@@ -194924,6 +194926,7 @@ var PAGE_KNOWN_PARTS = [
 var PAGE_FRONTMATTER_KEYS = [
   ...PROJECT_AND_PAGE_FRONTMATTER_KEYS,
   // These keys only exist on the page
+  "label",
   "kernelspec",
   "jupytext",
   "tags",
@@ -197749,6 +197752,54 @@ function fillNumbering(base5, filler) {
   return output2;
 }
 
+// ../myst-frontmatter/dist/references/types.js
+var KNOWN_REFERENCE_KINDS = ["myst", "intersphinx"];
+
+// ../myst-frontmatter/dist/references/validators.js
+function validateExternalReference(input3, opts) {
+  var _a6;
+  if (typeof input3 === "string") {
+    input3 = { url: input3 };
+  }
+  const value = validateObjectKeys(input3, { required: ["url"], optional: ["kind"] }, opts);
+  if (!value)
+    return void 0;
+  let url = validateUrl(value.url, incrementOptions("url", opts));
+  if (!url)
+    return void 0;
+  if (url.endsWith("/")) {
+    url = url.slice(0, url.length - 1);
+  }
+  const output2 = { url };
+  if (defined(value.kind)) {
+    const kindOpts = incrementOptions(value.kind, opts);
+    let kind = (_a6 = validateString(value.kind, kindOpts)) === null || _a6 === void 0 ? void 0 : _a6.toLowerCase();
+    if (kind === "sphinx" || kind === "inv")
+      kind = "intersphinx";
+    if (kind && !KNOWN_REFERENCE_KINDS.includes(kind)) {
+      validationWarning(`Unknown external reference kind "${kind}"`, kindOpts);
+    }
+    if (kind)
+      output2.kind = kind;
+  }
+  return output2;
+}
+function validateExternalReferences(input3, opts) {
+  const value = validateObject(input3, opts);
+  if (!value)
+    return void 0;
+  const output2 = Object.fromEntries(Object.entries(value).map(([key2, ref]) => {
+    const outputKey = validateString(key2, { ...opts, regex: "^[a-zA-Z0-9_-]*$" });
+    if (!outputKey)
+      return void 0;
+    const outputRef = validateExternalReference(ref, incrementOptions(key2, opts));
+    if (!outputRef)
+      return void 0;
+    return [outputKey, outputRef];
+  }).filter((exists2) => !!exists2));
+  return Object.keys(output2).length ? output2 : void 0;
+}
+
 // ../myst-frontmatter/dist/venues/validators.js
 function validateVenue(input3, opts) {
   let titleOpts;
@@ -198091,9 +198142,6 @@ function validateProjectAndPageFrontmatterKeys(value, opts) {
   if (defined(value.date)) {
     output2.date = validateDate(value.date, incrementOptions("date", opts));
   }
-  if (defined(value.name)) {
-    output2.name = validateString(value.name, incrementOptions("name", opts));
-  }
   if (defined(value.doi)) {
     output2.doi = validateDoi(value.doi, incrementOptions("doi", opts));
   }
@@ -198194,16 +198242,7 @@ function validateProjectFrontmatterKeys(value, opts) {
     output2.id = validateString(value.id, incrementOptions("id", opts));
   }
   if (defined(value.references)) {
-    const referencesOpts = incrementOptions("references", opts);
-    const references = validateObject(value.references, referencesOpts);
-    if (references) {
-      output2.references = Object.fromEntries(Object.keys(references).map((key2) => {
-        const url = validateUrl(references[key2], incrementOptions(key2, referencesOpts));
-        if (!url)
-          return void 0;
-        return [key2, { url }];
-      }).filter((exists2) => !!exists2));
-    }
+    output2.references = validateExternalReferences(value.references, incrementOptions("references", opts));
   }
   if (defined(value.thebe)) {
     const result = validateThebe(value.thebe, output2.github, incrementOptions("thebe", opts));
@@ -198226,7 +198265,7 @@ function validateProjectFrontmatterKeys(value, opts) {
   return output2;
 }
 function validateProjectFrontmatter(input3, opts) {
-  const value = validateObjectKeys(input3, { optional: PROJECT_FRONTMATTER_KEYS, alias: FRONTMATTER_ALIASES }, opts) || {};
+  const value = validateObjectKeys(input3, { optional: PROJECT_FRONTMATTER_KEYS, alias: { ...FRONTMATTER_ALIASES, name: "label" } }, opts) || {};
   return validateProjectFrontmatterKeys(value, opts);
 }
 
@@ -198254,6 +198293,9 @@ var USE_PROJECT_FALLBACK = [
 ];
 function validatePageFrontmatterKeys(value, opts) {
   const output2 = validateProjectAndPageFrontmatterKeys(value, opts);
+  if (defined(value.label)) {
+    output2.label = validateString(value.label, incrementOptions("label", opts));
+  }
   if (defined(value.kernelspec)) {
     output2.kernelspec = validateKernelSpec(value.kernelspec, incrementOptions("kernelspec", opts));
   }
@@ -198302,7 +198344,7 @@ function validatePageFrontmatterKeys(value, opts) {
   return output2;
 }
 function validatePageFrontmatter(input3, opts) {
-  const value = validateObjectKeys(input3, { optional: PAGE_FRONTMATTER_KEYS, alias: FRONTMATTER_ALIASES }, opts) || {};
+  const value = validateObjectKeys(input3, { optional: PAGE_FRONTMATTER_KEYS, alias: { ...FRONTMATTER_ALIASES, name: "label" } }, opts) || {};
   return validatePageFrontmatterKeys(value, opts);
 }
 
@@ -202829,8 +202871,8 @@ var RuleId;
   RuleId2["roleKnown"] = "role-known";
   RuleId2["roleBodyCorrect"] = "role-body-correct";
   RuleId2["tocContentsExist"] = "toc-contents-exist";
-  RuleId2["validTocStructure"] = "valid-toc-structure";
-  RuleId2["validToc"] = "valid-toc";
+  RuleId2["validTOCStructure"] = "valid-toc-structure";
+  RuleId2["validTOC"] = "valid-toc";
   RuleId2["tocWritten"] = "toc-written";
   RuleId2["imageDownloads"] = "image-downloads";
   RuleId2["imageExists"] = "image-exists";
@@ -202850,10 +202892,12 @@ var RuleId;
   RuleId2["footnoteReferencesDefinition"] = "footnote-references-definition";
   RuleId2["intersphinxReferencesResolve"] = "intersphinx-references-resolve";
   RuleId2["mystLinkValid"] = "myst-link-valid";
+  RuleId2["sphinxLinkValid"] = "sphinx-link-valid";
   RuleId2["rridLinkValid"] = "rrid-link-valid";
   RuleId2["wikipediaLinkValid"] = "wikipedia-link-valid";
   RuleId2["doiLinkValid"] = "doi-link-valid";
   RuleId2["linkResolves"] = "link-resolves";
+  RuleId2["linkTextExists"] = "link-text-exists";
   RuleId2["notebookAttachmentsResolve"] = "notebook-attachments-resolve";
   RuleId2["notebookOutputCopied"] = "notebook-output-copied";
   RuleId2["mdastSnippetImports"] = "mdast-snippet-imports";
@@ -205878,6 +205922,7 @@ var admonitionTitle = (h4, node3) => h4(node3, "p", { class: "admonition-title"
 var admonition = (h4, node3) => h4(node3, "aside", {
   class: (0, import_classnames.default)({
     [node3.class]: node3.class,
+    // The custom class is first!!
     admonition: true,
     [node3.kind]: node3.kind && node3.kind !== "admonition"
   })
@@ -220573,6 +220618,13 @@ var defaultHtmlToMdastOptions = {
     cite(h4, node3) {
       const attrs = addClassAndIdentifier(node3);
       return attrs.label ? h4(node3, "cite", attrs, all5(h4, node3)) : all5(h4, node3);
+    },
+    details(h4, node3) {
+      const attrs = addClassAndIdentifier(node3);
+      return h4(node3, "details", attrs, all5(h4, node3));
+    },
+    summary(h4, node3) {
+      return h4(node3, "summary", all5(h4, node3));
     }
   }
 };
@@ -235842,6 +235894,107 @@ function linksTransform(mdast2, file, opts) {
   });
 }
 
+// ../myst-transforms/dist/links/myst.js
+var TRANSFORM_SOURCE3 = "LinkTransform:MystTransformer";
+function removeMystPrefix(uri, vfile2, link4, source2) {
+  if (uri.startsWith("myst:")) {
+    const normalized = uri.replace(/^myst/, "xref");
+    if (vfile2) {
+      fileWarn(vfile2, `"myst:" prefix is deprecated for external reference "${uri}"`, {
+        note: `Use "${normalized}" instead.`,
+        node: link4,
+        source: source2,
+        ruleId: RuleId.mystLinkValid
+      });
+    }
+    return normalized;
+  }
+  return uri;
+}
+var MystTransformer = class {
+  constructor(references) {
+    this.protocol = "xref:myst";
+    this.mystXRefsList = references.filter((ref) => {
+      return ref.kind === "myst";
+    }).filter((ref) => {
+      return !!ref.value;
+    });
+  }
+  test(uri) {
+    if (!uri)
+      return false;
+    const normalizedUri = removeMystPrefix(uri);
+    return !!this.mystXRefsList.find((m2) => m2.key && normalizedUri.startsWith(`xref:${m2.key}`));
+  }
+  transform(link4, file) {
+    var _a6;
+    const urlSource = removeMystPrefix(link4.urlSource || link4.url, file, link4, TRANSFORM_SOURCE3);
+    let url;
+    try {
+      url = new URL(urlSource);
+    } catch (err) {
+      fileError(file, `Could not parse url for "${urlSource}"`, {
+        node: link4,
+        source: TRANSFORM_SOURCE3,
+        ruleId: RuleId.mystLinkValid
+      });
+      return false;
+    }
+    const key2 = url.pathname.split("/")[0];
+    const page = url.pathname.slice(key2.length);
+    const identifier = (_a6 = url.hash) === null || _a6 === void 0 ? void 0 : _a6.replace(/^#/, "");
+    const mystXRefs = this.mystXRefsList.find((m2) => m2.key === key2);
+    if (!mystXRefs || !mystXRefs.value) {
+      fileError(file, `Unknown project "${key2}" for link: ${urlSource}`, {
+        node: link4,
+        source: TRANSFORM_SOURCE3,
+        ruleId: RuleId.mystLinkValid
+      });
+      return false;
+    }
+    let match3;
+    if (identifier) {
+      match3 = mystXRefs.value.references.find((ref) => {
+        if (page && ref.url !== page)
+          return false;
+        if (!page && ref.implicit)
+          return false;
+        return ref.identifier === identifier || ref.html_id === identifier;
+      });
+    } else {
+      match3 = mystXRefs.value.references.find((ref) => {
+        if (ref.kind !== "page")
+          return false;
+        if (!page && ref.url === "/")
+          return true;
+        return ref.url === page;
+      });
+    }
+    if (!match3) {
+      fileError(file, `"${urlSource}" not found in MyST project ${mystXRefs.key} (${mystXRefs.url})`, {
+        node: link4,
+        source: TRANSFORM_SOURCE3,
+        ruleId: RuleId.mystLinkValid
+      });
+      return false;
+    }
+    link4.internal = false;
+    link4.url = `${mystXRefs.url}${match3.url}`;
+    link4.dataUrl = `${mystXRefs.url}${match3.data}`;
+    if (match3.kind === "page") {
+      link4.protocol = "file";
+    } else {
+      const xref = link4;
+      xref.type = "crossReference";
+      xref.remote = true;
+      xref.identifier = match3.identifier;
+      xref.label = match3.identifier;
+      xref.html_id = match3.html_id;
+    }
+    return true;
+  }
+};
+
 // ../myst-transforms/dist/links/utils.js
 function withoutHttp(url) {
   return url === null || url === void 0 ? void 0 : url.replace(/https?:\/\//, "");
@@ -235861,58 +236014,61 @@ function updateLinkTextIfEmpty(link4, title) {
   }
 }
 
-// ../myst-transforms/dist/links/myst.js
-var TRANSFORM_SOURCE3 = "LinkTransform:MystTransformer";
-var MystTransformer = class {
-  constructor(intersphinx) {
-    this.protocol = "myst";
-    this.intersphinx = intersphinx;
+// ../myst-transforms/dist/links/sphinx.js
+var TRANSFORM_SOURCE4 = "LinkTransform:SphinxTransformer";
+var SphinxTransformer = class {
+  constructor(references) {
+    this.protocol = "xref:sphinx";
+    this.intersphinx = references.filter((ref) => {
+      return ref.kind === "intersphinx";
+    }).filter((ref) => {
+      var _a6;
+      return !!((_a6 = ref.value) === null || _a6 === void 0 ? void 0 : _a6._loaded);
+    }).map((ref) => ref.value);
   }
   test(uri) {
-    return !!(uri === null || uri === void 0 ? void 0 : uri.startsWith("myst:"));
+    if (!uri)
+      return false;
+    const normalizedUri = removeMystPrefix(uri);
+    return !!this.intersphinx.find((i2) => i2.id && normalizedUri.startsWith(`xref:${i2.id}`));
   }
   transform(link4, file) {
     var _a6, _b;
-    const urlSource = link4.urlSource || link4.url;
+    const urlSource = removeMystPrefix(link4.urlSource || link4.url, file, link4, TRANSFORM_SOURCE4);
     let url;
     try {
       url = new URL(urlSource);
     } catch (err) {
       fileError(file, `Could not parse url for "${urlSource}"`, {
         node: link4,
-        source: TRANSFORM_SOURCE3,
-        ruleId: RuleId.mystLinkValid
+        source: TRANSFORM_SOURCE4,
+        ruleId: RuleId.sphinxLinkValid
       });
       return false;
     }
+    const id = url.pathname;
     const target = (_b = (_a6 = url.hash) === null || _a6 === void 0 ? void 0 : _a6.replace(/^#/, "")) !== null && _b !== void 0 ? _b : "";
-    const project = this.intersphinx.find((i2) => {
-      if (url.pathname)
-        return i2.id === url.pathname;
-      if (target)
-        return !!i2.getEntry({ name: target });
-      return false;
-    });
+    const project = this.intersphinx.find((i2) => i2.id === id);
     if (!project || !project.path) {
-      fileWarn(file, `Unknown project "${url.pathname}" for link: ${urlSource}`, {
+      fileError(file, `Unknown project "${id}" for link: ${urlSource}`, {
         node: link4,
-        source: TRANSFORM_SOURCE3,
-        ruleId: RuleId.mystLinkValid
+        source: TRANSFORM_SOURCE4,
+        ruleId: RuleId.sphinxLinkValid
       });
       return false;
     }
-    if (!url.hash) {
+    if (!target) {
       link4.internal = false;
       link4.url = project.path;
       updateLinkTextIfEmpty(link4, project.id || "(see documentation)");
-      return false;
+      return true;
     }
     const entry = project.getEntry({ name: target });
     if (!entry) {
-      fileWarn(file, `"${urlSource}" not found intersphinx ${project.id} (${project.path})`, {
+      fileError(file, `"${urlSource}" not found in intersphinx ${project.id} (${project.path})`, {
         node: link4,
-        source: TRANSFORM_SOURCE3,
-        ruleId: RuleId.mystLinkValid
+        source: TRANSFORM_SOURCE4,
+        ruleId: RuleId.sphinxLinkValid
       });
       return false;
     }
@@ -235926,7 +236082,7 @@ var MystTransformer = class {
 // ../myst-transforms/dist/links/wiki.js
 var DEFAULT_LANGUAGE = "en";
 var ANY_WIKIPEDIA_ORG = /^(?:https?:\/\/)?(?:([a-z]+)\.)?wikipedia\.org\/wiki\/(.+)$/;
-var TRANSFORM_SOURCE4 = "LinkTransform:WikiTransformer";
+var TRANSFORM_SOURCE5 = "LinkTransform:WikiTransformer";
 function removeWiki(url, replace = "") {
   return url.replace(/\/?(wiki\/?)?$/, replace).replace(/^\/?(wiki\/)/, "");
 }
@@ -235969,7 +236125,7 @@ var WikiTransformer = class {
       fileWarn(file, `Wikipedia pagenames should not contain spaces in link: ${urlSource}`, {
         node: link4,
         note: "Replace spaces with underscores",
-        source: TRANSFORM_SOURCE4,
+        source: TRANSFORM_SOURCE5,
         ruleId: RuleId.wikipediaLinkValid
       });
       return false;
@@ -235979,7 +236135,7 @@ var WikiTransformer = class {
       fileWarn(file, `Wikipedia pagenames should not contain spaces in link: ${urlSource}`, {
         node: link4,
         note: "Replace spaces with underscores",
-        source: TRANSFORM_SOURCE4,
+        source: TRANSFORM_SOURCE5,
         ruleId: RuleId.wikipediaLinkValid
       });
     }
@@ -235987,7 +236143,7 @@ var WikiTransformer = class {
       fileError(file, `Wikipedia pagenames should not contain "/" in link: ${urlSource}`, {
         node: link4,
         note: "Only point to the final page name, do not include any other parts of the Wikipedia URL.",
-        source: TRANSFORM_SOURCE4,
+        source: TRANSFORM_SOURCE5,
         ruleId: RuleId.wikipediaLinkValid
       });
       return false;
@@ -236008,7 +236164,7 @@ var WikiTransformer = class {
 
 // ../myst-transforms/dist/links/rrid.js
 var RESOLVER = "https://scicrunch.org/resolver/";
-var TRANSFORM_SOURCE5 = "LinkTransform:RRIDTransformer";
+var TRANSFORM_SOURCE6 = "LinkTransform:RRIDTransformer";
 function isValid(rrid) {
   return !!rrid;
 }
@@ -236038,7 +236194,7 @@ var RRIDTransformer = class {
     if (!isValid(rrid)) {
       fileWarn(file, `RRID is not valid: ${urlSource}`, {
         node: link4,
-        source: TRANSFORM_SOURCE5,
+        source: TRANSFORM_SOURCE6,
         ruleId: RuleId.rridLinkValid
       });
       return false;
@@ -236052,7 +236208,7 @@ var RRIDTransformer = class {
 };
 
 // ../myst-transforms/dist/links/doi.js
-var TRANSFORM_SOURCE6 = "LinkTransform:DOITransformer";
+var TRANSFORM_SOURCE7 = "LinkTransform:DOITransformer";
 var DOITransformer = class {
   constructor() {
     this.protocol = "doi";
@@ -236071,7 +236227,7 @@ var DOITransformer = class {
     if (!doiUrl2) {
       fileError(file, `DOI is not valid: ${urlSource}`, {
         node: link4,
-        source: TRANSFORM_SOURCE6,
+        source: TRANSFORM_SOURCE7,
         ruleId: RuleId.doiLinkValid
       });
       return false;
@@ -236160,6 +236316,22 @@ var GithubTransformer = class {
   }
 };
 
+// ../myst-transforms/dist/links/check.js
+function checkLinkTextTransform(mdast2, vfile2) {
+  const linkNodes = selectAll("link,linkBlock,card,crossReference", mdast2);
+  if (linkNodes.length === 0)
+    return;
+  linkNodes.forEach((node3) => {
+    var _a6;
+    if (!toText(node3.children) && !select("image", node3)) {
+      fileWarn(vfile2, `Link text is empty for <${(_a6 = node3.urlSource) !== null && _a6 !== void 0 ? _a6 : node3.url}>`, {
+        node: node3,
+        ruleId: RuleId.linkTextExists
+      });
+    }
+  });
+}
+
 // ../myst-transforms/dist/targets.js
 function mystTargetsTransform(tree) {
   visit(tree, "mystTarget", (node3, index4, parent2) => {
@@ -236336,7 +236508,18 @@ var abbreviationPlugin = (opts) => (tree) => {
 };
 
 // ../myst-transforms/dist/include.js
-async function includeDirectiveTransform(tree, vfile2, opts) {
+function updateFrontmatterFromInclude(frontmatter, includeFrontmatter) {
+  if (frontmatter.math || (includeFrontmatter === null || includeFrontmatter === void 0 ? void 0 : includeFrontmatter.math)) {
+    frontmatter.math = { ...frontmatter.math, ...includeFrontmatter === null || includeFrontmatter === void 0 ? void 0 : includeFrontmatter.math };
+  }
+  if (frontmatter.abbreviations || (includeFrontmatter === null || includeFrontmatter === void 0 ? void 0 : includeFrontmatter.abbreviations)) {
+    frontmatter.abbreviations = {
+      ...frontmatter.abbreviations,
+      ...includeFrontmatter === null || includeFrontmatter === void 0 ? void 0 : includeFrontmatter.abbreviations
+    };
+  }
+}
+async function includeDirectiveTransform(tree, frontmatter, vfile2, opts) {
   const includeNodes = selectAll("include", tree);
   if (includeNodes.length === 0)
     return;
@@ -236408,12 +236591,14 @@ async function includeDirectiveTransform(tree, vfile2, opts) {
         children = [container4];
       }
     } else {
-      children = await opts.parseContent(fullFile, content3, vfile2);
+      const parsed = await opts.parseContent(fullFile, content3);
+      children = parsed.mdast.children;
+      updateFrontmatterFromInclude(frontmatter, parsed.frontmatter);
     }
     node3.children = children;
     if (!((_b = node3.children) === null || _b === void 0 ? void 0 : _b.length))
       return;
-    await includeDirectiveTransform(node3, vfile2, {
+    await includeDirectiveTransform(node3, frontmatter, vfile2, {
       ...opts,
       stack: [...(_c = opts.stack) !== null && _c !== void 0 ? _c : [], fullFile],
       sourceFile: fullFile
@@ -236893,7 +237078,7 @@ var ReferenceState = class {
         return;
       if (node3.implicit)
         return;
-      fileWarn(this.vfile, `Duplicate identifier "${node3.identifier}" for node of type ${node3.type}`, {
+      fileWarn(this.vfile, `Duplicate identifier in file "${node3.identifier}"`, {
         node: node3,
         source: TRANSFORM_NAME2,
         ruleId: RuleId.identifierIsUnique
@@ -236949,6 +237134,9 @@ var ReferenceState = class {
     node3.enumerator = enumerator;
     return enumerator;
   }
+  getIdentifiers() {
+    return [...this.identifiers, ...Object.keys(this.targets)];
+  }
   getTarget(identifier) {
     if (!identifier)
       return void 0;
@@ -236961,7 +237149,6 @@ var ReferenceState = class {
       return this;
   }
   resolveReferenceContent(node3) {
-    var _a6, _b, _c;
     const fileTarget = this.getFileTarget(node3.identifier);
     if (fileTarget) {
       const { url, title, dataUrl } = fileTarget;
@@ -236982,26 +237169,32 @@ var ReferenceState = class {
       return;
     }
     node3.kind = target.kind;
-    const noNodeChildren = !((_a6 = node3.children) === null || _a6 === void 0 ? void 0 : _a6.length);
-    if (target.kind === TargetKind.heading) {
-      const numberHeading = shouldEnumerate(target.node, TargetKind.heading, this.numbering);
-      const template = getReferenceTemplate(target, this.numbering, numberHeading, true);
-      fillReferenceEnumerators2(this.vfile, node3, template, target.node, copyNode(target.node).children);
-    } else {
-      const caption3 = select("caption", target.node) || select("admonitionTitle", target.node) || select("definitionTerm", target.node);
-      const captionParagraph = caption3 ? (_b = select("paragraph", caption3)) !== null && _b !== void 0 ? _b : caption3 : caption3;
-      const title = captionParagraph ? (_c = copyNode(captionParagraph)) === null || _c === void 0 ? void 0 : _c.children : void 0;
-      if (title && node3.kind === ReferenceKind2.ref && noNodeChildren) {
-        node3.children = title;
-      }
-      const template = getReferenceTemplate(target, this.numbering, !!target.node.enumerator, !!title);
-      fillReferenceEnumerators2(this.vfile, node3, template, target.node, title);
-    }
-    node3.resolved = true;
-    node3.identifier = target.node.identifier;
-    node3.html_id = target.node.html_id;
+    addChildrenFromTargetNode(node3, target.node, this.numbering, this.vfile);
   }
 };
+function addChildrenFromTargetNode(node3, targetNode, numbering, vfile2) {
+  var _a6, _b, _c;
+  numbering = fillNumbering(numbering, DEFAULT_NUMBERING);
+  const kind = kindFromNode2(targetNode);
+  const noNodeChildren = !((_a6 = node3.children) === null || _a6 === void 0 ? void 0 : _a6.length);
+  if (kind === TargetKind.heading) {
+    const numberHeading = shouldEnumerate(targetNode, TargetKind.heading, numbering);
+    const template = getReferenceTemplate({ node: targetNode, kind }, numbering, numberHeading, true);
+    fillReferenceEnumerators2(vfile2, node3, template, targetNode, copyNode(targetNode).children);
+  } else {
+    const caption3 = select("caption", targetNode) || select("admonitionTitle", targetNode) || select("definitionTerm", targetNode);
+    const captionParagraph = caption3 ? (_b = select("paragraph", caption3)) !== null && _b !== void 0 ? _b : caption3 : caption3;
+    const title = captionParagraph ? (_c = copyNode(captionParagraph)) === null || _c === void 0 ? void 0 : _c.children : void 0;
+    if (title && node3.kind === ReferenceKind2.ref && noNodeChildren) {
+      node3.children = title;
+    }
+    const template = getReferenceTemplate({ node: targetNode, kind }, numbering, !!targetNode.enumerator, !!title);
+    fillReferenceEnumerators2(vfile2, node3, template, targetNode, title);
+  }
+  node3.resolved = true;
+  node3.identifier = targetNode.identifier;
+  node3.html_id = targetNode.html_id;
+}
 function warnNodeTargetNotFound(node3, vfile2) {
   if (!vfile2)
     return;
@@ -237027,6 +237220,9 @@ var MultiPageReferenceResolver = class {
     });
     return pageXRefs;
   }
+  getIdentifiers() {
+    return this.states.map((state) => state.getIdentifiers()).flat();
+  }
   getTarget(identifier, page) {
     const pageXRefs = this.resolveStateProvider(identifier, page);
     return pageXRefs === null || pageXRefs === void 0 ? void 0 : pageXRefs.getTarget(identifier);
@@ -237207,6 +237403,8 @@ function unnestCrossReferencesTransform(tree) {
 }
 var resolveCrossReferencesTransform = (tree, opts) => {
   visit(tree, "crossReference", (node3) => {
+    if (node3.protocol)
+      return;
     opts.state.resolveReferenceContent(node3);
   });
 };
@@ -237298,7 +237496,7 @@ function getFrontmatter(file, tree, opts = { propagateTargets: true }) {
   const nextNodeIsH1 = (nextNode === null || nextNode === void 0 ? void 0 : nextNode.type) === "heading" && nextNode.depth === 1;
   if (nextNodeIsH1 && !titleNull) {
     const title = toText(nextNode.children);
-    if (frontmatter.title && frontmatter.title === title) {
+    if (frontmatter.title && frontmatter.title === title && !opts.keepTitleNode) {
       nextNode.type = "__delete__";
       frontmatter.content_includes_title = false;
       if (nextNode.label) {
@@ -239775,13 +239973,20 @@ function frontmatterValidationOpts(vfile2, opts) {
     }
   };
 }
-function getPageFrontmatter(session, tree, vfile2, preFrontmatter) {
+function getPageFrontmatter(session, tree, vfile2, preFrontmatter, keepTitleNode) {
+  var _a6;
   const { frontmatter: rawPageFrontmatter, identifiers } = getFrontmatter(vfile2, tree, {
     propagateTargets: true,
-    preFrontmatter
+    preFrontmatter,
+    keepTitleNode
   });
   unnestKernelSpec(rawPageFrontmatter);
   const pageFrontmatter = validatePageFrontmatter(rawPageFrontmatter, frontmatterValidationOpts(vfile2));
+  if (pageFrontmatter.label) {
+    const { identifier } = (_a6 = normalizeLabel(pageFrontmatter.label)) !== null && _a6 !== void 0 ? _a6 : {};
+    if (identifier)
+      identifiers.push(identifier);
+  }
   logMessagesFromVFile(session, vfile2);
   return { frontmatter: pageFrontmatter, identifiers };
 }
@@ -240498,7 +240703,9 @@ var LatexSpecialSymbols = {
   textdegree: "\xBA",
   textasciitilde: "~",
   textvisiblespace: " ",
+  // Not sure this will work, but close enough
   " ": " ",
+  // this is a single backslash followed by a space
   ",": THIN_SPACE
   // this is a thin space (https://en.wikipedia.org/wiki/Thin_space) `\,` in latex
 };
@@ -240541,6 +240748,7 @@ var textOnlyReplacements = {
   "'": "\u2019",
   "`": "\u2018",
   "---": "\u2014",
+  // must be above the next one
   "--": "\u2013",
   "~": "\u202F"
 };
@@ -276221,6 +276429,7 @@ function parseArgument(node3, next) {
         type: "argument",
         content: [],
         openMark: next.content,
+        // will `closeMark` in next pass
         position: { start: (_a6 = next.position) === null || _a6 === void 0 ? void 0 : _a6.start }
       });
       return true;
@@ -276439,24 +276648,43 @@ var SECTION_HANDLERS = {
 var colors = {
   // Standard html colors:
   black: "black",
+  // #000000
   blue: "blue",
+  // #0000FF
   brown: "brown",
+  // #A52A2A
   cyan: "cyan",
+  // #00FFFF
   darkgray: "darkgray",
+  // #A9A9A9
   gray: "gray",
+  // #808080
   green: "green",
+  // #008000
   lightgray: "lightgray",
+  // #D3D3D3
   lime: "lime",
+  // #00FF00
   magenta: "magenta",
+  // #FF00FF
   olive: "olive",
+  // #808000
   orange: "orange",
+  // #FFA500
   pink: "pink",
+  // #FFC0CB
   purple: "purple",
+  // #800080
   red: "red",
+  // #FF0000
   teal: "teal",
+  // #008080
   violet: "violet",
+  // #EE82EE
   white: "white",
+  // #FFFFFF
   yellow: "yellow",
+  // #FFFF00
   // Other named latex colors
   Apricot: "#FBB982",
   Aquamarine: "#00B5BE",
@@ -277758,36 +277986,62 @@ var UNITS = {
   litre: "L",
   liter: "L",
   arcminute: "\u2032",
+  // minute (plane angle) U+2032
   minute: "min",
+  // minute (time)
   arcsecond: "\u2033",
+  // second (plane angle) U+2033
   neper: "Np",
   tonne: "t",
   celsius: "\u2103"
 };
 var PREFIXES = {
   quecto: "q",
+  // -30
   ronto: "r",
+  // -27
   yocto: "y",
+  // -24
   zepto: "z",
+  // -21
   atto: "a",
+  // -18
   femto: "f",
+  // -15
   pico: "p",
+  // -12
   nano: "n",
+  // -9
   micro: "\xB5",
+  // -6
   milli: "m",
+  // -3
   centi: "c",
+  // -2
   deci: "d",
+  // -1
   deca: "da",
+  // 1
   hecto: "h",
+  // 2
   kilo: "k",
+  // 3
   mega: "M",
+  // 6
   giga: "G",
+  // 9
   tera: "T",
+  // 12
   peta: "P",
+  // 15
   exa: "E",
+  // 18
   zetta: "Z",
+  // 21
   yotta: "Y",
+  // 24
   ronna: "R",
+  // 27
   quetta: "Q"
   // 30
 };
@@ -277851,7 +278105,9 @@ var ABBREVIATIONS = {
   GPa: "giga pascal",
   mohm: "milli ohm",
   kohm: "kilo ohm",
+  // kilohm
   Mohm: "mega ohm",
+  // megohm
   pV: "pico volt",
   nV: "nano volt",
   uV: "micro volt",
@@ -283966,31 +284222,54 @@ var UNITS2 = {
   litre: "L",
   liter: "L",
   arcminute: "\u2032",
+  // minute (plane angle) U+2032
   minute: "min",
+  // minute (time)
   arcsecond: "\u2033",
+  // second (plane angle) U+2033
   neper: "Np",
   tonne: "t",
   // SI prefixes
   yocto: "y",
+  // -24
   zepto: "z",
+  // -21
   atto: "a",
+  // -18
   femto: "f",
+  // -15
   pico: "p",
+  // -12
   nano: "n",
+  // -9
   micro: "\xB5",
+  // -6
   milli: "m",
+  // -3
   centi: "c",
+  // -2
   deci: "d",
+  // -1
   deca: "da",
+  // 1
   hecto: "h",
+  // 2
   kilo: "k",
+  // 3
   mega: "M",
+  // 6
   giga: "G",
+  // 9
   tera: "T",
+  // 12
   peta: "P",
+  // 15
   exa: "E",
+  // 18
   zetta: "Z",
+  // 21
   yotta: "Y",
+  // 24
   // Special
   angstrom: "\xC5"
 };
@@ -285270,10 +285549,15 @@ var tlds = [
 var MARKDOWN_IT_CONFIG = {
   options: {
     html: true,
+    // Enable HTML tags in source
     xhtmlOut: true,
+    // Use '/' to close single tags (<br />)
     breaks: false,
+    // Convert '\n' in paragraphs into <br>
     langPrefix: "language-",
+    // CSS language prefix for fenced blocks
     linkify: false,
+    // autoconvert URL-like texts to links
     // Enable some language-neutral replacements + quotes beautification
     typographer: false,
     // Double + single quotes replacement pairs, when typographer enabled,
@@ -285601,7 +285885,9 @@ var defaultMdast = {
         ...normalizeLabel(name3),
         class: getClassName(t2),
         showLineNumbers: showLineNumbers || void 0,
+        // Only add to MDAST if true
         startingLineNumber: showLineNumbers ? startingLineNumber : void 0,
+        // Only if showing line numbers!
         emphasizeLines,
         value: withoutTrailingNewline(t2.content)
       };
@@ -285797,6 +286083,7 @@ var defaultMdast = {
         label,
         kind: t2.meta.kind,
         partial: t2.meta.partial,
+        // author or year
         // TODO: can use the parsed version in the future
         prefix: (_b = t2.meta.prefix) === null || _b === void 0 ? void 0 : _b[0].content,
         suffix: (_c = t2.meta.suffix) === null || _c === void 0 ? void 0 : _c[0].content
@@ -286877,6 +287164,7 @@ var tabSetDirective = {
 var tabItemDirective = {
   name: "tab-item",
   alias: ["tabItem", "tab"],
+  // TODO: A transform is necessary for stray `tab`s
   arg: {
     type: String
   },
@@ -286942,7 +287230,7 @@ var import_node_path17 = __toESM(require("path"), 1);
 var import_nbtx = __toESM(require_cjs2(), 1);
 
 // ../myst-cli/dist/version.js
-var version2 = "1.1.56";
+var version2 = "1.2.1";
 var version_default2 = version2;
 
 // ../myst-cli/dist/utils/headers.js
@@ -287006,7 +287294,7 @@ ${source_default.bold.blue(docLinks.installNode)}
 `;
 async function getNodeVersion(session) {
   const result = new Promise((resolve7) => {
-    (0, import_check_node_version.default)({ node: ">= 16.0.0", npm: ">=7" }, (error, results) => {
+    (0, import_check_node_version.default)({ node: ">= 18.0.0", npm: ">=8.6.0" }, (error, results) => {
       if (error) {
         session.log.error(error);
         resolve7(null);
@@ -287163,8 +287451,8 @@ var tocFile = (filename) => {
     return filename;
   return (0, import_node_path14.join)(filename, "_toc.yml");
 };
-function upgradeOldJupyterBookToc(oldToc) {
-  const [root6, ...parts] = oldToc;
+function upgradeOldJupyterBookTOC(oldTOC) {
+  const [root6, ...parts] = oldTOC;
   const toc = {
     root: root6.file,
     format: TOC_FORMAT,
@@ -287180,7 +287468,7 @@ function readTOC(log, opts) {
   const toc = js_yaml_default.load(import_node_fs7.default.readFileSync(filename).toString());
   if (Array.isArray(toc)) {
     try {
-      const old = upgradeOldJupyterBookToc(toc);
+      const old = upgradeOldJupyterBookTOC(toc);
       log.warn(`${filename} is out of date: see https://executablebooks.org/en/latest/blog/2021-06-18-update-toc`);
       return old;
     } catch (error) {
@@ -287211,7 +287499,7 @@ function validateTOC(session, path42) {
     addWarningForFile(session, filename, `Table of Contents (ToC) file did not pass validation:
  - ${message}
  - An implicit ToC will be used instead
-`, "error", { ruleId: RuleId.validTocStructure });
+`, "error", { ruleId: RuleId.validTOCStructure });
     return false;
   }
 }
@@ -288095,6 +288383,38 @@ function checkCache(cache, content3, file) {
   const useCache = (mdast2 === null || mdast2 === void 0 ? void 0 : mdast2.pre) && mdast2.sha256 === sha256;
   return { useCache, sha256 };
 }
+function loadMdFile(session, content3, file, opts) {
+  const vfile2 = new VFile();
+  vfile2.path = file;
+  const mdast2 = parseMyst(session, content3, file);
+  const { frontmatter, identifiers } = getPageFrontmatter(session, mdast2, vfile2, opts === null || opts === void 0 ? void 0 : opts.preFrontmatter, opts === null || opts === void 0 ? void 0 : opts.keepTitleNode);
+  return { kind: SourceFileKind.Article, mdast: mdast2, frontmatter, identifiers };
+}
+async function loadNotebookFile(session, content3, file, opts) {
+  const vfile2 = new VFile();
+  vfile2.path = file;
+  const mdast2 = await processNotebook(session, file, content3);
+  const { frontmatter, identifiers } = getPageFrontmatter(session, mdast2, vfile2, opts === null || opts === void 0 ? void 0 : opts.preFrontmatter, opts === null || opts === void 0 ? void 0 : opts.keepTitleNode);
+  return { kind: SourceFileKind.Notebook, mdast: mdast2, frontmatter, identifiers };
+}
+function loadTexFile(session, content3, file, opts) {
+  var _a6;
+  const vfile2 = new VFile();
+  vfile2.path = file;
+  const tex = new TexParser(content3, vfile2);
+  const frontmatter = validatePageFrontmatter({
+    title: toText(tex.data.frontmatter.title),
+    short_title: toText(tex.data.frontmatter.short_title),
+    authors: tex.data.frontmatter.authors,
+    // TODO: affiliations: tex.data.frontmatter.affiliations,
+    keywords: tex.data.frontmatter.keywords,
+    math: tex.data.macros,
+    bibliography: tex.data.bibliography,
+    ...(_a6 = opts === null || opts === void 0 ? void 0 : opts.preFrontmatter) !== null && _a6 !== void 0 ? _a6 : {}
+  }, frontmatterValidationOpts(vfile2));
+  logMessagesFromVFile(session, vfile2);
+  return { kind: SourceFileKind.Article, mdast: tex.ast, frontmatter };
+}
 async function loadFile(session, file, projectPath, extension, opts) {
   var _a6, _b;
   await session.loadPlugins();
@@ -288107,35 +288427,26 @@ async function loadFile(session, file, projectPath, extension, opts) {
     location4 = `/${import_node_path18.default.relative(projectPath, file)}`;
   }
   location4 = location4.replaceAll("\\", "/");
-  const vfile2 = new VFile();
-  vfile2.path = file;
   try {
+    const content3 = import_node_fs11.default.readFileSync(file).toString();
+    const { sha256, useCache } = checkCache(cache, content3, file);
+    if (useCache) {
+      session.log.debug(toc(`loadFile: ${file} already loaded.`));
+      return (_a6 = cache.$getMdast(file)) === null || _a6 === void 0 ? void 0 : _a6.pre;
+    }
     const ext2 = extension || import_node_path18.default.extname(file).toLowerCase();
+    let loadResult;
     switch (ext2) {
       case ".md": {
-        const content3 = import_node_fs11.default.readFileSync(file).toString();
-        const { sha256, useCache } = checkCache(cache, content3, file);
-        if (useCache)
-          break;
-        const mdast2 = parseMyst(session, content3, file);
-        const { frontmatter, identifiers } = getPageFrontmatter(session, mdast2, vfile2, opts === null || opts === void 0 ? void 0 : opts.preFrontmatter);
-        cache.$setMdast(file, {
-          sha256,
-          pre: { kind: SourceFileKind.Article, file, location: location4, mdast: mdast2, frontmatter, identifiers }
-        });
+        loadResult = loadMdFile(session, content3, file, opts);
         break;
       }
       case ".ipynb": {
-        const content3 = import_node_fs11.default.readFileSync(file).toString();
-        const { sha256, useCache } = checkCache(cache, content3, file);
-        if (useCache)
-          break;
-        const mdast2 = await processNotebook(cache, file, content3);
-        const { frontmatter, identifiers } = getPageFrontmatter(session, mdast2, vfile2, opts === null || opts === void 0 ? void 0 : opts.preFrontmatter);
-        cache.$setMdast(file, {
-          sha256,
-          pre: { kind: SourceFileKind.Notebook, file, location: location4, mdast: mdast2, frontmatter, identifiers }
-        });
+        loadResult = await loadNotebookFile(session, content3, file, opts);
+        break;
+      }
+      case ".tex": {
+        loadResult = loadTexFile(session, content3, file, opts);
         break;
       }
       case ".bib": {
@@ -288143,35 +288454,6 @@ async function loadFile(session, file, projectPath, extension, opts) {
         cache.$citationRenderers[file] = renderer;
         break;
       }
-      case ".tex": {
-        const content3 = import_node_fs11.default.readFileSync(file).toString();
-        const { sha256, useCache } = checkCache(cache, content3, file);
-        if (useCache)
-          break;
-        const tex = new TexParser(content3, vfile2);
-        const frontmatter = validatePageFrontmatter({
-          title: toText(tex.data.frontmatter.title),
-          short_title: toText(tex.data.frontmatter.short_title),
-          authors: tex.data.frontmatter.authors,
-          // TODO: affiliations: tex.data.frontmatter.affiliations,
-          keywords: tex.data.frontmatter.keywords,
-          math: tex.data.macros,
-          bibliography: tex.data.bibliography,
-          ...(_a6 = opts === null || opts === void 0 ? void 0 : opts.preFrontmatter) !== null && _a6 !== void 0 ? _a6 : {}
-        }, frontmatterValidationOpts(vfile2));
-        logMessagesFromVFile(session, vfile2);
-        cache.$setMdast(file, {
-          sha256,
-          pre: {
-            kind: SourceFileKind.Article,
-            file,
-            mdast: tex.ast,
-            location: location4,
-            frontmatter
-          }
-        });
-        break;
-      }
       default:
         addWarningForFile(session, file, "Unrecognized extension", "error", {
           ruleId: RuleId.mystFileLoads
@@ -288179,6 +288461,12 @@ async function loadFile(session, file, projectPath, extension, opts) {
         session.log.info(`"${file}": Please rerun the build with "-c" to ensure the built files are cleared.`);
         success = false;
     }
+    if (loadResult) {
+      cache.$setMdast(file, {
+        sha256,
+        pre: { file, location: location4, ...loadResult }
+      });
+    }
   } catch (error) {
     session.log.debug(`
 
@@ -294622,7 +294910,7 @@ var glob = Object.assign(glob_, {
 });
 glob.glob = glob;
 
-// ../myst-cli/dist/project/fromToc.js
+// ../myst-cli/dist/project/fromTOC.js
 var import_node_fs12 = __toESM(require("fs"), 1);
 var import_node_path19 = require("path");
 function pagesFromChapters(session, path42, chapters, pages = [], level = 1, pageSlugs) {
@@ -294646,7 +294934,7 @@ function pagesFromChapters(session, path42, chapters, pages = [], level = 1, pag
   });
   return pages;
 }
-function projectFromToc(session, path42, level = 1) {
+function projectFromTOC(session, path42, level = 1) {
   const filename = tocFile(path42);
   if (!import_node_fs12.default.existsSync(filename)) {
     throw new Error(`Could not find TOC "${filename}". Please create a '_toc.yml'.`);
@@ -294684,8 +294972,8 @@ function projectFromToc(session, path42, level = 1) {
   }
   return { path: dir || ".", file: indexFile, index: slug, pages };
 }
-function pagesFromToc(session, path42, level) {
-  const { file, index: index4, pages } = projectFromToc(session, path42, nextLevel(level));
+function pagesFromTOC(session, path42, level) {
+  const { file, index: index4, pages } = projectFromTOC(session, path42, nextLevel(level));
   pages.unshift({ file, slug: index4, level });
   return pages;
 }
@@ -294708,10 +294996,10 @@ function projectPagesFromPath(session, path42, level, pageSlugs, opts) {
   if (contents.includes((0, import_node_path20.join)(path42, "_toc.yml"))) {
     const prevLevel = level < 2 ? 1 : level - 1;
     try {
-      return pagesFromToc(session, path42, prevLevel);
+      return pagesFromTOC(session, path42, prevLevel);
     } catch {
       if (!suppressWarnings) {
-        addWarningForFile(session, (0, import_node_path20.join)(path42, "_toc.yml"), `Invalid table of contents ignored`, "warn", { ruleId: RuleId.validToc });
+        addWarningForFile(session, (0, import_node_path20.join)(path42, "_toc.yml"), `Invalid table of contents ignored`, "warn", { ruleId: RuleId.validTOC });
       }
     }
   }
@@ -294796,7 +295084,7 @@ async function projectFromPath(session, path42, indexFile) {
   return { file: indexFile, index: slug, path: path42, pages, implicitIndex };
 }
 
-// ../myst-cli/dist/project/toToc.js
+// ../myst-cli/dist/project/toTOC.js
 var import_node_fs14 = __toESM(require("fs"), 1);
 var import_node_path21 = require("path");
 function getRelativeDocumentLink(file, path42) {
@@ -294861,7 +295149,7 @@ function tocFromProject(project, path42 = ".") {
   };
   return toc;
 }
-function writeTocFromProject(project, path42) {
+function writeTOCFromProject(project, path42) {
   const filename = (0, import_node_path21.join)(path42, "_toc.yml");
   const content3 = `${GENERATED_TOC_HEADER}${js_yaml_default.dump(tocFromProject(project, path42))}`;
   import_node_fs14.default.writeFileSync(filename, content3);
@@ -294882,13 +295170,13 @@ async function loadProjectFromDisk(session, path42, opts) {
 Consider running "myst init --project" in that directory`, "warn", { ruleId: RuleId.projectConfigExists });
   }
   let newProject;
-  let { index: index4, writeToc } = opts || {};
+  let { index: index4, writeTOC } = opts || {};
   const projectConfigFile = selectors_exports.selectLocalConfigFile(session.store.getState(), path42);
   if (validateTOC(session, path42)) {
-    newProject = projectFromToc(session, path42);
-    if (writeToc)
+    newProject = projectFromTOC(session, path42);
+    if (writeTOC)
       session.log.warn("Not writing the table of contents, it already exists!");
-    writeToc = false;
+    writeTOC = false;
   } else {
     const project2 = selectors_exports.selectLocalProject(session.store.getState(), path42);
     if (!index4 && !(project2 === null || project2 === void 0 ? void 0 : project2.implicitIndex) && (project2 === null || project2 === void 0 ? void 0 : project2.file)) {
@@ -294899,11 +295187,11 @@ Consider running "myst init --project" in that directory`, "warn", { ruleId: Rul
   if (!newProject) {
     throw new Error(`Could not load project from ${path42}`);
   }
-  if (writeToc) {
+  if (writeTOC) {
     try {
       session.log.info(`\u{1F4D3} Writing '_toc.yml' file to ${path42 === "." ? "the current directory" : path42}`);
-      writeTocFromProject(newProject, path42);
-      newProject = projectFromToc(session, path42);
+      writeTOCFromProject(newProject, path42);
+      newProject = projectFromTOC(session, path42);
     } catch {
       addWarningForFile(session, projectConfigFile, `Error writing '_toc.yml' file to ${path42}`, "error", { ruleId: RuleId.tocWritten });
     }
@@ -297521,7 +297809,7 @@ function resolveArticlesFromTOC(session, exp, tocPath, vfile2) {
     ExportFormats.pdf,
     ExportFormats.pdftex
   ].includes(exp.format);
-  const proj = projectFromToc(session, tocPath, allowLevelLessThanOne ? -1 : 1);
+  const proj = projectFromTOC(session, tocPath, allowLevelLessThanOne ? -1 : 1);
   return resolveArticlesFromProject(exp, proj, vfile2);
 }
 function resolveTemplate(sourceFile, exp, disableTemplate) {
@@ -297574,9 +297862,9 @@ function resolveArticles(session, sourceFile, vfile2, exp, projectPath) {
   const { articles, sub_articles } = exp;
   let resolved = { articles, sub_articles };
   if (exp.toc && !resolved.articles && !resolved.sub_articles) {
-    const resolvedToc = import_node_path28.default.resolve(import_node_path28.default.dirname(sourceFile), exp.toc);
-    if (validateTOC(session, resolvedToc)) {
-      resolved = resolveArticlesFromTOC(session, exp, resolvedToc, vfile2);
+    const resolvedTOC = import_node_path28.default.resolve(import_node_path28.default.dirname(sourceFile), exp.toc);
+    if (validateTOC(session, resolvedTOC)) {
+      resolved = resolveArticlesFromTOC(session, exp, resolvedTOC, vfile2);
     }
   }
   if (!resolved.articles && SOURCE_EXTENSIONS.includes(import_node_path28.default.extname(sourceFile))) {
@@ -297990,79 +298278,127 @@ async function getSiteManifest(session, opts) {
   return manifest;
 }
 
-// ../myst-cli/dist/process/loadIntersphinx.js
+// ../myst-cli/dist/process/loadReferences.js
 var import_node_fs23 = __toESM(require("fs"), 1);
 var import_node_path30 = require("path");
-function inventoryCacheFile(session, id, path42) {
+function inventoryCacheFile(session, refKind, id, path42) {
   const hashcontent = `${id}${path42}`;
-  const filename = `intersphinx-${computeHash(hashcontent)}.inv`;
+  const ext2 = refKind === "intersphinx" ? "inv" : "json";
+  const filename = `${refKind}-${computeHash(hashcontent)}.${ext2}`;
   const cacheFolder = (0, import_node_path30.join)(session.buildPath(), "cache");
   if (!import_node_fs23.default.existsSync(cacheFolder))
     import_node_fs23.default.mkdirSync(cacheFolder, { recursive: true });
   return (0, import_node_path30.join)(cacheFolder, filename);
 }
-async function loadIntersphinx(session, opts) {
-  const state = session.store.getState();
-  const projectConfig = selectors_exports.selectLocalProjectConfig(state, opts.projectPath);
-  const configFile = selectors_exports.selectLocalConfigFile(state, opts.projectPath);
-  if (!(projectConfig === null || projectConfig === void 0 ? void 0 : projectConfig.references) || !configFile)
-    return [];
-  const vfile2 = new VFile();
-  vfile2.path = configFile;
-  const cache = castSession(session);
-  const references = await Promise.all(Object.entries(projectConfig.references).filter(([key2, object]) => {
-    if (isUrl(object.url))
-      return true;
-    fileError(vfile2, `${key2} references is not a valid url: "${object.url}"`, {
-      ruleId: RuleId.intersphinxReferencesResolve
-    });
-    return false;
-  }).map(async ([key2, object]) => {
-    if (!cache.$externalReferences[key2] || opts.force) {
-      const inventory = new Inventory({ id: key2, path: object.url });
-      const cachePath = inventoryCacheFile(session, key2, inventory.path);
-      if (import_node_fs23.default.existsSync(cachePath) && !opts.force) {
-        const localInventory = new Inventory({ id: key2, path: cachePath });
-        session.log.debug(`Loading cached inventory file for ${inventory.path}: ${cachePath}`);
-        const toc = tic();
-        await localInventory.load();
-        inventory.project = localInventory.project;
-        inventory.version = localInventory.version;
-        inventory.data = localInventory.data;
-        inventory._loaded = true;
-        session.log.info(toc(`\u{1F3EB} Read ${inventory.numEntries} references links for "${inventory.id}" in %s.`));
-      }
-      cache.$externalReferences[key2] = inventory;
-    }
-    return cache.$externalReferences[key2];
-  }).filter((exists2) => !!exists2));
-  await Promise.all(references.map(async (loader2) => {
-    if (loader2._loaded)
+async function preloadReference(session, key2, reference) {
+  const ref = {
+    key: key2,
+    url: reference.url,
+    kind: reference.kind
+  };
+  const mystCachePath = inventoryCacheFile(session, "myst", key2, reference.url);
+  const intersphinxCachePath = inventoryCacheFile(session, "intersphinx", key2, reference.url);
+  if ((!ref.kind || ref.kind === "myst") && import_node_fs23.default.existsSync(mystCachePath)) {
+    const toc = tic();
+    const xrefs = JSON.parse(import_node_fs23.default.readFileSync(mystCachePath).toString());
+    session.log.debug(`Loading cached inventory file for ${reference.url}: ${mystCachePath}`);
+    session.log.info(toc(`\u{1F3EB} Read ${xrefs.references.length} references links for "${key2}" in %s.`));
+    ref.kind = "myst";
+    ref.value = xrefs;
+  } else if ((!ref.kind || ref.kind === "intersphinx") && import_node_fs23.default.existsSync(intersphinxCachePath)) {
+    const inventory = new Inventory({ id: key2, path: reference.url });
+    const localInventory = new Inventory({ id: key2, path: intersphinxCachePath });
+    session.log.debug(`Loading cached inventory file for ${reference.url}: ${intersphinxCachePath}`);
+    const toc = tic();
+    await localInventory.load();
+    inventory.project = localInventory.project;
+    inventory.version = localInventory.version;
+    inventory.data = localInventory.data;
+    inventory._loaded = true;
+    session.log.info(toc(`\u{1F3EB} Read ${inventory.numEntries} references links for "${key2}" in %s.`));
+    ref.kind = "intersphinx";
+    ref.value = inventory;
+  }
+  return ref;
+}
+async function loadReference(session, vfile2, reference) {
+  var _a6;
+  if (reference.kind === "myst" && reference.value) {
+    return reference;
+  }
+  if (reference.kind === "intersphinx" && ((_a6 = reference.value) === null || _a6 === void 0 ? void 0 : _a6._loaded)) {
+    return reference;
+  }
+  if (!reference.kind || reference.kind === "myst") {
+    const mystXRefsUrl = `${reference.url}/myst.xref.json`;
+    session.log.debug(`Attempting to load MyST xref file: ${mystXRefsUrl}`);
+    const toc = tic();
+    const mystXRefsResp = await fetch2(mystXRefsUrl);
+    if (mystXRefsResp.status === 200) {
+      reference.kind = "myst";
+      const mystXRefs = await mystXRefsResp.json();
+      reference.value = mystXRefs;
+      const cachePath = inventoryCacheFile(session, "myst", reference.key, reference.url);
+      session.log.debug(`Saving remote myst xref file to cache ${reference.url}: ${cachePath}`);
+      writeFileToFolder(cachePath, JSON.stringify(mystXRefs));
+      session.log.info(toc(`\u{1F3EB} Read ${mystXRefs.references.length} references for "${reference.key}" in %s.`));
+      return reference;
+    } else if (reference.kind === "myst") {
+      fileError(vfile2, `Problem fetching references entry: ${reference.key} (${mystXRefsUrl})`, {
+        ruleId: RuleId.intersphinxReferencesResolve
+      });
       return;
+    } else {
+      session.log.debug(`Unable to load reference "${reference.key}" as MyST cross-references`);
+    }
+  }
+  if (!reference.kind || reference.kind === "intersphinx") {
+    const inventory = new Inventory({ id: reference.key, path: reference.url });
     const toc = tic();
     try {
-      session.log.debug(`Loading inventory file ${loader2.path}`);
-      await loader2.load();
+      session.log.debug(`Attempting to load inventory file ${inventory.path}/objects.inv`);
+      await inventory.load();
     } catch (error) {
-      session.log.debug(`
+      if (reference.kind === "intersphinx") {
+        session.log.debug(`
 
 ${error === null || error === void 0 ? void 0 : error.stack}
 
 `);
-      fileError(vfile2, `Problem fetching references entry: ${loader2.id} (${loader2.path})`, {
-        ruleId: RuleId.intersphinxReferencesResolve
-      });
+        fileError(vfile2, `Problem fetching references entry: ${inventory.id} (${inventory.path})`, {
+          ruleId: RuleId.intersphinxReferencesResolve
+        });
+      } else {
+        session.log.debug(`Unable to load reference "${reference.key}" as intersphinx`);
+      }
       return null;
     }
-    const cachePath = inventoryCacheFile(session, loader2.id, loader2.path);
-    if (!import_node_fs23.default.existsSync(cachePath) && isUrl(loader2.path)) {
-      session.log.debug(`Saving remote inventory file to cache ${loader2.path}: ${cachePath}`);
-      loader2.write(cachePath);
+    const cachePath = inventoryCacheFile(session, "intersphinx", inventory.id, inventory.path);
+    if (!import_node_fs23.default.existsSync(cachePath) && isUrl(inventory.path)) {
+      session.log.debug(`Saving remote inventory file to cache ${inventory.path}: ${cachePath}`);
+      inventory.write(cachePath);
+    }
+    session.log.info(toc(`\u{1F3EB} Read ${inventory.numEntries} references for "${inventory.id}" in %s.`));
+  }
+}
+async function loadReferences(session, opts) {
+  const state = session.store.getState();
+  const projectConfig = selectors_exports.selectLocalProjectConfig(state, opts.projectPath);
+  const configFile = selectors_exports.selectLocalConfigFile(state, opts.projectPath);
+  if (!(projectConfig === null || projectConfig === void 0 ? void 0 : projectConfig.references) || !configFile)
+    return [];
+  const vfile2 = new VFile();
+  vfile2.path = configFile;
+  const cache = castSession(session);
+  const references = await Promise.all(Object.entries(projectConfig.references).map(async ([key2, val]) => {
+    if (!cache.$externalReferences[key2]) {
+      cache.$externalReferences[key2] = await preloadReference(session, key2, val);
     }
-    session.log.info(toc(`\u{1F3EB} Read ${loader2.numEntries} references links for "${loader2.id}" in %s.`));
+    return cache.$externalReferences[key2];
+  }).filter((exists2) => !!exists2));
+  return Promise.all(references.map(async (ref) => {
+    await loadReference(session, vfile2, ref);
   }));
-  logMessagesFromVFile(session, vfile2);
-  return references;
 }
 
 // ../myst-cli/dist/process/mdast.js
@@ -298320,6 +298656,59 @@ function transformLiftCodeBlocksInJupytext(mdast2) {
   mdast2.children = flattened;
 }
 
+// ../myst-cli/dist/transforms/crossReferences.js
+async function transformMystXRefs(session, vfile2, mdast2, frontmatter) {
+  const toc = tic();
+  const nodes = selectAll("link,crossReference", mdast2).filter((node3) => {
+    return node3.protocol === "xref:myst" && node3.dataUrl;
+  }).filter((node3) => {
+    var _a6;
+    if (!((_a6 = node3.children) === null || _a6 === void 0 ? void 0 : _a6.length))
+      return true;
+    return !!node3.identifier;
+  });
+  if (nodes.length === 0)
+    return;
+  session.log.debug(`Updating link text for ${plural("%s external MyST reference(s)", nodes)}`);
+  let number2 = 0;
+  let data;
+  await Promise.all([
+    ...nodes.map(async (node3) => {
+      var _a6, _b, _c;
+      try {
+        const resp = await fetch(node3.dataUrl);
+        if (resp.ok) {
+          data = await resp.json();
+        }
+      } catch {
+      }
+      if (!data) {
+        fileWarn(vfile2, `Unable to resolve link text from external MyST reference: ${node3.urlSource}`, { ruleId: RuleId.mystLinkValid, note: "Could not load data from external project" });
+        return;
+      }
+      if (!node3.identifier) {
+        node3.children = [{ type: "text", value: (_c = (_b = (_a6 = data.frontmatter) === null || _a6 === void 0 ? void 0 : _a6.title) !== null && _b !== void 0 ? _b : data.slug) !== null && _c !== void 0 ? _c : "" }];
+      } else {
+        const targets = selectAll(`[identifier=${node3.identifier}]`, data.mdast);
+        const target = targets.find((t2) => {
+          return !["crossReference", "cite", "footnoteDefinition", "footnoteReference"].includes(t2.type);
+        });
+        if (!target) {
+          fileWarn(vfile2, `Unable to resolve link text from external MyST reference: ${node3.urlSource}`, {
+            ruleId: RuleId.mystLinkValid,
+            note: `Could not locate identifier ${node3.identifier} in page content`
+          });
+          return;
+        }
+        addChildrenFromTargetNode(node3, target, frontmatter.numbering, vfile2);
+      }
+      number2 += 1;
+    })
+  ]);
+  const denominator = number2 === nodes.length ? "" : `/${nodes.length}`;
+  session.log.info(toc(`\u{1FA84}  Updated link text for ${plural(`%s${denominator} external MyST reference(s)`, number2)} in %s seconds`));
+}
+
 // ../myst-cli/dist/transforms/dois.js
 var import_node_fs24 = __toESM(require("fs"), 1);
 var import_node_path31 = require("path");
@@ -298701,26 +299090,25 @@ var makeFileLoader = (session, baseFile) => (fullFile) => {
   }));
   return import_node_fs25.default.readFileSync(fullFile).toString();
 };
-var makeContentParser = (session) => async (filename, content3, vfile2) => {
-  var _a6;
+var makeContentParser = (session, file) => async (filename, content3) => {
   if (filename.toLowerCase().endsWith(".html")) {
-    return [{ type: "html", value: content3 }];
+    const mdast2 = { type: "root", children: [{ type: "html", value: content3 }] };
+    return { mdast: mdast2, kind: SourceFileKind.Article };
   }
+  const opts = { keepTitleNode: true };
   if (filename.toLowerCase().endsWith(".tex")) {
-    const subTex = new TexParser(content3, vfile2);
-    return (_a6 = subTex.ast.children) !== null && _a6 !== void 0 ? _a6 : [];
+    return loadTexFile(session, content3, file, opts);
   }
   if (filename.toLowerCase().endsWith(".ipynb")) {
-    const mdast2 = await processNotebook(session, filename, content3);
-    return mdast2.children;
+    return loadNotebookFile(session, content3, file, opts);
   }
-  return parseMyst(session, content3, filename).children;
+  return loadMdFile(session, content3, file, opts);
 };
-async function includeFilesTransform(session, baseFile, tree, vfile2) {
-  const parseContent = makeContentParser(session);
+async function includeFilesTransform(session, baseFile, tree, frontmatter, vfile2) {
+  const parseContent = makeContentParser(session, baseFile);
   const loadFile2 = makeFileLoader(session, baseFile);
   const resolveFile = makeFileResolver(baseFile);
-  await includeDirectiveTransform(tree, vfile2, {
+  await includeDirectiveTransform(tree, frontmatter, vfile2, {
     resolveFile,
     loadFile: loadFile2,
     parseContent,
@@ -300017,7 +300405,7 @@ async function transformMdast(session, opts) {
   cache.$internalReferences[file] = state;
   frontmatterPartsTransform(session, file, mdast2, frontmatter);
   importMdastFromJson(session, file, mdast2);
-  await includeFilesTransform(session, file, mdast2, vfile2);
+  await includeFilesTransform(session, file, mdast2, frontmatter, vfile2);
   rawDirectiveTransform(mdast2, vfile2);
   liftCodeMetadataToBlock(session, vfile2, mdast2);
   const pipe = unified().use(reconstructHtmlPlugin).use(htmlPlugin, { htmlHandlers }).use(basicTransformationsPlugin, {
@@ -300031,15 +300419,17 @@ async function transformMdast(session, opts) {
   });
   await pipe.run(mdast2, vfile2);
   propagateBlockDataToCode(session, vfile2, mdast2);
-  const intersphinx = projectPath ? await loadIntersphinx(session, { projectPath }) : [];
   const transformers = [
     new WikiTransformer(),
     new GithubTransformer(),
     new RRIDTransformer(),
     new DOITransformer(),
-    new MystTransformer(intersphinx)
+    // This also is picked up in the next transform
+    new MystTransformer(Object.values(cache.$externalReferences)),
+    new SphinxTransformer(Object.values(cache.$externalReferences))
   ];
   linksTransform(mdast2, vfile2, { transformers, selector: LINKS_SELECTOR });
+  await transformMystXRefs(session, vfile2, mdast2, frontmatter);
   cache.$citationRenderers[file] = await transformLinkedDOIs(session, vfile2, mdast2, cache.$doiRenderers, file);
   const rendererFiles = [file];
   if (projectPath) {
@@ -300131,11 +300521,12 @@ async function postProcessMdast(session, { file, checkLinks, pageReferenceStates
   });
   await pipe.run(mdast2, vfile2);
   keysTransform(mdast2);
+  checkLinkTextTransform(mdast2, vfile2);
   logMessagesFromVFile(session, fileState.vfile);
   logMessagesFromVFile(session, vfile2);
   log.debug(toc(`Transformed mdast cross references and links for "${file}" in %s`));
   if (checkLinks)
-    await checkLinksTransform(session, file, mdastPost.mdast);
+    await checkLinksTransform(session, file, mdast2);
 }
 async function finalizeMdast(session, mdast2, frontmatter, file, { imageWriteFolder, useExistingImages, imageAltOutputFolder, imageExtensions, optimizeWebp, simplifyFigures, processThumbnail, maxSizeWebp }) {
   var _a6;
@@ -300220,10 +300611,45 @@ function getReferenceTitleAsText(targetNode) {
   if (caption3)
     return toText(caption3);
 }
-async function addProjectReferencesToObjectsInv(session, inv, opts) {
-  const { pages } = await loadProject(session, opts.projectPath);
-  const pageReferenceStates = selectPageReferenceStates(session, pages);
-  pageReferenceStates.forEach((state) => {
+async function writeMystXRefJson(session, states) {
+  const mystXRefs = {
+    version: "1",
+    myst: version_default2,
+    references: states.filter((state) => {
+      return !!state.url && !!state.dataUrl;
+    }).map((state) => {
+      const { url, dataUrl } = state;
+      const data = `/content${dataUrl}`;
+      const pageRef = { kind: "page", data, url };
+      const pageIdRefs = state.identifiers.map((identifier) => {
+        return { identifier, kind: "page", data, url };
+      });
+      const targetRefs = Object.values(state.targets).map((target) => {
+        var _a6;
+        const { identifier, html_id } = (_a6 = target.node) !== null && _a6 !== void 0 ? _a6 : {};
+        return {
+          identifier,
+          html_id: html_id !== identifier ? html_id : void 0,
+          kind: target.kind,
+          data,
+          url,
+          implicit: target.node.implicit
+        };
+      });
+      return [pageRef, ...pageIdRefs, ...targetRefs];
+    }).flat()
+  };
+  const filename = (0, import_node_path39.join)(session.sitePath(), "myst.xref.json");
+  session.log.debug(`Writing myst.xref.json file: ${filename}`);
+  writeFileToFolder(filename, JSON.stringify(mystXRefs));
+}
+async function writeObjectsInv(session, states, siteConfig) {
+  const inv = new Inventory({
+    project: siteConfig === null || siteConfig === void 0 ? void 0 : siteConfig.title,
+    // TODO: allow a version on the project?!
+    version: String(siteConfig === null || siteConfig === void 0 ? void 0 : siteConfig.version)
+  });
+  states.forEach((state) => {
     var _a6;
     inv.setEntry({
       type: Domains.stdDoc,
@@ -300244,7 +300670,9 @@ async function addProjectReferencesToObjectsInv(session, inv, opts) {
       });
     });
   });
-  return inv;
+  const filename = (0, import_node_path39.join)(session.sitePath(), "objects.inv");
+  session.log.debug(`Writing objects.inv file: ${filename}`);
+  inv.write(filename);
 }
 async function loadProject(session, projectPath, opts) {
   const project = await loadProjectFromDisk(session, projectPath, {
@@ -300254,7 +300682,28 @@ async function loadProject(session, projectPath, opts) {
   const pages = filterPages(project);
   return { project, pages };
 }
-function selectPageReferenceStates(session, pages) {
+function warnOnDuplicateIdentifiers(session, states) {
+  const collisions = {};
+  states.forEach((state) => {
+    state.getIdentifiers().forEach((identifier) => {
+      var _a6, _b;
+      const target = state.getTarget(identifier);
+      if ((_a6 = target === null || target === void 0 ? void 0 : target.node) === null || _a6 === void 0 ? void 0 : _a6.implicit)
+        return;
+      (_b = collisions[identifier]) !== null && _b !== void 0 ? _b : collisions[identifier] = [];
+      collisions[identifier].push(state.filePath);
+    });
+  });
+  Object.entries(collisions).forEach(([identifier, files]) => {
+    if (files.length <= 1)
+      return;
+    addWarningForFile(session, files[0], `Duplicate identifier in project "${identifier}"`, "warn", {
+      note: `In files: ${files.join(", ")}`,
+      ruleId: RuleId.identifierIsUnique
+    });
+  });
+}
+function selectPageReferenceStates(session, pages, opts) {
   const cache = castSession(session);
   const pageReferenceStates = pages.map((page) => {
     const state = cache.$internalReferences[page.file];
@@ -300270,6 +300719,8 @@ function selectPageReferenceStates(session, pages) {
     }
     return void 0;
   }).filter((state) => !!state);
+  if (!(opts === null || opts === void 0 ? void 0 : opts.suppressWarnings))
+    warnOnDuplicateIdentifiers(session, pageReferenceStates);
   return pageReferenceStates;
 }
 async function resolvePageSource(session, file) {
@@ -300349,7 +300800,7 @@ async function processProject(session, siteProject, opts) {
   var _a6;
   const toc = tic();
   const { log } = session;
-  const { imageWriteFolder, imageAltOutputFolder, imageExtensions, extraLinkTransformers, extraTransforms, watchMode, writeToc, writeFiles = true, reloadProject, execute, maxSizeWebp, checkLinks, strict } = opts || {};
+  const { imageWriteFolder, imageAltOutputFolder, imageExtensions, extraLinkTransformers, extraTransforms, watchMode, writeTOC, writeFiles = true, reloadProject, execute, maxSizeWebp, checkLinks, strict } = opts || {};
   if (!siteProject.path) {
     const slugSuffix = siteProject.slug ? `: ${siteProject.slug}` : "";
     log.error(`No local path for site project${slugSuffix}`);
@@ -300358,7 +300809,7 @@ async function processProject(session, siteProject, opts) {
     throw Error("Unable to process project");
   }
   const { project, pages } = await loadProject(session, siteProject.path, {
-    writeToc: writeFiles && writeToc,
+    writeTOC: writeFiles && writeTOC,
     reloadProject
   });
   if (!watchMode) {
@@ -300368,7 +300819,7 @@ async function processProject(session, siteProject, opts) {
       // Load all content (.md and .ipynb)
       ...pages.map((page) => loadFile(session, page.file, siteProject.path, void 0)),
       // Load up all the intersphinx references
-      loadIntersphinx(session, { projectPath: siteProject.path })
+      loadReferences(session, { projectPath: siteProject.path })
     ]);
   }
   combineProjectCitationRenderers(session, siteProject.path);
@@ -300417,7 +300868,7 @@ async function processProject(session, siteProject, opts) {
   return project;
 }
 async function processSite(session, opts) {
-  var _a6, _b, _c;
+  var _a6, _b;
   try {
     reloadAllConfigsForCurrentSite(session);
   } catch (error) {
@@ -300470,20 +300921,17 @@ ${page.file}
   }
   if ((_b = opts === null || opts === void 0 ? void 0 : opts.writeFiles) !== null && _b !== void 0 ? _b : true) {
     await writeSiteManifest(session, opts);
-    const inv = new Inventory({
-      project: siteConfig === null || siteConfig === void 0 ? void 0 : siteConfig.title,
-      // TODO: allow a version on the project?!
-      version: String((_c = siteConfig === null || siteConfig === void 0 ? void 0 : siteConfig.version) !== null && _c !== void 0 ? _c : "1")
-    });
+    const states = [];
     await Promise.all(siteConfig.projects.map(async (project) => {
       if (!project.path)
         return;
-      await addProjectReferencesToObjectsInv(session, inv, {
-        projectPath: project.path
-      });
+      const { pages } = await loadProject(session, project.path);
+      states.push(...selectPageReferenceStates(session, pages, {
+        suppressWarnings: true
+      }));
     }));
-    const filename = (0, import_node_path39.join)(session.sitePath(), "objects.inv");
-    inv.write(filename);
+    await writeObjectsInv(session, states, siteConfig);
+    await writeMystXRefJson(session, states);
   }
   return true;
 }
@@ -300649,6 +301097,7 @@ function getDefaultEnv(template) {
   const env7 = import_nunjucks.default.configure(template.templatePath, {
     trimBlocks: true,
     autoescape: false,
+    // Ensures that we are not writing to HTML!
     tags: {
       blockStart: "[#",
       blockEnd: "#]",
@@ -301024,6 +301473,7 @@ var textOnlyReplacements2 = {
   "\u201C": "``",
   // guillemots
   "\xBB": ">>",
+  // These could be improved
   "\xAB": "<<",
   "\u2026": "\\dots",
   "\u2013": "--",
@@ -301049,9 +301499,13 @@ var arrows = {
 };
 var symbols2 = {
   "\u2212": "-",
+  // minus
   "-": "-",
+  // hyphen minus
   "\uFE63": "-",
+  // Small hyphen minus
   "\uFF0D": "-",
+  // Full-width Hyphen-minus
   "\uFF0B": "+"
   // Full-width Plus
 };
@@ -301776,6 +302230,12 @@ var handlers3 = {
   mystDirective(node3, state) {
     state.renderChildren(node3, false);
   },
+  div(node3, state) {
+    state.renderChildren(node3, false);
+  },
+  span(node3, state) {
+    state.renderChildren(node3, true);
+  },
   comment(node3, state) {
     var _a6, _b;
     state.ensureNewLine();
@@ -302086,7 +302546,7 @@ async function getFileContent(session, files, { projectPath, imageExtensions, ex
       });
     }),
     // Load up all the intersphinx references
-    loadIntersphinx(session, { projectPath })
+    loadReferences(session, { projectPath })
   ]);
   combineProjectCitationRenderers(session, projectPath);
   await Promise.all(allFiles.map(async (file, ind) => {
@@ -302586,9 +303046,13 @@ var arrows2 = {
 };
 var symbols3 = {
   "\u2212": "-",
+  // minus
   "-": "-",
+  // hyphen minus
   "\uFE63": "-",
+  // Small hyphen minus
   "\uFF0D": "-",
+  // Full-width Hyphen-minus
   "\uFF0B": "+"
   // Full-width Plus
 };
@@ -303468,7 +303932,7 @@ ${node3.value}
     state.write(next ? `#[@${id}]` : `@${id}`);
   },
   citeGroup(node3, state) {
-    state.renderChildren(node3, 0, " ");
+    state.renderChildren(node3, 0, { delim: " " });
   },
   cite(node3, state) {
     const needsLabel = !/^[a-zA-Z0-9_\-:.]+$/.test(node3.label);
@@ -303502,7 +303966,7 @@ ${node3.value}
     state.write("]");
   },
   footnoteDefinition() {
-  }
+  },
   // si(node, state) {
   //   // state.useMacro('siunitx');
   //   if (node.number == null) {
@@ -303513,6 +303977,12 @@ ${node3.value}
   //     );
   //   }
   // },
+  div(node3, state) {
+    state.renderChildren(node3, 1);
+  },
+  span(node3, state) {
+    state.renderChildren(node3, 0, { trimEnd: false });
+  }
 };
 var TypstSerializer = class {
   constructor(file, tree, opts) {
@@ -303554,7 +304024,7 @@ var TypstSerializer = class {
       return;
     this.addNewLine();
   }
-  renderChildren(node3, trailingNewLines = 0, delim = "") {
+  renderChildren(node3, trailingNewLines = 0, { delim = "", trimEnd: trimEnd2 = true } = {}) {
     var _a6, _b, _c;
     const numChildren = (_b = (_a6 = node3.children) === null || _a6 === void 0 ? void 0 : _a6.length) !== null && _b !== void 0 ? _b : 0;
     (_c = node3.children) === null || _c === void 0 ? void 0 : _c.forEach((child, index4) => {
@@ -303572,7 +304042,8 @@ var TypstSerializer = class {
       if (delim && index4 + 1 < numChildren)
         this.write(delim);
     });
-    this.trimEnd();
+    if (trimEnd2)
+      this.trimEnd();
     for (let i2 = trailingNewLines; i2--; )
       this.addNewLine();
   }
@@ -307014,6 +307485,7 @@ var JatsDocument = class {
       "xmlns:xlink": "http://www.w3.org/1999/xlink",
       "xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
       "xmlns:ali": "http://www.niso.org/schemas/ali/1.0/",
+      // Used for the licensing
       "dtd-version": "1.3",
       "xml:lang": "en"
     };
@@ -307693,7 +308165,7 @@ To resolve this, run: myst build --all`, {
     if (import_node_fs38.default.existsSync(import_node_path51.default.join(projectPath, "_toc.yml"))) {
       copyFileToFolder(session, import_node_path51.default.join(projectPath, "_toc.yml"), bundle, fileCopyErrorLogFn);
     } else {
-      writeTocFromProject(project, bundle);
+      writeTOCFromProject(project, bundle);
     }
     addManifestItem(manifestItems, "article-source", mecaFolder, import_node_path51.default.join(bundle, "_toc.yml"));
     const projectPages = [
@@ -312573,6 +313045,7 @@ async function startContentServer(session, opts) {
   app.use("/content", import_express.default.static(session.contentPath()));
   app.use("/config.json", import_express.default.static((0, import_node_path55.join)(session.sitePath(), "config.json")));
   app.use("/objects.inv", import_express.default.static((0, import_node_path55.join)(session.sitePath(), "objects.inv")));
+  app.use("/myst.xref.json", import_express.default.static((0, import_node_path55.join)(session.sitePath(), "myst.xref.json")));
   const server = app.listen(port, () => {
     session.log.debug(`Content server listening on port ${port}`);
   });
@@ -312685,9 +313158,10 @@ async function currentSiteRoutes(session, host, baseurl, opts) {
     var _a7, _b2;
     const projSlug = proj.slug ? `/${proj.slug}` : "";
     const siteIndex = baseurl ? `/${proj.index}` : "";
+    const pages = proj.pages.filter((page) => !!page.slug);
     return [
       { url: `${host}${projSlug}${siteIndex}`, path: import_node_path56.default.join((_a7 = proj.slug) !== null && _a7 !== void 0 ? _a7 : "", "index.html") },
-      ...proj.pages.map((page) => {
+      ...pages.map((page) => {
         var _a8;
         return {
           url: `${host}${projSlug}/${page.slug}`,
@@ -312699,7 +313173,7 @@ async function currentSiteRoutes(session, host, baseurl, opts) {
         url: `${host}${projSlug}/${proj.index}.json`,
         path: import_node_path56.default.join((_b2 = proj.slug) !== null && _b2 !== void 0 ? _b2 : "", `${proj.index}.json`)
       },
-      ...proj.pages.map((page) => {
+      ...pages.map((page) => {
         var _a8;
         return {
           url: `${host}${projSlug}/${page.slug}.json`,
@@ -312707,7 +313181,7 @@ async function currentSiteRoutes(session, host, baseurl, opts) {
         };
       }),
       // Download other assets
-      ...["favicon.ico", "robots.txt"].map((asset) => ({
+      ...["favicon.ico", "robots.txt", "myst-theme.css"].map((asset) => ({
         url: `${host}/${asset}`,
         path: asset
       }))
@@ -312761,6 +313235,10 @@ async function buildHtml(session, opts) {
   const routes = await currentSiteRoutes(session, host, baseurl, opts);
   await Promise.all(routes.map(async (page) => {
     const resp = await session.fetch(page.url);
+    if (!resp.ok) {
+      session.log.error(`Error fetching ${page.url}`);
+      return;
+    }
     const content3 = await resp.text();
     writeFileToFolder(import_node_path56.default.join(htmlDir, page.path), content3);
   }));
@@ -312768,8 +313246,9 @@ async function buildHtml(session, opts) {
   const templateBuildDir = import_node_path56.default.join(template.templatePath, "public");
   import_fs_extra.default.copySync(templateBuildDir, htmlDir);
   import_fs_extra.default.copySync(session.publicPath(), import_node_path56.default.join(htmlDir, "build"));
-  import_fs_extra.default.copySync(import_node_path56.default.join(session.sitePath(), "objects.inv"), import_node_path56.default.join(htmlDir, "objects.inv"));
   import_fs_extra.default.copySync(import_node_path56.default.join(session.sitePath(), "config.json"), import_node_path56.default.join(htmlDir, "config.json"));
+  import_fs_extra.default.copySync(import_node_path56.default.join(session.sitePath(), "objects.inv"), import_node_path56.default.join(htmlDir, "objects.inv"));
+  import_fs_extra.default.copySync(import_node_path56.default.join(session.sitePath(), "myst.xref.json"), import_node_path56.default.join(htmlDir, "myst.xref.json"));
   rewriteAssetsFolder(htmlDir, baseurl);
   process.exit(0);
 }
@@ -315740,12 +316219,12 @@ Learn more about this CLI and MyST Markdown at: ${source_default.bold("https://m
 
 `;
 async function init2(session, opts) {
-  const { project, site, writeToc, ghPages, ghCurvenote } = opts;
+  const { project, site, writeTOC, ghPages, ghCurvenote } = opts;
   if (ghPages)
     return githubPagesAction(session);
   if (ghCurvenote)
     return githubCurvenoteAction(session);
-  if (!project && !site && !writeToc) {
+  if (!project && !site && !writeTOC) {
     session.log.info(WELCOME());
   }
   loadConfig(session, ".");
@@ -315793,11 +316272,11 @@ async function init2(session, opts) {
     session.log.info(`\u{1F4BE} Writing new ${configDoc} config file: ${source_default.blue(import_node_path60.default.resolve(configFile))}`);
     import_node_fs41.default.writeFileSync(configFile, configData2);
   }
-  if (writeToc) {
+  if (writeTOC) {
     loadConfig(session, ".");
-    await loadProjectFromDisk(session, ".", { writeToc });
+    await loadProjectFromDisk(session, ".", { writeTOC });
   }
-  if (writeToc || project || site)
+  if (writeTOC || project || site)
     return;
   session.log.info("");
   const promptStart = await inquirer_default.prompt([
@@ -323281,11 +323760,11 @@ var source_default8 = chalk6;
 function makeProjectOption(description) {
   return new Option("--project", description).default(false);
 }
-function makeWriteTocOption() {
+function makeWriteTOCOption() {
   return new Option(
     "--write-toc",
     "Generate editable _toc.yml file for project if it does not exist"
-  ).default(false);
+  ).default(false).implies({ writeTOC: true });
 }
 function makeGithubPagesOption() {
   return new Option(
@@ -323302,7 +323781,7 @@ function makeGithubCurvenoteOption() {
 
 // src/init.ts
 function makeInitCLI(program3) {
-  const command = new Command("init").description("Initialize a MyST project in the current directory").addOption(makeProjectOption("Initialize config for MyST project content")).addOption(makeSiteOption("Initialize config for MyST site")).addOption(makeWriteTocOption()).addOption(makeGithubPagesOption()).addOption(makeGithubCurvenoteOption()).action(clirun2(Session, init2, program3));
+  const command = new Command("init").description("Initialize a MyST project in the current directory").addOption(makeProjectOption("Initialize config for MyST project content")).addOption(makeSiteOption("Initialize config for MyST site")).addOption(makeWriteTOCOption()).addOption(makeGithubPagesOption()).addOption(makeGithubCurvenoteOption()).action(clirun2(Session, init2, program3));
   return command;
 }
 function addDefaultCommand(program3) {