External Libraries Integration Guide

SunEditor supports integration with external libraries for enhanced functionality. This guide explains how to configure and use CodeMirror (code highlighting in code view) and KaTeX/MathJax (math formula rendering).

---

Table of Contents

• CodeMirror Integration
• Math Libraries
  • KaTeX
  • MathJax
  • Math Plugin Options
• Troubleshooting

---

CodeMirror Integration

CodeMirror provides syntax highlighting and advanced editing features for the code view mode.

Installation:

npm install codemirror

Configuration:

import CodeMirror from 'codemirror';
import 'codemirror/lib/codemirror.css';
import 'codemirror/mode/htmlmixed/htmlmixed';
import SUNEDITOR from 'suneditor';
import plugins from 'suneditor/src/plugins';

const editor = SUNEDITOR.create('editor', {
	plugins: plugins,
	buttonList: [['codeView']],
	externalLibs: {
		codeMirror: {
			src: CodeMirror,
			options: {
				// Optional: Override default options
				mode: 'htmlmixed',
				htmlMode: true,
				lineNumbers: true,
				lineWrapping: true,
			},
		},
	},
});

CodeMirror Options:

Property	Type	Required	Description
src	Object	✅	The CodeMirror library object
options	Object	❌	CodeMirror configuration options

Default Options:

{
  mode: 'htmlmixed',
  htmlMode: true,
  lineNumbers: true,
  lineWrapping: true
}

CDN Usage (HTML):

<!-- CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/codemirror@6.65.7/lib/codemirror.min.css" />

<!-- JavaScript -->
<script src="https://cdn.jsdelivr.net/npm/codemirror@6.65.7/lib/codemirror.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/codemirror@6.65.7/mode/htmlmixed/htmlmixed.js"></script>
<script src="https://cdn.jsdelivr.net/npm/codemirror@6.65.7/mode/xml/xml.js"></script>
<script src="https://cdn.jsdelivr.net/npm/codemirror@6.65.7/mode/css/css.js"></script>

// CodeMirror is available as global variable
SUNEDITOR.create('editor', {
	externalLibs: {
		codeMirror: {
			src: CodeMirror,
		},
	},
});

---

Math Libraries

The math plugin allows inserting mathematical formulas. It requires either KaTeX or MathJax library.

Important: Include the math plugin in your buttonList to use math formula features.

KaTeX

KaTeX is a fast, lightweight library for rendering LaTeX math.

Installation:

npm install katex

Configuration:

import katex from 'katex';
import 'katex/dist/katex.css';
import SUNEDITOR from 'suneditor';
import plugins from 'suneditor/src/plugins';

const editor = SUNEDITOR.create('editor', {
	plugins: plugins,
	buttonList: [['math']],
	externalLibs: {
		katex: {
			src: katex,
			options: {
				// Optional: KaTeX render options
				throwOnError: false,
				displayMode: true,
			},
		},
	},
});

KaTeX Options:

Property	Type	Required	Description
src	Object	✅	The katex library object
options	Object	❌	KaTeX rendering options

Default KaTeX Options:

{
	throwOnError: false;
}

CDN Usage (HTML):

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.2/dist/katex.min.css" />
<script src="https://cdn.jsdelivr.net/npm/katex@0.16.2/dist/katex.min.js"></script>

// katex is available as global variable
SUNEDITOR.create('editor', {
	externalLibs: {
		katex: {
			src: katex,
		},
	},
});

---

MathJax

MathJax provides comprehensive math rendering with broader LaTeX support.

Note: MathJax is not supported in iframe mode.

Installation:

npm install mathjax-full

Configuration:

import { mathjax } from 'mathjax-full/js/mathjax.js';
import { TeX } from 'mathjax-full/js/input/tex.js';
import { CHTML } from 'mathjax-full/js/output/chtml.js';
import { browserAdaptor } from 'mathjax-full/js/adaptors/browserAdaptor.js';
import { RegisterHTMLHandler } from 'mathjax-full/js/handlers/html.js';
import SUNEDITOR from 'suneditor';
import plugins from 'suneditor/src/plugins';

const editor = SUNEDITOR.create('editor', {
	plugins: plugins,
	buttonList: [['math']],
	externalLibs: {
		mathjax: {
			src: mathjax,
			TeX: TeX,
			CHTML: CHTML,
			browserAdaptor: browserAdaptor,
			RegisterHTMLHandler: RegisterHTMLHandler,
		},
	},
});

MathJax Options:

Property	Type	Required	Description
src	Object	✅	The mathjax library object
TeX	Class	✅	TeX input processor class
CHTML	Class	✅	CHTML output processor class
browserAdaptor	Function	✅	Browser adaptor function
RegisterHTMLHandler	Function	✅	HTML handler registration function

---

Math Plugin Options

The math plugin has additional configuration options:

SUNEDITOR.create('editor', {
	externalLibs: {
		katex: { src: katex },
	},
	math: {
		fontSizeList: [
			{ text: '1', value: '1em' },
			{ text: '1.5', value: '1.5em' },
			{ text: '2', value: '2em', default: true },
			{ text: '2.5', value: '2.5em' },
		],
		formSize: {
			width: '460px',
			height: '14em',
			minWidth: '400px',
			minHeight: '40px',
			maxWidth: '800px',
			maxHeight: '400px',
		},
		canResize: true,
		autoHeight: false,
		onPaste: function (event) {
			// Custom paste handler for math input
		},
	},
});

---

Troubleshooting

CodeMirror not working

1. Check import: Ensure you're importing the correct version
2. Verify options: Ensure src property is set to the CodeMirror library object
3. Check console: Look for [SUNEDITOR.options.externalLibs.codeMirror.fail] warnings

Math formulas not rendering

1. Library not loaded: Check for [SUNEDITOR.plugins.math.warn] in console
2. KaTeX CSS missing: Include katex.min.css for proper rendering
3. MathJax in iframe: MathJax is not supported in iframe mode

Common Console Warnings

Warning	Cause	Solution
The math plugin must need either "KaTeX" or "MathJax" library	No math library configured	Add katex or mathjax to externalLibs
The katex option is set incorrectly	Missing src property	Add src: katex to katex options
The MathJax option is set incorrectly	Missing required MathJax components	Include all required MathJax imports
The MathJax option is not supported in the iframe	Using MathJax with iframe mode	Use KaTeX instead or disable iframe mode
The codeMirror option is set incorrectly	Missing src property	Add src: CodeMirror to codeMirror options