diff --git a/docs/config/img/mathMLDifferences.png b/docs/config/img/mathMLDifferences.png new file mode 100644 index 000000000..6b7a86400 Binary files /dev/null and b/docs/config/img/mathMLDifferences.png differ diff --git a/docs/config/math.md b/docs/config/math.md index 154158508..b2063e3af 100644 --- a/docs/config/math.md +++ b/docs/config/math.md @@ -84,3 +84,13 @@ Example with legacy mode enabled (the latest version of KaTeX's stylesheet can b ``` + +## 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) diff --git a/packages/mermaid/src/config.type.ts b/packages/mermaid/src/config.type.ts index 79f424315..775d49fb5 100644 --- a/packages/mermaid/src/config.type.ts +++ b/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. diff --git a/packages/mermaid/src/diagrams/common/common.ts b/packages/mermaid/src/diagrams/common/common.ts index 017b2b091..66cc5ff6f 100644 --- a/packages/mermaid/src/diagrams/common/common.ts +++ b/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) - ? `
- ${line} -
` + ? `
${line}
` : `
${line}
` ) .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(//g, '') diff --git a/packages/mermaid/src/docs/config/img/mathMLDifferences.png b/packages/mermaid/src/docs/config/img/mathMLDifferences.png new file mode 100644 index 000000000..6b7a86400 Binary files /dev/null and b/packages/mermaid/src/docs/config/img/mathMLDifferences.png differ diff --git a/packages/mermaid/src/docs/config/math.md b/packages/mermaid/src/docs/config/math.md index 22b398e08..a53dceaf2 100644 --- a/packages/mermaid/src/docs/config/math.md +++ b/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 ``` + +## 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) diff --git a/packages/mermaid/src/schemas/config.schema.yaml b/packages/mermaid/src/schemas/config.schema.yaml index d1bb8ad1b..68da484e0 100644 --- a/packages/mermaid/src/schemas/config.schema.yaml +++ b/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