DOC-3189: Add new options for preserving MathML elements and attributes in the Math plugin

modules/ROOT/pages/7.8.0-release-notes.adoc

@@ -101,6 +101,54 @@ Previously, deleting a comment reply did not dispatch a `change` event, which pr
 
 For information on the **Comments** plugin, see: xref:introduction-to-tiny-comments.adoc[Introduction to {companyname} Comments].
 
+=== Math
+
+The {productname} {release-version} release includes an accompanying release of the **Math** premium plugin.
+
+**Math** includes the following addition.
+
+==== New `extended_mathml_attributes` and `extended_mathml_elements` options.
+// #TINY-11756
+
+To improve flexibility when working with MathML content, especially in cases where new attributes or elements are not yet supported by DOMPurify, two new configuration options have been introduced: xref:math.adoc#extended-mathml-elements[extended_mathml_elements] and xref:math.adoc#extended-mathml-attributes[extended_mathml_attributes].
+
+Prior to {release-version}, MathML elements and attributes were treated the same as all other content, with no special handling for MathML-specific structures. As a result, unsupported elements and attributes were either retained without validation or stripped without regard to their MathML context.
+
+In {productname} {release-version}, MathML content is now filtered separately from general HTML using DOMPurify. As part of this change, support has been added to selectively allow specific elements and attributes *within* a `<math>` element using the new configuration options.
+
+The new options allow users to define lists of MathML elements and attributes that should be preserved, even if DOMPurify does not currently recognize them. This enables quicker user-side updates in response to evolving MathML specifications without disabling sanitization or waiting for upstream changes.
+
+* **`+extended_mathml_elements+`**: allows a list of additional MathML elements to be preserved.
+* **`+extended_mathml_attributes+`**: allows a list of additional MathML attributes to be preserved.
+
+These options apply only within MathML contexts and do not affect general HTML content. They enable use cases such as preserving `+<mn>+` elements and attributes like `linebreak` in MathML expressions.
+
+.Example of MathML with preserved elements and attributes
+[source,js]
+----
+tinymce.init({
+  selector: "textarea",
+  extended_mathml_elements: [ "mn" ],
+  extended_mathml_attributes: [ "linebreak" ]
+});
+----
+
+.Example of MathML with preserved elements and attributes
+[source,html]
+----
+<p>
+  <math xmlns="http://www.w3.org/1998/Math/MathML">
+    <mrow><mn>0.196</mn></mrow>
+    <mspace linebreak="newline"></mspace>
+    <mrow><mo>=</mo></mrow>
+    <mspace linebreak="newline"></mspace>
+    <mrow><mn>0.196</mn></mrow>
+  </math>
+</p>
+----
+
+For information on the **Math** premium plugin, see: xref:math.adoc[Math].
+
 === Export to Word
 
 The {productname} {release-version} release includes an accompanying update to the **Export to Word** premium plugin.

modules/ROOT/pages/math.adoc

@@ -72,6 +72,12 @@ include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[]
 
 include::partial$misc/plugin-menu-item-id-boilerplate.adoc[]
 
+== Options
+
+include::partial$configuration/extended_mathml_elements.adoc[leveloffset=+1]
+
+include::partial$configuration/extended_mathml_attributes.adoc[leveloffset=+1]
+
 == Commands
 
 The {pluginname} plugin provides the following {productname} commands.

modules/ROOT/partials/configuration/extended_mathml_attributes.adoc

@@ -0,0 +1,57 @@
+[[extended-mathml-attributes]]
+== `+extended_mathml_attributes+`
+
+This option allows a specific list of additional MathML attributes to be preserved in the editor content, even if they are not included in the default DOMPurify allowlist. This setting only affects attributes used within MathML markup and has no effect on general HTML content.
+
+*Type:* `+Array+` of `+Strings+`
+
+*Default value:* `+[]+` (empty array)
+
+=== Example: using `+extended_mathml_attributes+`
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',
+  extended_mathml_attributes: [ 'linebreak', 'encoding' ]
+});
+----
+
+.Example of MathML with preserved attributes
+[source,html]
+----
+<p>
+  <math xmlns="http://www.w3.org/1998/Math/MathML">
+    <mrow linebreak="newline" encoding="utf8">
+      <mi>x</mi>
+      <mo>=</mo>
+      <mfrac>
+        <mrow>
+          <mo>&#x2212;</mo>
+          <mi>b</mi>
+          <mo>&#x00B1;</mo>
+          <msqrt>
+            <mrow>
+              <msup>
+                <mi>b</mi>
+                <mn>2</mn>
+              </msup>
+              <mo>&#x2212;</mo>
+              <mn>4</mn>
+              <mo>&#x2062;</mo>
+              <mi>a</mi>
+              <mo>&#x2062;</mo>
+              <mi>c</mi>
+            </mrow>
+          </msqrt>
+        </mrow>
+        <mrow>
+          <mn>2</mn>
+          <mo>&#x2062;</mo>
+          <mi>a</mi>
+        </mrow>
+      </mfrac>
+    </mrow>
+  </math>
+</p>
+----

modules/ROOT/partials/configuration/extended_mathml_elements.adoc

@@ -0,0 +1,46 @@
+[[extended-mathml-elements]]
+== `+extended_mathml_elements+`
+
+This option allows a specific list of additional MathML elements to be preserved in the editor content, even if they are not included in the default DOMPurify allowlist. This setting only affects elements used within MathML markup and has no effect on general HTML content.
+
+*Type:* `+Array+` of `+Strings+`
+
+*Default value:* `+[]+` (empty array)
+
+=== Example: using `+extended_mathml_elements+`
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',
+  extended_mathml_elements: [ 'mn', 'mspace' ]
+});
+----
+
+.Example of MathML with preserved elements
+[source,html]
+----
+<p>
+  <math xmlns="http://www.w3.org/1998/Math/MathML">
+    <mrow>
+      <mi>a</mi>
+      <mo>=</mo>
+      <mfrac>
+        <mrow>
+          <mn>1</mn>
+          <mo>+</mo>
+          <mn>√2</mn>
+        </mrow>
+        <mn>3</mn>
+      </mfrac>
+      <mspace width="1em"></mspace>
+      <mo>&#x222A;</mo>
+      <mspace width="1em"></mspace>
+      <msup>
+        <mn>5</mn>
+        <mn>2</mn>
+      </msup>
+    </mrow>
+  </math>
+</p>
+----