Update docs

chore(deps): update all patch dependencies (patch)

cypress/helpers/util.ts

@@ -55,6 +55,7 @@ export const imgSnapshotTest = (
   const options: CypressMermaidConfig = {
     ..._options,
     fontFamily: _options.fontFamily || 'courier',
+    // @ts-ignore TODO: Fix type of fontSize
     fontSize: _options.fontSize || '16px',
     sequence: {
       ...(_options.sequence || {}),

docs/config/math.md

@@ -84,3 +84,13 @@ Example with legacy mode enabled (the latest version of KaTeX's stylesheet can b
   </body>
 </html>
 ```
+
+## Handling Rendering Differences
+
+Due to differences between default fonts across operating systems and browser's MathML implementations, inconsistent results can be seen across platforms. If having consistent results are important, or the most optimal rendered results are desired, `forceLegacyMathML` can be enabled in the config.
+
+This option will always use KaTeX's stylesheet instead of only when MathML is not supported (as with `legacyMathML`). Note that only `forceLegacyMathML` needs to be set.
+
+If including KaTeX's stylesheet is not a concern, enabling this option is recommended to avoid scenarios where no MathML implementation within a browser provides the desired output (as seen below).
+
+![Image showing differences between Browsers](img/mathMLDifferences.png)

docs/ecosystem/integrations-community.md

@@ -240,6 +240,8 @@ Communication tools and platforms
 
 ### Other
 
+- [Astro](https://astro.build/)
+  - [Adding diagrams to your Astro site with MermaidJS and Playwright](https://agramont.net/blog/diagraming-with-mermaidjs-astro/)
 - [Bisheng](https://www.npmjs.com/package/bisheng)
   - [bisheng-plugin-mermaid](https://github.com/yct21/bisheng-plugin-mermaid)
 - [Blazorade Mermaid: Render Mermaid diagrams in Blazor applications](https://github.com/Blazorade/Blazorade-Mermaid/wiki)
@@ -249,6 +251,7 @@ Communication tools and platforms
 - [Jekyll](https://jekyllrb.com/)
   - [jekyll-mermaid](https://rubygems.org/gems/jekyll-mermaid)
   - [jekyll-mermaid-diagrams](https://github.com/fuzhibo/jekyll-mermaid-diagrams)
+- [MarkChart: Preview Mermaid diagrams on macOS](https://markchart.app/)
 - [mermaid-isomorphic](https://github.com/remcohaszing/mermaid-isomorphic)
 - [mermaid-server: Generate diagrams using a HTTP request](https://github.com/TomWright/mermaid-server)
 - [NiceGUI: Let any browser be the frontend of your Python code](https://nicegui.io) ✅

packages/mermaid/src/config.type.ts

@@ -120,6 +120,13 @@ export interface MermaidConfig {
    *
    */
   legacyMathML?: boolean;
+  /**
+   * This option forces Mermaid to rely on KaTeX's own stylesheet for rendering MathML. Due to differences between OS
+   * fonts and browser's MathML implementation, this option is recommended if consistent rendering is important.
+   * If set to true, ignores legacyMathML.
+   *
+   */
+  forceLegacyMathML?: boolean;
   /**
    * This option controls if the generated ids of nodes in the SVG are
    * generated randomly or based on a seed.
@@ -158,7 +165,7 @@ export interface MermaidConfig {
   block?: BlockDiagramConfig;
   dompurifyConfig?: DOMPurifyConfiguration;
   wrap?: boolean;
-  fontSize?: string | number;
+  fontSize?: number;
   markdownAutoWrap?: boolean;
   /**
    * Suppresses inserting 'Syntax error' diagram in the DOM.

packages/mermaid/src/diagrams/common/common.ts

@@ -337,18 +337,20 @@ export const renderKatex = async (text: string, config: MermaidConfig): Promise<
     return text;
   }
 
-  if (!isMathMLSupported() && !config.legacyMathML) {
+  if (!(isMathMLSupported() || config.legacyMathML || config.forceLegacyMathML)) {
     return text.replace(katexRegex, 'MathML is unsupported in this environment.');
   }
 
   const { default: katex } = await import('katex');
+  const outputMode =
+    config.forceLegacyMathML || (!isMathMLSupported() && config.legacyMathML)
+      ? 'htmlAndMathml'
+      : 'mathml';
   return text
     .split(lineBreakRegex)
     .map((line) =>
       hasKatex(line)
-        ? `<div style="display: flex; align-items: center; justify-content: center; white-space: nowrap;">
-              ${line}
-            </div>`
+        ? `<div style="display: flex; align-items: center; justify-content: center; white-space: nowrap;">${line}</div>`
         : `<div>${line}</div>`
     )
     .join('')
@@ -357,7 +359,7 @@ export const renderKatex = async (text: string, config: MermaidConfig): Promise<
         .renderToString(c, {
           throwOnError: true,
           displayMode: true,
-          output: isMathMLSupported() ? 'mathml' : 'htmlAndMathml',
+          output: outputMode,
         })
         .replace(/\n/g, ' ')
         .replace(/<annotation.*<\/annotation>/g, '')

packages/mermaid/src/diagrams/xychart/xychartRenderer.ts

@@ -36,6 +36,7 @@ export const draw = (txt: string, id: string, _version: string, diagObj: Diagram
     .attr('height', chartConfig.height)
     .attr('class', 'background');
 
+  // @ts-ignore: TODO Fix ts errors
   configureSvgSize(svg, chartConfig.height, chartConfig.width, true);
 
   svg.attr('viewBox', `0 0 ${chartConfig.width} ${chartConfig.height}`);

packages/mermaid/src/docs/config/math.md

@@ -60,3 +60,13 @@ Example with legacy mode enabled (the latest version of KaTeX's stylesheet can b
   </body>
 </html>
 ```
+
+## Handling Rendering Differences
+
+Due to differences between default fonts across operating systems and browser's MathML implementations, inconsistent results can be seen across platforms. If having consistent results are important, or the most optimal rendered results are desired, `forceLegacyMathML` can be enabled in the config.
+
+This option will always use KaTeX's stylesheet instead of only when MathML is not supported (as with `legacyMathML`). Note that only `forceLegacyMathML` needs to be set.
+
+If including KaTeX's stylesheet is not a concern, enabling this option is recommended to avoid scenarios where no MathML implementation within a browser provides the desired output (as seen below).
+
+![Image showing differences between Browsers](img/mathMLDifferences.png)

packages/mermaid/src/docs/ecosystem/integrations-community.md

@@ -235,6 +235,8 @@ Communication tools and platforms
 
 ### Other
 
+- [Astro](https://astro.build/)
+  - [Adding diagrams to your Astro site with MermaidJS and Playwright](https://agramont.net/blog/diagraming-with-mermaidjs-astro/)
 - [Bisheng](https://www.npmjs.com/package/bisheng)
   - [bisheng-plugin-mermaid](https://github.com/yct21/bisheng-plugin-mermaid)
 - [Blazorade Mermaid: Render Mermaid diagrams in Blazor applications](https://github.com/Blazorade/Blazorade-Mermaid/wiki)
@@ -244,6 +246,7 @@ Communication tools and platforms
 - [Jekyll](https://jekyllrb.com/)
   - [jekyll-mermaid](https://rubygems.org/gems/jekyll-mermaid)
   - [jekyll-mermaid-diagrams](https://github.com/fuzhibo/jekyll-mermaid-diagrams)
+- [MarkChart: Preview Mermaid diagrams on macOS](https://markchart.app/)
 - [mermaid-isomorphic](https://github.com/remcohaszing/mermaid-isomorphic)
 - [mermaid-server: Generate diagrams using a HTTP request](https://github.com/TomWright/mermaid-server)
 - [NiceGUI: Let any browser be the frontend of your Python code](https://nicegui.io) ✅

packages/mermaid/src/mermaidAPI.ts

@@ -10,8 +10,10 @@
  *
  * In addition to the render function, a number of behavioral configuration options are available.
  */
+// @ts-ignore TODO: Investigate D3 issue
 import { select } from 'd3';
 import { compile, serialize, stringify } from 'stylis';
+// @ts-ignore: TODO Fix ts errors
 import { version } from '../package.json';
 import * as configApi from './config.js';
 import { addDiagrams } from './diagram-api/diagram-orchestration.js';

packages/mermaid/src/schemas/config.schema.yaml

@@ -180,6 +180,13 @@ properties:
       fall back to legacy rendering for KaTeX.
     type: boolean
     default: false
+  forceLegacyMathML:
+    description: |
+      This option forces Mermaid to rely on KaTeX's own stylesheet for rendering MathML. Due to differences between OS 
+      fonts and browser's MathML implementation, this option is recommended if consistent rendering is important.
+      If set to true, ignores legacyMathML.
+    type: boolean
+    default: false
   deterministicIds:
     description: |
       This option controls if the generated ids of nodes in the SVG are

packages/mermaid/src/types.ts

@@ -1,5 +1,3 @@
-import type { interpolateToCurve } from './utils.js';
-
 export interface Point {
   x: number;
   y: number;
@@ -32,7 +30,7 @@ export interface EdgeData {
   arrowTypeEnd: string;
   style: string;
   labelStyle: string;
-  curve: ReturnType<typeof interpolateToCurve>;
+  curve: any;
 }
 
 export type ArrayElement<A> = A extends readonly (infer T)[] ? T : never;

packages/mermaid/src/utils.ts

@@ -1,5 +1,5 @@
 import { sanitizeUrl } from '@braintree/sanitize-url';
-import type { CurveFactory, Selection } from 'd3';
+import type { CurveFactory } from 'd3';
 import {
   curveBasis,
   curveBasisClosed,
@@ -230,12 +230,16 @@ export const isSubstringInArray = function (str: string, arr: string[]): number
  * @param defaultCurve - The default curve to return
  * @returns The curve factory to use
  */
-export function interpolateToCurve(interpolate: string | undefined, defaultCurve: CurveFactory) {
+export function interpolateToCurve(
+  interpolate: string | undefined,
+  defaultCurve: CurveFactory
+): CurveFactory {
   if (!interpolate) {
     return defaultCurve;
   }
   const curveName = `curve${interpolate.charAt(0).toUpperCase() + interpolate.slice(1)}`;
 
+  // @ts-ignore TODO: Fix issue with curve type
   return d3CurveTypes[curveName as keyof typeof d3CurveTypes] ?? defaultCurve;
 }
 
@@ -483,25 +487,6 @@ export const random = (options: { length: number }) => {
   return makeRandomHex(options.length);
 };
 
-interface TextData {
-  text: string;
-  x: number;
-  y: number;
-  anchor: 'start' | 'middle' | 'end';
-  fontFamily?: string;
-  fontSize?: string | number;
-  fontWeight?: string | number;
-  fill?: string;
-  class?: string;
-  textMargin: number;
-  style?: string;
-  width?: number;
-  height?: number;
-  rx?: number;
-  ry?: number;
-  valign?: string;
-}
-
 export const getTextObj = function () {
   return {
     x: 0,
@@ -516,7 +501,7 @@ export const getTextObj = function () {
     ry: 0,
     valign: undefined,
     text: '',
-  } satisfies TextData;
+  };
 };
 
 /**
@@ -527,9 +512,20 @@ export const getTextObj = function () {
  * @returns Text element with given styling and content
  */
 export const drawSimpleText = function (
-  elem: Selection<SVGSVGElement, any, HTMLElement, any>,
-  textData: TextData
-) {
+  elem: SVGElement,
+  textData: {
+    text: string;
+    x: number;
+    y: number;
+    anchor: 'start' | 'middle' | 'end';
+    fontFamily: string;
+    fontSize: string | number;
+    fontWeight: string | number;
+    fill: string;
+    class: string | undefined;
+    textMargin: number;
+  }
+): SVGTextElement {
   // Remove and ignore br:s
   const nText = textData.text.replace(common.lineBreakRegex, ' ');
 
@@ -693,7 +689,7 @@ export const calculateTextDimensions: (
   text: string,
   config: TextDimensionConfig
 ) => TextDimensions = memoize(
-  (text: string, config: TextDimensionConfig) => {
+  (text: string, config: TextDimensionConfig): TextDimensions => {
     const { fontSize = 12, fontFamily = 'Arial', fontWeight = 400 } = config;
     if (!text) {
       return { width: 0, height: 0 };
@@ -723,7 +719,9 @@ export const calculateTextDimensions: (
       for (const line of lines) {
         const textObj = getTextObj();
         textObj.text = line || ZERO_WIDTH_SPACE;
+        // @ts-ignore TODO: Fix D3 types
         const textElem = drawSimpleText(g, textObj)
+          // @ts-ignore TODO: Fix D3 types
           .style('font-size', _fontSizePx)
           .style('font-weight', fontWeight)
           .style('font-family', fontFamily);