Extension:CodeMirror/6

This documentation refers to CodeMirror 6 – the new version of CodeMirror. It is slated to replace CodeMirror 5 by MediaWiki version 1.43 (release timeline ). See the migration guide on migrating clients to CodeMirror 6, and Extension:CodeMirror for CodeMirror 5 documentation.

MediaWiki extensions manual

CodeMirror Release status: stable
Implementation	User interface
Description	Provides syntax highlighting in editors
Author(s)	Pavel Astakhov MusikAnimal Bhsd
Maintainer(s)	Community Tech
Latest version	5.0.0
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki	>= 1.42.0
PHP	7.4+
License	GNU General Public License 2.0 or later
Download	Download extension Git [?]: Download Git master browse repository (Phabricator · GitHub) commit history repository contributors (GitHub) code review README
Parameters $wgCodeMirrorConflictingGadgets $wgCodeMirrorV6 $wgCodeMirrorTemplateFoldingNamespaces $wgCodeMirrorLineNumberingNamespaces
Hooks used EditPage::showEditForm:initial EditPage::showReadOnlyForm:initial GetPreferences ResourceLoaderGetConfigVars
Quarterly downloads	324 (Ranked 17th)
Public wikis using	6,549 (Ranked 62nd)
Translate the CodeMirror/6 extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug

The CodeMirror extension provides syntax highlighting in MediaWiki wikitext editors using the CodeMirror library. For usage and a list of features, see Help:Extension:CodeMirror.

In 2024, the extension was upgraded to the new major version, CodeMirror 6, and with it many new features were added. See #Differences from CodeMirror 5 for a detailed list of the changes.

Usage

For usage of this extension, see Help:Extension:CodeMirror.

For the JavaScript documentation, see docs.wikimedia.org/CodeMirror.

Differences from CodeMirror 5

Change log

New features

• No longer requires the use of WikiEditor.
• Significant performance improvements.
• Right-to-left support (task T170001) with bidi isolation (task T358804).
• Template folding (task T30684)
• Syntax highlighting on read-only pages (task T301615)
• …

Bug fixes

• Highlighting table captions with attributes (task T324374).
• No longer incorrectly highlights protocol-like words (task T309880).
• Improved treatment of lists at the start of a line (task T184272).
• Added support for jQuery.textSelection's "encapsulate" method (task T211205).
• Syncing text editor font preference in editors other than the 2017 editor (task T245568).
• No longer loads the CodeMirror ResourceLoader module unnecessarily on pages where it isn't used (task T359206).
• Link titles can be both emboldened and italicized.
• Closing HTML tags that highlighted as an error also highlight the closing bracket.
• …

Deprecations and other changes

• The ext.CodeMirror and ext.CodeMirror.WikiEditor modules will be replaced with ext.CodeMirror.init and ext.CodeMirror.WikiEditor.init in MediaWiki 1.43 (release timeline ). Until then, use the .v6 variants documented below.
• The .cm-mw-mnemonic CSS class has been renamed to .cm-mw-html-entity.
• The .cm-mw-template-name-mnemonic class has been removed. Use .cm-mw-template-ground.cm-html-entity instead.
• Line-level styling for <nowiki>, <pre>, or any tag without an associated TagMode has been removed (task T351686).
• Mixed languages within wikitext are not yet supported (task T357480). The only known usage of this with CodeMirror 5 is Extension:PhpTags .
• The browser's native search functionality (using Ctrl+F) has been replaced with search functionality built into CodeMirror. This is necessary to maintain performance (task T303664).

Migration guide

MediaWiki version:

≥ 1.42

This guide applies to MediaWiki 1.42 and later. All integrations should aim to be migrated by the release of MediaWiki 1.43 (release timeline ).

ResourceLoader modules

Ensure you're using the new .v6 modules. Because CodeMirror 6 no longer relies on WikiEditor, there are some naming and behaviourial changes from the CodeMirror 5 counterparts:

Old module	New module (MW 1.42)	New module (MW 1.43)	Description
ext.CodeMirror	ext.CodeMirror.v6.WikiEditor.init	ext.CodeMirror.WikiEditor.init	CodeMirror integration for WikiEditor on #wpTextbox1 (the normal editing textarea) and only for wikitext.
N/A	ext.CodeMirror.v6.WikiEditor	ext.CodeMirror.WikiEditor	Exports the CodeMirrorWikiEditor class
ext.CodeMirror.lib	ext.CodeMirror.v6.lib	ext.CodeMirror.lib	Exports CodeMirror internals.
ext.CodeMirror.addons	N/A	N/A	This packaged the bracket matching feature in CodeMirror 5. Bracket matching is default behaviour in CodeMirror 6.
ext.CodeMirror.mode.mediawiki	ext.CodeMirror.v6.mode.mediawiki	ext.CodeMirror.mode.mediawiki	The MediaWiki language mode.
N/A	ext.CodeMirror.v6	ext.CodeMirror	CodeMirror integration for MediaWiki editors. Exports the CodeMirror class.

