🧜‍♀️ Create images of mermaid diagrams for static exports

.changeset/cool-pigs-deny.md

@@ -0,0 +1,5 @@
+---
+'myst-common': patch
+---
+
+Added `options?: PluginOptions` to `TransformSpec` type. Enables passing configuration options to transform plugins.

.changeset/orange-rockets-relate.md

@@ -0,0 +1,8 @@
+---
+'myst-cli': patch
+---
+
+Integrated transform loading from options with proper plugin utilities.
+
+Added mermaid transform import and configuration
+Integrated mermaid transform into Typst build pipeline.

.changeset/stale-ghosts-drum.md

@@ -0,0 +1,5 @@
+---
+'myst-spec-ext': patch
+---
+
+Added `label`, `identifier`, and `html_id` to `Image` type

docs/diagrams.md

@@ -24,3 +24,32 @@ flowchart LR
 :::{note}
 Both GitHub and JupyterLab ([#101](https://github.com/jupyter/enhancement-proposals/pull/101)) support the translation of a code-block ` ```mermaid ` to a mermaid diagram directly, this can also be used by default in MyST.
 :::
+
+## Rendering for Static Exports
+
+MyST supports static rendering of Mermaid diagrams for static export formats (PDF, Word, LaTeX, Typst). This feature converts Mermaid syntax to base64-encoded SVG or PNG images during the build process, ensuring consistent rendering across all static output formats.
+
+:::{important} Prerequisites
+To use static Mermaid rendering, you need the Mermaid CLI installed:
+
+```bash
+npm install -g @mermaid-js/mermaid-cli
+```
+
+:::
+
+:::{note .dropdown} For CI Environments
+
+The Mermaid CLI uses Puppeteer which may require special configuration in CI environments. MyST automatically handles this by detecting the `CI` environment variable or you can manually control it:
+
+```bash
+# Automatic detection (recommended for CI)
+CI=true npm run build
+
+# Manual control
+MERMAID_NO_SANDBOX=true npm run build
+```
+
+This automatically creates a Puppeteer configuration file with `--no-sandbox` flag to resolve sandbox issues in Linux CI environments.
+
+:::

packages/jtex/tests/download.spec.ts

@@ -4,57 +4,53 @@ import { TemplateKind } from 'myst-common';
 import MystTemplate, { downloadTemplate, resolveInputs, Session } from 'myst-templates';
 import { renderTemplate } from '../src';
 
-describe(
-  'Download Template',
-  () => {
-    it('Download default template', async () => {
-      const session = new Session();
-      const inputs = resolveInputs(session, { buildDir: '_build', kind: TemplateKind.tex });
-      await downloadTemplate(session, {
-        templatePath: inputs.templatePath,
-        templateUrl: inputs.templateUrl as string,
-      });
-      expect(fs.existsSync('_build/templates/tex/myst/plain_latex/template.zip')).toBe(true);
-      expect(fs.existsSync('_build/templates/tex/myst/plain_latex/template.yml')).toBe(true);
-      expect(fs.existsSync('_build/templates/tex/myst/plain_latex/template.tex')).toBe(true);
+describe('Download Template', { timeout: 15000 }, () => {
+  it('Download default template', async () => {
+    const session = new Session();
+    const inputs = resolveInputs(session, { buildDir: '_build', kind: TemplateKind.tex });
+    await downloadTemplate(session, {
+      templatePath: inputs.templatePath,
+      templateUrl: inputs.templateUrl as string,
     });
-    it('Bad template paths to throw', async () => {
-      const jtex = new MystTemplate(new Session(), {
-        template: 'not-there',
-        kind: TemplateKind.tex,
-      });
-      expect(() => jtex.prepare({} as any)).toThrow(/does not exist/);
+    expect(fs.existsSync('_build/templates/tex/myst/plain_latex/template.zip')).toBe(true);
+    expect(fs.existsSync('_build/templates/tex/myst/plain_latex/template.yml')).toBe(true);
+    expect(fs.existsSync('_build/templates/tex/myst/plain_latex/template.tex')).toBe(true);
+  });
+  it('Bad template paths to throw', async () => {
+    const jtex = new MystTemplate(new Session(), {
+      template: 'not-there',
+      kind: TemplateKind.tex,
     });
-    it('Render out the template', async () => {
-      const jtex = new MystTemplate(new Session(), {
-        kind: TemplateKind.tex,
-        template: `${__dirname}/example`,
-      });
-      renderTemplate(jtex, {
-        contentOrPath: `${__dirname}/test.tex`,
-        outputPath: '_build/out/article.tex',
-        frontmatter: {
-          title: 'test',
-          description: 'test',
-          date: new Date(2022, 6, 22).toISOString(),
-          authors: [
-            { name: 'Rowan Cockett', affiliations: ['Curvenote'] },
-            { name: 'Steve Purves', affiliations: ['Curvenote'], orcid: '0000' },
-          ],
-        },
-        options: {
-          keywords: '',
-        },
-        parts: {
-          abstract: 'My abstract!',
-        },
-      });
-      expect(fs.existsSync('_build/out/article.tex')).toBe(true);
-      const content = fs.readFileSync('_build/out/article.tex').toString();
-      expect(content.includes('Volcanic Archipelago')).toBe(true);
-      expect(content.includes('Rowan Cockett')).toBe(true);
-      expect(content.includes('My abstract!')).toBe(true);
+    expect(() => jtex.prepare({} as any)).toThrow(/does not exist/);
+  });
+  it('Render out the template', async () => {
+    const jtex = new MystTemplate(new Session(), {
+      kind: TemplateKind.tex,
+      template: `${__dirname}/example`,
     });
-  },
-  { timeout: 15000 },
-);
+    renderTemplate(jtex, {
+      contentOrPath: `${__dirname}/test.tex`,
+      outputPath: '_build/out/article.tex',
+      frontmatter: {
+        title: 'test',
+        description: 'test',
+        date: new Date(2022, 6, 22).toISOString(),
+        authors: [
+          { name: 'Rowan Cockett', affiliations: ['Curvenote'] },
+          { name: 'Steve Purves', affiliations: ['Curvenote'], orcid: '0000' },
+        ],
+      },
+      options: {
+        keywords: '',
+      },
+      parts: {
+        abstract: 'My abstract!',
+      },
+    });
+    expect(fs.existsSync('_build/out/article.tex')).toBe(true);
+    const content = fs.readFileSync('_build/out/article.tex').toString();
+    expect(content.includes('Volcanic Archipelago')).toBe(true);
+    expect(content.includes('Rowan Cockett')).toBe(true);
+    expect(content.includes('My abstract!')).toBe(true);
+  });
+});

packages/myst-cli/package.json

@@ -43,6 +43,7 @@
   },
   "dependencies": {
     "@jupyterlab/services": "^7.3.0",
+    "@mermaid-js/mermaid-cli": "^10.9.1",
     "@reduxjs/toolkit": "^2.1.0",
     "adm-zip": "^0.5.10",
     "boxen": "^7.1.1",

packages/myst-cli/src/build/docx/single.ts

@@ -28,6 +28,7 @@ import { cleanOutput } from '../utils/cleanOutput.js';
 import { getFileContent } from '../utils/getFileContent.js';
 import { createFooter } from './footers.js';
 import { createArticleTitle, createReferenceTitle } from './titles.js';
+import { createMermaidImageMystPlugin } from '../../transforms/mermaid.js';
 
 const DOCX_IMAGE_EXTENSIONS = [ImageExtensions.png, ImageExtensions.jpg, ImageExtensions.jpeg];
 
@@ -98,6 +99,7 @@ export async function runWordExport(
     projectPath,
     imageExtensions: DOCX_IMAGE_EXTENSIONS,
     extraLinkTransformers,
+    transforms: [createMermaidImageMystPlugin],
     preFrontmatters: [
       filterKeys(article, [...PAGE_FRONTMATTER_KEYS, ...Object.keys(FRONTMATTER_ALIASES)]),
     ],

packages/myst-cli/src/build/jats/single.ts

@@ -14,6 +14,7 @@ import { resolveFrontmatterParts } from '../../utils/resolveFrontmatterParts.js'
 import type { ExportWithOutput, ExportFnOptions } from '../types.js';
 import { cleanOutput } from '../utils/cleanOutput.js';
 import { getFileContent } from '../utils/getFileContent.js';
+import { createMermaidImageMystPlugin } from '../../transforms/mermaid.js';
 
 /**
  * Build a MyST project as JATS XML
@@ -39,6 +40,7 @@ export async function runJatsExport(
       projectPath,
       imageExtensions: KNOWN_IMAGE_EXTENSIONS,
       extraLinkTransformers,
+      transforms: [createMermaidImageMystPlugin],
       preFrontmatters: [
         filterKeys(article, [...PAGE_FRONTMATTER_KEYS, ...Object.keys(FRONTMATTER_ALIASES)]),
       ], // only apply to article, not sub_articles

packages/myst-cli/src/build/tex/single.ts

@@ -34,6 +34,7 @@ import { createTempFolder } from '../../utils/createTempFolder.js';
 import { resolveFrontmatterParts } from '../../utils/resolveFrontmatterParts.js';
 import type { ExportWithOutput, ExportResults, ExportFnOptions } from '../types.js';
 import { writeBibtexFromCitationRenderers } from '../utils/bibtex.js';
+import { createMermaidImageMystPlugin } from '../../transforms/mermaid.js';
 
 export const DEFAULT_BIB_FILENAME = 'main.bib';
 const TEX_IMAGE_EXTENSIONS = [
@@ -140,6 +141,7 @@ export async function localArticleToTexRaw(
       projectPath,
       imageExtensions: TEX_IMAGE_EXTENSIONS,
       extraLinkTransformers,
+      transforms: [createMermaidImageMystPlugin],
       titleDepths: fileArticles.map((article) => article.level),
       preFrontmatters: fileArticles.map((article) =>
         filterKeys(article, [...PAGE_FRONTMATTER_KEYS, ...Object.keys(FRONTMATTER_ALIASES)]),
@@ -206,6 +208,7 @@ export async function localArticleToTexTemplated(
       projectPath,
       imageExtensions: TEX_IMAGE_EXTENSIONS,
       extraLinkTransformers,
+      transforms: [createMermaidImageMystPlugin],
       titleDepths: fileArticles.map((article) => article.level),
       preFrontmatters: fileArticles.map((article) =>
         filterKeys(article, [...PAGE_FRONTMATTER_KEYS, ...Object.keys(FRONTMATTER_ALIASES)]),

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

@@ -37,6 +37,7 @@ import version from '../version.js';
 import { cleanOutput } from './utils/cleanOutput.js';
 import type { ExportWithOutput, ExportResults, ExportFnOptions } from './types.js';
 import { writeBibtexFromCitationRenderers } from './utils/bibtex.js';
+import { createMermaidImageMystPlugin } from '../transforms/mermaid.js';
 
 export const DEFAULT_BIB_FILENAME = 'main.bib';
 const TYPST_IMAGE_EXTENSIONS = [
@@ -158,6 +159,7 @@ export async function localArticleToTypstRaw(
       projectPath,
       imageExtensions: TYPST_IMAGE_EXTENSIONS,
       extraLinkTransformers,
+      transforms: [createMermaidImageMystPlugin],
       titleDepths: fileArticles.map((article) => article.level),
       preFrontmatters: fileArticles.map((article) =>
         filterKeys(article, [...PAGE_FRONTMATTER_KEYS, ...Object.keys(FRONTMATTER_ALIASES)]),
@@ -229,6 +231,7 @@ export async function localArticleToTypstTemplated(
       projectPath,
       imageExtensions: TYPST_IMAGE_EXTENSIONS,
       extraLinkTransformers,
+      transforms: [createMermaidImageMystPlugin],
       titleDepths: fileArticles.map((article) => article.level),
       preFrontmatters: fileArticles.map((article) =>
         filterKeys(article, [...PAGE_FRONTMATTER_KEYS, ...Object.keys(FRONTMATTER_ALIASES)]),

packages/myst-cli/src/build/utils/getFileContent.ts

@@ -1,4 +1,5 @@
 import { resolve } from 'node:path';
+import type { TransformSpec } from 'myst-common';
 import { plural } from 'myst-common';
 import { tic } from 'myst-cli-utils';
 import type { LinkTransformer } from 'myst-transforms';
@@ -19,6 +20,7 @@ export async function getFileContent(
     projectPath,
     imageExtensions,
     extraLinkTransformers,
+    transforms,
     extraTransforms,
     titleDepths,
     preFrontmatters,
@@ -27,6 +29,8 @@ export async function getFileContent(
     projectPath?: string;
     imageExtensions: ImageExtensions[];
     extraLinkTransformers?: LinkTransformer[];
+    transforms?: TransformSpec[];
+    /** @deprecated use transforms instead */
     extraTransforms?: TransformFn[];
     titleDepths?: number | (number | undefined)[];
     preFrontmatters?: Record<string, any> | (Record<string, any> | undefined)[];
@@ -72,6 +76,7 @@ export async function getFileContent(
         minifyMaxCharacters: 0,
         index: project.index,
         titleDepth,
+        transforms,
         extraTransforms,
         execute,
       });

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

@@ -1,6 +1,12 @@
 import path from 'node:path';
 import { tic } from 'myst-cli-utils';
-import type { GenericParent, IExpressionResult, PluginUtils, References } from 'myst-common';
+import type {
+  GenericParent,
+  IExpressionResult,
+  PluginUtils,
+  References,
+  TransformSpec,
+} from 'myst-common';
 import { fileError, fileWarn, RuleId, slugToUrl } from 'myst-common';
 import type { PageFrontmatter } from 'myst-frontmatter';
 import { SourceFileKind } from 'myst-spec-ext';
@@ -112,6 +118,8 @@ export async function transformMdast(
     imageExtensions?: ImageExtensions[];
     watchMode?: boolean;
     execute?: boolean;
+    transforms?: TransformSpec[];
+    /** @deprecated Use `session.plugins?.transforms` instead */
     extraTransforms?: TransformFn[];
     minifyMaxCharacters?: number;
     index?: string;
@@ -125,6 +133,7 @@ export async function transformMdast(
     pageSlug,
     projectSlug,
     imageExtensions,
+    transforms,
     extraTransforms,
     watchMode = false,
     minifyMaxCharacters,
@@ -204,10 +213,15 @@ export async function transformMdast(
     })
     .use(inlineMathSimplificationPlugin, { replaceSymbol: false })
     .use(mathPlugin, { macros: frontmatter.math });
+  // Load transform functions from options (we always run all of them)
+  transforms?.forEach((t) => {
+    pipe.use(t.plugin, t.options, pluginUtils);
+  });
+
   // Load custom transform plugins
   session.plugins?.transforms.forEach((t) => {
     if (t.stage !== 'document') return;
-    pipe.use(t.plugin, undefined, pluginUtils);
+    pipe.use(t.plugin, t.options, pluginUtils);
   });
 
   pipe
@@ -361,7 +375,7 @@ export async function postProcessMdast(
   const pipe = unified();
   session.plugins?.transforms.forEach((t) => {
     if (t.stage !== 'project') return;
-    pipe.use(t.plugin, undefined, pluginUtils);
+    pipe.use(t.plugin, t.options, pluginUtils);
   });
   await pipe.run(mdast, vfile);
 

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

@@ -10,4 +10,5 @@ export * from './links.js';
 export * from './mdast.js';
 export * from './outputs.js';
 export * from './inlineExpressions.js';
+export * from './mermaid.js';
 export * from './types.js';