Extension:CodeMirror

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

CodeMirror currently does not support syntax highlighting of Scribunto, JavaScript, CSS and JSON pages, but will in the future (T373711). In the meantime, use Extension:CodeEditor instead.

CodeMirror 확장은 CodeMirror 라이브러리를 사용하여 미디어위키 위키텍스트 편집기에서 구문 강조 표시를 제공합니다. 사용법과 기능 목록에 대해, mw:Help:Extension:CodeMirror 를 참조하십시오.

2024년에, 이 확장은 새로운 주요 버전, CodeMirror 6으로 업그레이드되었고, 많은 새로운 기능이 추가되었습니다. 변경 사항의 자세한 목록에 대해 CodeMirror 5와의 차이점 을 참조하십시오.

Usage

이 확장 기능의 사용법에 대해, mw:Help:Extension:CodeMirror 를 참조하십시오.

자바스크립트 문서에 대해, docs.wikimedia.org/CodeMirror를 참조하십시오.

Installation

미디어위키 확장 내려받기 지면에서 해당 판을 내려받아서 정해진 위치로 이동시킵니다.

또는 개발자와 코드 기여자는 대신 다음을 사용하여 Git에서 확장 프로그램을 설치해야 합니다.

cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/CodeMirror

미디어위키 설정 LocalSettings.php 파일에 다음을 추가합니다:

wfLoadExtension( 'CodeMirror' );

필요하다면 구성하십시오.

Special:Version에 접근해서 확장이 정상적으로 설치가 되었는지 확인하십시오.

Configuration

$wgCodeMirrorLineNumberingNamespaces: Restrict line numbering to specific namespaces. Defaults to null, which enables it for all namespaces. Set to [] to disable everywhere.
$wgCodeMirrorCodeFoldingNamespaces: Restrict code folding to specific namespaces. Defaults to null, which enables it for all namespaces. Set to [] to disable everywhere.
$wgCodeMirrorAutocompleteNamespaces: Restrict autocompletion to specific namespaces. Defaults to null, which enables it for all namespaces. Set to [] to disable everywhere.
$wgCodeMirrorOpenLinksNamespaces: Restrict opening of links with modifier + click 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 (T259059).
$wgCodeMirrorConflictingGadgets: An array of gadget names that, if enabled, will prevent CodeMirror from loading. Defaults to wikEd.
$wgDefaultUserOptions['usecodemirror']: When using CodeMirror version 6, set to 1 to enable by default, set to 0 to only enable if the user selects it in their preferences
$wgCodeMirrorDefaultPreferences: Control which features are enabled by default for all users. Note that some features are not available in the 2017 wikitext editor . See the table below for more information.

$wgCodeMirrorDefaultPreferences
Feature	2017 editor compatibility	Default value
`activeLine`	N	`false`
`bidiIsolation`	N	`false`
`bracketMatching`	Y	`true`
`lineNumbering`	Y	`true`
`lineWrapping`	Y^[1]	`true`
`specialChars`	N	`true`
`codeFolding`	N	`true`
`autocomplete`	N	`true`
`openLinks`	N	`true`

Differences from CodeMirror 5

Change log

New features

No longer requires the use of Extension:WikiEditor .
Significant performance improvements.
Right-to-left support (T170001) with bidi isolation (T358804).
Code folding (T30684).
Autocompletion (T95100).
Quickly open links with modifier key + click (T303392).
Improved search panel (T371436).
CodeMirror preferences (T359498).
Syntax highlighting on read-only pages (T301615).
Syntax highlighting of definition lists (T170042).
Bracket matching for CJK full-width brackets (T362992).
Ctrl+⇧ Shift+X (or ⌘ Cmd+⇧ Shift+X on Mac) changes the directionality of the text (T170001).

Bug fixes

