Merge pull request #5483 from NicolasNewman/5435/inconsistent-math-rendering

fix: inconsistent MathML rendering & erroneous <br />s being added

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)

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.

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/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/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