With the release of MediaWiki 1.43, the old modules will be replaced with the news ones, and for some time the .v6 modules will be aliased before being removed entirely.

Gadgets and user scripts

The CodeMirror global has been removed entirely. For example, CodeMirror.fromTextArea( myTextarea ) will no longer work. Instead, first load the desired ResourceLoader modules, instantiate a CodeMirror object, and call the initialize() method. See #Using ResourceLoader for examples.

CSS

The .CodeMirror element no longer exists. Use .cm-editor instead for the entire CodeMirror DOM, or .cm-content for the inner content (doesn't include the search panel, for example).

See #Deprecations and other changes for changes to other CSS classes.

Installation

• Download and move the extracted CodeMirror folder to your extensions/ directory.
  Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/CodeMirror
• Add the following code at the bottom of your LocalSettings.php file:

  wfLoadExtension( 'CodeMirror' );
  

• Configure as required.
•  Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration

For customization of colors and CodeMirror's various features, see Help:Extension:CodeMirror

$wgCodeMirrorLineNumberingNamespaces

Restrict line numbering to specific namespaces. Defaults to null, which enables it for all namespaces. Set to [] to disable everywhere.

$wgCodeMirrorTemplateFoldingNamespaces

Restrict template folding to specific namespaces. Defaults to null, which enables it for all namespaces. Set to [] to disable everywhere.

$wgCodeMirrorV6

Temporary feature flag to control the migration to CodeMirror 6 (task T259059).

$wgCodeMirrorRTL

Temporary feature flag to control rollout of CodeMirror 6 to RTL wikis (task T170001).

$wgCodeMirrorConflictingGadgets

An array of gadget names that, if enabled, will prevent CodeMirror from loading. Defaults to wikEd.

Integration

This section documents functionality still in development as of April 2024

Extensions

Registering a new tag for MediaWiki

If you simply want CodeMirror to recognize a tag that is added by an extension, you can do so using the CodeMirrorTagModes extension attribute. For example, to register the tag ‎<foo> as something containing wikitext, you would add the following to extension.json:

{
	"attributes": {
		"CodeMirror": {
			"TagModes": [
				"foo": "mediawiki"
			]
		}
	}
}

CodeMirror will then highlight the content inside ‎<foo>...‎</foo> as wikitext.

Registering a tag so that CodeMirror treats the contents as something other than wikitext is currently not supported (task T357480). If a tag is not registered, CodeMirror will highlight the contents as non-wikitext in the same way it highlights the contents of a ‎<nowiki>...‎</nowiki> tag.

Registering content models

CodeMirror's integration with WikiEditor currently works only with wikitext, but will eventually support other content types.

For the time being, if you need wikitext syntax highlighting on the main textarea (#wpTextbox1) for a content model other than wikitext, you can use the CodeMirrorContentModels extension attribute. For example, Extension:Proofread Page registers the proofread-page content type:

{
	"attributes": {
		"CodeMirror": {
			"ContentModels": [
				"proofread-page"
			]
		}
	}
}

PluginModules

CodeMirrorPluginModules is an extension attribute that allows side-loading a module with CodeMirror. This unconditionally loads the module whenever the ext.CodeMirror.v6 module is loaded. If your plugin is only used in specific circumstances, consider having it check whether it is needed, and dynamically load the core code from a different module. This will avoid unnecessarily consuming end user bandwidth.

extension.json:

{
	"attributes": {
		"CodeMirror": {
			"PluginModules": [
				"ext.MyExtension.CodeMirror"
			]
		}
	}
}

ext.MyExtension.CodeMirror.js:

// Only load in the template namespace
if ( mw.config.get( 'wgNamespaceNumber' ) === 10 ) {
	return mw.loader.using( 'ext.MyExtension.CodeMirror.core' );
}
return Promise.resolve();

JavaScript

Using ResourceLoader

The CodeMirror extension provides a number of ResourceLoader modules for use by user scripts, gadgets, or extensions. To make use of CodeMirror, you'll need at minimum the ext.CodeMirror.v6 module, along with the desired language. For MediaWiki wikitext, you'd use ext.CodeMirror.v6.mode.mediawiki.

Here is an example of how to apply wikitext syntax highlighting to any arbitrary textarea, using the default set of features:

mw.loader.using( [ 'ext.CodeMirror.v6', 'ext.CodeMirror.v6.mode.mediawiki' ] ).then( ( require ) => {
	const CodeMirror = require( 'ext.CodeMirror.v6' );
	const mediawikiLang = require( 'ext.CodeMirror.v6.mode.mediawiki' );
	const cm = new CodeMirror( $( 'textarea' ) );
	cm.initialize( [ cm.defaultExtensions, mediawikiLang() ] );
} );

If you also want WikiEditor:

mw.loader.using( [
	'ext.wikiEditor',
	'ext.CodeMirror.v6.WikiEditor',
	'ext.CodeMirror.v6.mode.mediawiki'
] ).then( ( require ) => {
	mw.addWikiEditor( $( 'textarea' ) );
    const CodeMirrorWikiEditor = require( 'ext.CodeMirror.v6.WikiEditor' );
	const mediawikiLang = require( 'ext.CodeMirror.v6.mode.mediawiki' );
	const cmWe = new CodeMirrorWikiEditor( $( 'textarea' ) );
	cmWe.initialize( [ cmWe.defaultExtensions, mediawikiLang() ] );
	cmWe.addCodeMirrorToWikiEditor();
} );

ResourceLoader modules

Module	Description
ext.CodeMirror.v6.lib	The core CodeMirror library. You shouldn't need to require this directly unless you need access to the upstream CodeMirror API.
ext.CodeMirror.v6	The basic CodeMirror integration for MediaWiki editors. This module exports the CodeMirror class.
ext.CodeMirror.v6.mode.mediawiki	The MediaWiki language mode. Use this in conjunction with the ext.CodeMirror.v6 module.
ext.CodeMirror.v6.init	CodeMirror integration on #wpTextbox1 (the normal editing textarea) and only for wikitext.
ext.CodeMirror.v6.WikiEditor	CodeMirror integration for WikiEditor. This module exports the CodeMirrorWikiEditor class.
ext.CodeMirror.v6.WikiEditor.init	CodeMirror integration for WikiEditor on #wpTextbox1 (the normal editing textarea) and only for wikitext.

Using hooks

You can also integrate with CodeMirror by using frontend hooks. These allow you to run code just before or after CodeMirror has loaded.

Frontend hooks

Hook	Description
ext.CodeMirror.initialize	Called just before CodeMirror is initialized. This can be used to manipulate the DOM to suit CodeMirror (i.e. if you manipulate WikiEditor's DOM, you may need this). Parameters (jQuery) The current "editor", most likely #wpTextbox1
ext.CodeMirror.ready	Called just after CodeMirror is initialized. Parameters (jQuery) The CodeMirror .cm-editor element.
ext.CodeMirror.destroy	Called just after CodeMirror is destroyed and the original textarea is restored. Parameters (jQuery) The original textarea.
ext.CodeMirror.switch	Called after CodeMirror has been enabled or disabled in WikiEditor. Parameters (boolean) Whether the CodeMirror editor is now shown. (jQuery) The current "editor", either the normal #wpTextbox1 or the .cm-editor element.
ext.CodeMirror.input	Called when document changes are made in CodeMirror. Note that the textarea may not be updated yet. Parameters (ViewUpdate) The ViewUpdate object.

Extending CodeMirror

You can import the ext.CodeMirror.v6.lib module to get access to the upstream CodeMirror API. With this you can provide your own Extension when instantiating a CodeMirror or CodeMirrorWikiEditor instance, among other things.

Make note of various default extensions in the CodeMirror class, which may be overridden if needed. Such an example is setting the height of the CodeMirror editor. By default, CodeMirror uses the height of the textarea it is given, but you could change that overriding the heightExtension:

mw.loader.using( [ 'ext.CodeMirror.v6', 'ext.CodeMirror.v6.mode.mediawiki' ] ).then( ( require ) => {
	const CodeMirror = require( 'ext.CodeMirror.v6' );
	const mediawikiLang = require( 'ext.CodeMirror.v6.mode.mediawiki' );
	// ext.CodeMirror.v6.lib is a dependency of ext.CodeMirror.v6, so it's already loaded at this point.
	const lib = require( 'ext.CodeMirror.v6.lib' );
	const cm = new CodeMirror( $( 'textarea' ) );
	cm.heightExtension = lib.EditorView.theme( {
		'&': {
			height: '300px'
		}
	} );
	cm.initialize( [ cmWe.defaultExtensions, mediawikiLang() ] );
} );

Another example is to provide your own Extension that does something when changes are made in CodeMirror:

mw.loader.using( [ 'ext.CodeMirror.v6', 'ext.CodeMirror.v6.mode.mediawiki' ] ).then( ( require ) => {
	const CodeMirror = require( 'ext.CodeMirror.v6' );
	const mediawikiLang = require( 'ext.CodeMirror.v6.mode.mediawiki' );
	// ext.CodeMirror.v6.lib is a dependency of ext.CodeMirror.v6, so it's already loaded at this point.
	const lib = require( 'ext.CodeMirror.v6.lib' );
	const myExtension = lib.EditorView.updateListener.of( ( update ) => {
		if ( update.docChanged ) {
			// do something
		}
	} );
} );
const cm = new CodeMirror( $( 'textarea' ) );
cm.initialize( [ cmWe.defaultExtensions, mediawikiLang(), myExtension ] );

Another means of tracking changes to CodeMirror is using the ext.CodeMirror.input hook:

mw.hook( 'ext.CodeMirror.input' ).add( ( update ) => {
	// Print the ChangeSet to the console
	console.log( update.changes.toJSON() );
} );

See also

• User:Remember the dot/Syntax highlighter
• Extension:VisualEditor
• Extension:WikiEditor
• Extension:CodeEditor
• c:Category:MediaWiki extension CodeMirror