🪄 Updates for multi-article typst export with interactive figures

.changeset/fifty-cougars-invent.md

@@ -0,0 +1,5 @@
+---
+'myst-to-typst': patch
+---
+
+Support additional greek characters in typst

.changeset/kind-lies-kick.md

@@ -0,0 +1,7 @@
+---
+'myst-directives': patch
+'myst-transforms': patch
+'myst-cli': patch
+---
+
+Add static figure placeholder for images that should be used only for PDF exports

.changeset/large-countries-cheer.md

@@ -0,0 +1,5 @@
+---
+'myst-cli': patch
+---
+
+Prevent html outputs that translate to empty images

.changeset/nasty-pets-smell.md

@@ -0,0 +1,5 @@
+---
+'myst-to-typst': patch
+---
+
+Support restarting counter for each typst article in multi-article export

.changeset/new-birds-bake.md

@@ -0,0 +1,5 @@
+---
+'myst-to-typst': patch
+---
+
+Fix typst crossreferences to other pages

.changeset/rare-months-rest.md

@@ -0,0 +1,5 @@
+---
+'myst-cli': patch
+---
+
+Prioritize project-level parts for project-level typst export

packages/myst-cli/src/build/typst.ts

@@ -267,6 +267,31 @@ export async function localArticleToTypstTemplated(
     macros: [],
     commands: {},
   };
