Skip to content

external-libraries.md

Latest commit

 

History

History
281 lines (220 loc) · 7.5 KB

external-libraries.md

File metadata and controls

281 lines (220 loc) · 7.5 KB

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

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