ckeditor5-math

CKEditor 5 mathematical feature

This is the best* TeX-based mathematical plugin for CKEditor 5. You can use it to insert, edit and view mathematical equation and formulas. This plugin supports MathJax, KaTeX and custom typesetting engines.

Table of contents

• Features
• Screenshots
• Examples
• Installation
  • Styles for Lark theme
• Configuration & Usage
  • Plugin options
  • Available typesetting engines
  • Supported input and output formats
• Paste support
  • From plain text
  • From Microsoft Word
• Preview workaround
• Todo

Features

• TeX syntax
• Inline and display equations
• Preview view
• Multiple typesetting engines
• Have multiple input and output format
• Paste support
  • from plain text
  • from Microsoft Word

Screenshots

Examples

Link to examples repository

Installation

Use official classic or inline build as a base:

• CKEditor 5 classic editor build
• CKEditor 5 inline editor build

Install plugin with NPM or Yarn

npm install ckeditor5-math --save-dev

Add import into ckeditor.js file

import Mathematics from 'ckeditor5-math/src/math';

Add it to built-in plugins

InlineEditor.builtinPlugins = [
	// ...
	Mathematics
];

Add math button to toolbar

InlineEditor.defaultConfig = {
	toolbar: {
		items: [
			// ...
			'math'
		]
	}
};

Styles for Lark theme

Copy theme/ckeditor5-math folder from https://github.com/isaul32/ckeditor5-theme-lark to your lark theme repository or install

npm install @ckeditor/ckeditor5-theme-lark@https://github.com/isaul32/ckeditor5-theme-lark --save-dev

Styles requires PostCSS like official CKEditor 5 plugins.

Configuration & Usage

Plugin options

InlineEditor.defaultConfig = {
    // ...
    math: {
        engine: 'mathjax', // or katex or function (equation, element, display) => { ... }
        outputType: 'script', // or span or math
		forceOutputType: false, // forces output to use outputType
		enablePreview: true // Enable preview view
    }
}

Available typesetting engines

MathJax

• Tested by using latest 2.7
• Has experimental (CHTML, SVG) support for 3.0.0 or newer version
• Use only \( \) delimiters for inline and \[ \] delimiters for display

KaTeX

• Tested by using version 0.11.0

Custom typesetting

It's possible to implement with engine config. For example, this feature can be used when use back end rendering.

InlineEditor.defaultConfig = {
	// ...
	math: {
		engine: (equation, element, display, preview) => {
			// ...
		}
	}
}

• equation is equation in TeX format without delimiters.
• element is DOM element reserved for rendering.
• display is boolean. Typesetting should be inline when false.
• preview is boolean. Rendering in preview when true.

Supported input and output formats

Supported input and output formats are:

<!-- MathJax style http://docs.mathjax.org/en/v2.7-latest/advanced/model.html#how-mathematics-is-stored-in-the-page -->
<script type="math/tex">\sqrt{\frac{a}{b}}</script>
<script type="math/tex; mode=display">\sqrt{\frac{a}{b}}</script>

<!-- CKEditor 4 style https://ckeditor.com/docs/ckeditor4/latest/features/mathjax.html -->
<span class="math-tex">\( \sqrt{\frac{a}{b}} \)</span>
<span class="math-tex">\[ \sqrt{\frac{a}{b}} \]</span>

Paste support

From plain text

Paste TeX equations with delimiters. For example:

\[ x=\frac{-b\pm\sqrt{b^2-4ac}}{2a} \]

or

\( x=\frac{-b\pm\sqrt{b^2-4ac}}{2a} \)

From Microsoft Word

Use paste from office fork instead of official. This feature is experimental and might not work always (look source codes).

Install paste from office fork

npm install @ckeditor/ckeditor5-paste-from-office@github:isaul32/ckeditor5-paste-from-office --save-dev

import PasteFromOffice from '@ckeditor/ckeditor5-paste-from-office/src/pastefromoffice';
import Mathematics from 'ckeditor5-math/src/math';
// ...
InlineEditor.builtinPlugins = [
	// ...
	PasteFromOffice,
	Mathematics
];

Preview workaround

.ck-reset_all * css rules from ckeditor5-ui and ckeditor5-theme-lark break rendering in preview mode.

My solution for this is use rendering element outside of CKEditor DOM and place it right place by using absolute position. Alternative solution could be using iframe, but then we have to copy typesetting engine's scripts and styles to child document.

Todo

• MathML input and output when using MathJax version 3
• Make tests

[*] at least in my opinion 😄

Changelog

1.0.0 (2019-10-03)

Initial release.