Highlighting table captions with attributes (T324374).
Highlighting indented tables (T108454).
No longer incorrectly highlights protocol-like words (T309880).
Improved treatment of lists at the start of a line (T184272).
Added support for jQuery.textSelection's "encapsulate" method (T211205).
Syncing text editor font preference in editors other than the 2017 editor (T245568).
No longer loads the CodeMirror ResourceLoader module unnecessarily on pages where it isn't used (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 ResourceLoader modules are changing. See the migration guide .
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.
The .cm-mw-apostrophes-bold and .cm-mw-apostrophes-italic CSS classes have been removed. Use .cm-mw-apostrophes instead.
Line-level styling for <nowiki>, <pre>, or any tag without an associated TagMode has been removed (T351686).
Mixed languages within wikitext are not yet supported (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 (T303664).

Migration guide

MediaWiki version:

≥ 1.43

This guide applies to MediaWiki 1.43 and later. All integrations should aim to be migrated by the release of MediaWiki 1.44 (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.43)	New module (MW 1.44+)	Description
`ext.CodeMirror`	`ext.CodeMirror.v6.WikiEditor.init`	`ext.CodeMirror.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
N/A	`ext.CodeMirror.v6.init`	`ext.CodeMirror.init`	CodeMirror for `#wpTextbox1` and only for wikitext.
`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`	Exports the CodeMirror class.
`ext.CodeMirror.visualEditor`	`ext.CodeMirror.visualEditor.init`	`ext.CodeMirror.init`	Integration with the 2017 wikitext editor .
`ext.CodeMirror.lib.mode.php`	N/A	N/A	CodeMirror 6 will not provide these modules. They are rarely used and have no corresponding content model in MediaWiki. If you want support for these languages, you'll need to install the packages and bundle the code yourself.
`ext.CodeMirror.lib.mode.clike`
`ext.CodeMirror.lib.mode.htmlmixed`
`ext.CodeMirror.lib.mode.xml`
`ext.CodeMirror.lib.mode.javascript`	TBD	`ext.CodeMirror.lib.mode.javascript`	These languages are planned to be supported in CodeMirror 6.
`ext.CodeMirror.lib.mode.css`		`ext.CodeMirror.lib.mode.css`
N/A		`ext.CodeMirror.lib.mode.lua`
N/A		`ext.CodeMirror.lib.mode.json`
N/A		`ext.CodeMirror.lib.mode.vue`

With the release of MediaWiki 1.44, 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.

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 to other CSS classes.

Integration

MediaWiki 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 (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 jQuery.textSelection

If you simply want to fetch or make changes to the contents of a textarea, jQuery.textSelection is the easiest means to do so. Usage of jQuery.textSelection on the textarea is bubbled up to CodeMirror, so you don't need to have any knowledge of whether CodeMirror is enabled:

const $textarea = $( '#wpTextbox1' )
const content = $textarea.textSelection( 'getContents' );
// Append "Foobar" to the content.
$textarea.textSelection( 'setContents', content + '\nFoobar' );

Using ResourceLoader

The CodeMirror extension provides a number of ResourceLoader modules for use by user scripts, gadgets, and 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` (internal)	The main entrypoint for action=edit requests. Not intended for external use.
`ext.CodeMirror.v6.WikiEditor`	CodeMirror integration for WikiEditor. This module exports the CodeMirrorWikiEditor class.
`ext.CodeMirror.visualEditor.init`	CodeMirror integration with the 2017 wikitext editor , 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, or react to changes to the document.

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. (`CodeMirror`) The CodeMirror instance.
`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.
`ext.CodeMirror.preferences.ready`	Fired just before CodeMirrorPreferences has been instantiated. Paramaters (`CodeMirrorPreferences`) The CodeMirrorPreferences instance.
`ext.CodeMirror.preferences.change`	Fired when a CodeMirror preference is changed. Paramaters (`string`) The name of the preference, which is also the corresponding key in the extensionRegistry and compartmentRegistry. (`boolean`) The new value of the preference.
`ext.CodeMirror.preferences.display` (internal)	Fired when the preferences panel is constructed, just before it is displayed. Parameters (`HTMLDivElement`) The preferences panel container.

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.

For example, to provide your own Extension that reacts to changes 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 { EditorView } = require( 'ext.CodeMirror.v6.lib' );
	const myExtension = EditorView.updateListener.of( ( /** @type {ViewUpdate} */ update ) => {
		if ( update.docChanged ) {
		    // do something
		    console.log( update.changes );
		}
	} );
	const cm = new CodeMirror( $( 'textarea' ) );
    cm.initialize( [ cm.defaultExtensions, mediawikiLang(), myExtension ] );
} );

Another means of listening to changes 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() );
} );

Registering an extension in CodeMirror preferences

If you want users to be able to toggle on and off an extension that you provide, you must register it with CodeMirrorPreferences. To guard against race conditions, use the ext.CodeMirror.ready hook:

mw.hook( 'ext.CodeMirror.ready' ).add( ( $textarea, cm ) => {
	cm.preferences.registerExtension( 'myExtension'. myExtension, cm.view );
} );

Notes

^ Line wrapping cannot be disabled in the 2017 editor.

[1] Line wrapping cannot be disabled in the 2017 editor.

[1]