Native MathML TinyMCE Editor

tinymce-native-mathml-editor is a visual Mathematics, Physics, and Chemistry formula editor for TinyMCE. It creates, edits, stores, and displays equations as native MathML.

The package does not use LaTeX, KaTeX, MathJax, MathLive, or a hidden equation string as its internal model. The live MathML DOM is the source of truth from authoring through persistence and browser display.

Highlights

• Visual slot-based editing with keyboard navigation and formula undo/redo.
• Fractions, roots, powers, indices, limits, integrals, sums, matrices, vectors, cases, accents, fences, and multiline structures.
• Mathematics, Physics, and Chemistry palettes.
• Chemistry typing such as H2SO4 and Ca(OH)2 becomes MathML subscripts.
• Chemistry charges, isotope templates, reaction arrows, equilibrium arrows, physical states, and common compounds.
• Native MathML import and re-editing.
• Clipboard conversion for native MathML, Word OMML, common TeX-style input, KaTeX/MathJax MathML, and mixed prose.
• Clean persistence: temporary editor slots, caret markers, and editor-only attributes are removed before MathML is saved.
• No runtime equation renderer is shipped; browsers render the saved MathML.

Requirements

• TinyMCE 7.8 or newer; TinyMCE 8 is used by the demo.
• A modern browser with native MathML support.
• Node.js 20.19+ only when building or developing this package.

Install

npm install tinymce tinymce-native-mathml-editor

TinyMCE is a peer dependency. Load TinyMCE, then load the plugin and its stylesheet:

import tinymce from "tinymce/tinymce";
import "tinymce/icons/default";
import "tinymce/themes/silver";
import "tinymce/models/dom";
import "tinymce-native-mathml-editor";
import "tinymce-native-mathml-editor/plugin.css";

await tinymce.init({
  selector: "#editor",
  license_key: "gpl",
  plugins: "nativemathml",
  toolbar: "undo redo | nativemathml",
  nativemathml_default_type: "math",
});

The plugin registers itself with TinyMCE's PluginManager under the name nativemathml. The JavaScript import is intentionally side-effect-only.

Self-hosted external plugin

If the application loads TinyMCE plugins from public URLs, copy these files from node_modules/tinymce-native-mathml-editor/dist/ into a public folder:

/public/vendor/native-mathml/
├── plugin.js
└── plugin.css

Then configure TinyMCE:

tinymce.init({
  selector: "#editor",
  license_key: "gpl",
  external_plugins: {
    nativemathml: "/vendor/native-mathml/plugin.js",
  },
  plugins: "lists table code nativemathml",
  toolbar: "undo redo | nativemathml | bullist numlist | table | code",
});

The plugin discovers plugin.css beside plugin.js. Keep both files in the same public directory.

TinyMCE MathML schema configuration

The plugin protects complete MathML trees while TinyMCE parses content. Hosts can still provide their own MathML schema lists when other plugins or custom schema rules require them. A minimal explicit configuration looks like this:

tinymce.init({
  // ...your normal TinyMCE options...
  extended_mathml_elements: [
    "math", "mrow", "mi", "mn", "mo", "mtext", "mspace",
    "mfrac", "msqrt", "mroot", "msup", "msub", "msubsup",
    "mover", "munder", "munderover", "mtable", "mtr", "mtd",
    "mmultiscripts", "mprescripts", "none",
  ],
  extended_mathml_attributes: [
    "display", "mathvariant", "stretchy", "symmetric", "fence",
    "separator", "form", "accent", "accentunder", "linethickness",
    "rowalign", "columnalign", "rowspacing", "columnspacing",
    "columnlines", "rowlines", "columnwidth", "width", "height",
    "depth", "lspace", "voffset", "scriptlevel", "displaystyle",
  ],
});

Merge these values with existing application configuration rather than replacing lists used by other plugins.

Options

| Option | Default | Purpose | | --- | --- | --- | | nativemathml_default_type | "math" | Initial palette: math, physics, or chemistry. | | nativemathml_enable_math | true | Show Mathematics tools. | | nativemathml_enable_physics | true | Show Physics tools. | | nativemathml_enable_chemistry | true | Show Chemistry tools. | | nativemathml_modal_title | "Native MathML Formula Editor" | Dialog title. | | nativemathml_autoformat | true | Convert common typed operators such as /, *, -, and ->. | | nativemathml_auto_close_fences | true | Automatically close typed fences. | | nativemathml_reserved_functions | built-in list | Comma- or space-separated function names treated as upright operators. |

For literal punctuation, set nativemathml_autoformat: false, switch Autoformat off in the dialog, or hold a modifier key for a single punctuation keystroke.

Saved MathML contract

The package persists standard MathML, for example:

<math xmlns="http://www.w3.org/1998/Math/MathML">
  <mroot>
    <mn>8</mn>
    <mn>2</mn>
  </mroot>
</math>

Before insertion or update, the plugin removes temporary data-mm-* attributes, caret and placeholder nodes, redundant editing rows, and the TinyMCE-only contenteditable="false" protection attribute. The resulting MathML can be stored in normal HTML and rendered by a browser.

Your server-side HTML sanitizer must allow the MathML elements and attributes your application intends to preserve.

Keyboard controls

• Type normally to insert MathML identifiers, numbers, and operators.
• Tab / Shift+Tab: move to the next / previous formula position.
• Arrow keys: move within the active position.
• Backspace / Delete: remove formula nodes.
• Ctrl/Cmd+Z: undo formula editing.
• Ctrl/Cmd+Y or Ctrl/Cmd+Shift+Z: redo where supported.
• Ctrl/Cmd+Enter: insert or update the formula.
• Escape: close the dialog.

Double-click an existing MathML formula to edit it, or select it and click the nativemathml toolbar button.

Demo and development

npm install
npm start

npm start builds the plugin and starts the Vite demo. The demo includes existing MathML fixtures, a raw HTML/MathML loader, and output inspection.

Useful commands:

npm run check          # type checking and tests
npm run build          # distributable JavaScript, CSS, and declarations
npm run build:portable # classic browser-script build
npm pack --dry-run     # inspect the npm tarball contents

The test suite runs in jsdom and verifies MathML serialization, clipboard conversion, chemistry parsing, editing behavior, TinyMCE boundaries, and regressions in navigation and undo behavior.

Package exports

tinymce-native-mathml-editor            side-effect plugin registration
tinymce-native-mathml-editor/plugin.css dialog stylesheet

Project structure

src/plugin.ts          TinyMCE registration and editor integration
src/editor/            Dialog, document model, clipboard, and boundaries
src/mathml/            MathML construction, parsing, tokenizing, and catalog data
src/plugin.css         Dialog and editor styles
demo/                  Runnable TinyMCE demo
tests/                 Vitest regression and model tests
docs/                  Architecture, MathML contract, and release guidance

License

MIT. See LICENSE.

Releasing

See docs/RELEASING.md for the complete GitHub and npm publication procedure, including trusted publishing from GitHub Actions.