+  const state = session.store.getState();
+  const projectFrontmatter = selectors.selectLocalProjectConfig(state, projectPath ?? '.') ?? {};
+  if (file === selectors.selectCurrentProjectFile(state)) {
+    // If export is defined at the project level, prioritize project parts over page parts
+    partDefinitions.forEach((def) => {
+      const part = extractTypstPart(
+        session,
+        { type: 'root', children: [] },
+        {},
+        def,
+        projectFrontmatter,
+        templateYml,
+      );
+      if (Array.isArray(part)) {
+        // This is the case if def.as_list is true
+        part.forEach((item) => {
+          collected = mergeTypstTemplateImports(collected, item);
+        });
+        parts[def.id] = part.map(({ value }) => value);
+      } else if (part != null) {
+        collected = mergeTypstTemplateImports(collected, part);
+        parts[def.id] = part?.value ?? '';
+      }
+    });
+  }
   const hasGlossaries = false;
   const results = await Promise.all(
     content.map(async ({ mdast, frontmatter, references }, ind) => {
@@ -311,8 +336,7 @@ export async function localArticleToTypstTemplated(
     frontmatter = content[0].frontmatter;
     typstContent = results[0].value;
   } else {
-    const state = session.store.getState();
-    frontmatter = selectors.selectLocalProjectConfig(state, projectPath ?? '.') ?? {};
+    frontmatter = projectFrontmatter;
     const { dir, name, ext } = path.parse(output);
     typstContent = '';
     let fileInd = 0;

packages/myst-cli/src/process/mdast.ts

@@ -68,6 +68,8 @@ import {
   transformFilterOutputStreams,
   transformLiftCodeBlocksInJupytext,
   transformMystXRefs,
+  removeStaticImages,
+  removeNonStaticImages,
 } from '../transforms/index.js';
 import type { ImageExtensions } from '../utils/resolveExtension.js';
 import { logMessagesFromVFile } from '../utils/logging.js';
@@ -379,10 +381,13 @@ export async function finalizeMdast(
   const vfile = new VFile(); // Collect errors on this file
   vfile.path = file;
   if (simplifyFigures) {
+    removeNonStaticImages(mdast);
     // Transform output nodes to images / text
     reduceOutputs(session, mdast, file, imageWriteFolder, {
       altOutputFolder: simplifyFigures ? undefined : imageAltOutputFolder,
     });
+  } else {
+    removeStaticImages(mdast);
   }
   transformOutputsToFile(session, mdast, imageWriteFolder, {
     altOutputFolder: simplifyFigures ? undefined : imageAltOutputFolder,

packages/myst-cli/src/transforms/images.ts

@@ -746,6 +746,45 @@ export function transformPlaceholderImages(
   remove(mdast, '__remove__');
 }
 
+/**
+ * Remove all static images
+ *
+ * This should only be run for web builds
+ */
+export function removeStaticImages(mdast: GenericParent) {
+  selectAll('image', mdast)
+    .filter((image: GenericNode) => image.static)
+    .forEach((image: GenericNode) => {
+      image.type = '__remove__';
+    });
+  remove(mdast, '__remove__');
+}
+
+/**
+ * Remove all figure content except static/placeholder, where present
+ *
+ * This should only be run for static builds
+ */
+export function removeNonStaticImages(mdast: GenericParent) {
+  const containers = selectAll('container', mdast);
+  containers.forEach((container: GenericNode) => {
+    const hasStatic = !!container.children?.find((child) => child.static);
+    const hasPlaceholder = !!container.children?.find((child) => child.placeholder);
+    if (!hasStatic && !hasPlaceholder) return;
+    container.children = container.children?.filter((child) => {
+      if (['caption', 'legend'].includes(child.type)) {
+        // Always keep caption/legend
+        return true;
+      }
+      if (hasStatic) {
+        // Prioritize static image over placeholder
+        return !!child.static;
+      }
+      return !!child.placeholder;
+    });
+  });
+}
+
 /**
  * Trim base64 values for urlSource when they have been replaced by image urls
  */

packages/myst-cli/src/transforms/outputs.ts

@@ -279,6 +279,9 @@ export function reduceOutputs(
             ],
           };
           htmlTransform(htmlTree);
+          if ((selectAll('image', htmlTree) as GenericNode[]).find((htmlImage) => !htmlImage.url)) {
+            return undefined;
+          }
           return htmlTree.children;
         } else if (content_type.startsWith('image/')) {
           const path = writeCachedOutputToFile(session, hash, cache.$outputs[hash], writeFolder, {

packages/myst-directives/src/figure.ts

@@ -56,6 +56,10 @@ export const figureDirective: DirectiveSpec = {
       type: String,
       doc: 'A placeholder image when using a notebook cell as the figure contents. This will be shown in place of the Jupyter output until an execution environment is attached. It will also be used in static outputs, such as a PDF output.',
     },
+    static: {
+      type: String,
+      doc: 'An image only used in static outputs. This image will always take priority for static outputs, such as PDFs, and will never be used in dynamic outputs, such as web builds.',
+    },
     'no-subfigures': {
       type: Boolean,
       doc: 'Disallow implicit subfigure creation from child nodes',
@@ -96,6 +100,17 @@ export const figureDirective: DirectiveSpec = {
         align: data.options?.align as Image['align'],
       });
     }
+    if (data.options?.static) {
+      children.push({
+        type: 'image',
+        static: true,
+        url: data.options.static as string,
+        alt: data.options?.alt as string,
+        width: data.options?.width as string,
+        height: data.options?.height as string,
+        align: data.options?.align as Image['align'],
+      });
+    }
     if (data.body) {
       children.push(...(data.body as GenericNode[]));
     }

packages/myst-to-typst/src/container.ts

@@ -104,6 +104,11 @@ export const containerHandler: Handler = (node, state) => {
     return;
   }
 
+  if (node.enumerator?.endsWith('.1')) {
+    state.write(`#set figure(numbering: "${node.enumerator}")\n`);
+    state.write(`#counter(figure.where(kind: "${kind}")).update(0)\n\n`);
+  }
+
   if (nonCaptions && nonCaptions.length > 1) {
     const allSubFigs =
       nonCaptions.filter((item: GenericNode) => item.type === 'container').length ===

packages/myst-to-typst/src/index.ts

@@ -363,10 +363,10 @@ const handlers: Record<string, Handler> = {
   legend: captionHandler,
   captionNumber: () => undefined,
   crossReference(node: CrossReference, state, parent) {
-    if (node.remote) {
+    if (node.remoteBaseUrl) {
       // We don't want to handle remote references, treat them as links
       const url =
-        (node.remoteBaseUrl ?? '') +
+        node.remoteBaseUrl +
         (node.url === '/' ? '' : node.url ?? '') +
         (node.html_id ? `#${node.html_id}` : '');
       linkHandler({ ...node, url: url }, state);

packages/myst-to-typst/src/math.ts

@@ -67,6 +67,10 @@ const math: Handler = (node, state) => {
   const { identifier: label } = normalizeLabel(node.label) ?? {};
   addMacrosToState(value, state);
   state.ensureNewLine();
+  if (node.enumerator?.endsWith('.1')) {
+    state.write(`#set math.equation(numbering: "(${node.enumerator})")\n`);
+    state.write(`#counter(math.equation).update(0)\n\n`);
+  }
   // Note: must have spaces $ math $ for the block!
   state.write(`$ ${value} $${label ? ` <${label}>` : ''}\n\n`);
   state.ensureNewLine(true);

packages/myst-to-typst/src/utils.ts

@@ -49,8 +49,8 @@ const textOnlyReplacements: Record<string, string> = {
   '©': '#emoji.copyright ',
   '®': '#emoji.reg ',
   '™': '#emoji.tm ',
-  '<': '\\< ',
-  '>': '\\> ',
+  '<': '\\<',
+  '>': '\\>',
   ' ': '~',
   ' ': '~',
   // eslint-disable-next-line no-irregular-whitespace
@@ -105,16 +105,19 @@ const mathReplacements: Record<string, string> = {
   '×': 'times',
   Α: 'A',
   α: 'alpha',
+  𝜶: 'alpha',
   Β: 'B',
   β: 'beta',
   ß: 'beta',
+  𝜷: 'beta',
   Γ: 'Gamma',
   γ: 'gamma',
   Δ: 'Delta',
   '∆': 'Delta',
   δ: 'delta',
   Ε: 'E',
   ε: 'epsilon',
+  𝝴: 'epsilon',
   Ζ: 'Z',
   ζ: 'zeta',
   Η: 'H',

packages/myst-transforms/src/containers.ts

@@ -44,6 +44,10 @@ function isPlaceholder(node: GenericNode) {
   return node.type === 'image' && node.placeholder;
 }
 
+function isStatic(node: GenericNode) {
+  return node.type === 'image' && node.static;
+}
+
 /** Nest node inside container */
 function createSubfigure(node: GenericNode, parent: GenericParent): GenericParent {
   const children = node.type === 'container' && node.children ? node.children : [node];
@@ -130,6 +134,7 @@ export function containerChildrenTransform(tree: GenericParent, vfile: VFile) {
     hoistContentOutOfParagraphs(container);
     let subfigures: GenericNode[] = [];
     let placeholderImage: GenericNode | undefined;
+    let staticImage: GenericNode | undefined;
     let caption: GenericNode | undefined;
     let legend: GenericNode | undefined;
     const otherNodes: GenericNode[] = [];
@@ -161,6 +166,15 @@ export function containerChildrenTransform(tree: GenericParent, vfile: VFile) {
         } else {
           placeholderImage = child;
         }
+      } else if (isStatic(child)) {
+        if (staticImage) {
+          fileError(vfile, 'container has multiple static images', {
+            node: container,
+            ruleId: RuleId.containerChildrenValid,
+          });
+        } else {
+          staticImage = child;
+        }
       } else if (SUBFIGURE_TYPES.includes(child.type)) {
         subfigures.push(child);
       } else {
@@ -186,6 +200,7 @@ export function containerChildrenTransform(tree: GenericParent, vfile: VFile) {
         caption ? 'caption' : undefined,
         legend ? 'legend' : undefined,
         placeholderImage ? 'placeholder image' : undefined,
+        staticImage ? 'static image' : undefined,
       ]
         .filter(Boolean)
         .join(', ');
@@ -206,6 +221,7 @@ export function containerChildrenTransform(tree: GenericParent, vfile: VFile) {
     }
     const children: GenericNode[] = [...subfigures];
     if (placeholderImage) children.push(placeholderImage);
+    if (staticImage) children.push(staticImage);
     // Caption is above tables and below all other figures
     if (container.kind === 'table') {
       if (caption) children.unshift(caption);