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:

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:

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:

---

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