Extension:CodeMirror
CodeMirror Release status: stable |
|
---|---|
Implementation | User interface |
Description | Provides syntax highlighting in editors |
Author(s) | |
Maintainer(s) | Community Tech |
Latest version | 6.0.0 |
Compatibility policy | Snapshots releases along with MediaWiki. Master is not backward compatible. |
PHP | 7.4+ |
License | GNU General Public License 2.0 or later |
Download | README |
Help | Help:Extension:CodeMirror |
|
|
Quarterly downloads | 258 (Ranked 20th) |
Public wikis using | 6,549 (Ranked 62nd) |
Translate the CodeMirror 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 the differences from CodeMirror 5 for a detailed list of the changes.
Usage
[edit]For usage of this extension, see Help:Extension:CodeMirror .
For the JavaScript documentation, see docs.wikimedia.org/CodeMirror.
Installation
[edit]- Download and move the extracted
CodeMirror
folder to yourextensions/
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
[edit]- $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 (task T259059).
- $wgCodeMirrorConflictingGadgets
- An array of gadget names that, if enabled, will prevent CodeMirror from loading. Defaults to wikEd.
- $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.
Feature | 2017 editor compatibility |
Default value |
---|---|---|
activeLine |
false
| |
bidiIsolation |
false
| |
bracketMatching |
true
| |
lineNumbering |
true
| |
lineWrapping |
[1] | true
|
specialChars |
true
| |
codeFolding |
true
| |
autocomplete |
true
| |
openLinks |
true
|
Differences from CodeMirror 5
[edit]Change log
[edit]New features
[edit]- No longer requires the use of WikiEditor .
- Significant performance improvements.
- Right-to-left support (task T170001) with bidi isolation (task T358804).
- Code folding (task T30684).
- Autocompletion (task T95100).
- Quickly open links with modifier key + click (task T303392).
- Improved search panel (task T371436).
- CodeMirror preferences (task T359498).
- Syntax highlighting on read-only pages (task T301615).
- Syntax highlighting of definition lists (task T170042).
- Bracket matching for CJK full-width brackets (task T362992).
- Ctrl+⧠Shift+X (or â Cmd+⧠Shift+X on Mac) changes the directionality of the text (task T170001).
Bug fixes
[edit]- Highlighting table captions with attributes (task T324374).
- Highlighting indented tables (task T108454).
- 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
[edit]- 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 (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
[edit]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
[edit]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.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 |
N/A | ext.CodeMirror.v6.init
|
ext.CodeMirror.v6.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.visualEditor
|
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
[edit]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
[edit]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
[edit]MediaWiki Extensions
[edit]Registering a new tag for MediaWiki
[edit]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
[edit]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
[edit]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
[edit]Using jQuery.textSelection
[edit]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
[edit]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();
} );
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.
|
ext.CodeMirror.visualEditor.init
|
CodeMirror integration with the 2017 wikitext editor , and only for wikitext. |
Using hooks
[edit]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.
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
|
ext.CodeMirror.ready
|
Called just after CodeMirror is initialized.
Parameters
|
ext.CodeMirror.destroy
|
Called just after CodeMirror is destroyed and the original textarea is restored.
Parameters
|
ext.CodeMirror.switch
|
Called after CodeMirror has been enabled or disabled in WikiEditor.
Parameters
|
ext.CodeMirror.input
|
Called when document changes are made in CodeMirror. Note that the textarea may not be updated yet.
Parameters
|
Extending CodeMirror
[edit]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
[edit]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 );
} );
See also
[edit]- User:Remember the dot/Syntax highlighter
- Extension:VisualEditor
- Extension:WikiEditor
- Extension:CodeEditor
- c:Category:MediaWiki extension CodeMirror
Notes
[edit]- â Line wrapping cannot be disabled in the 2017 editor.
This extension is being used on one or more Wikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's CommonSettings.php and InitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's Special:Version page. |
This extension is included in the following wiki farms/hosts and/or packages: This is not an authoritative list. Some wiki farms/hosts and/or packages may contain this extension even if they are not listed here. Always check with your wiki farms/hosts or bundle to confirm. |
- Stable extensions
- User interface extensions
- GPL licensed extensions
- Extensions in Wikimedia version control
- EditPage::showEditForm:initial extensions
- EditPage::showReadOnlyForm:initial extensions
- GetBetaFeaturePreferences extensions
- GetPreferences extensions
- ResourceLoaderGetConfigVars extensions
- All extensions
- Extensions used on Wikimedia
- Extensions included in Canasta
- Extensions included in Fandom
- Extensions included in Miraheze
- Extensions included in MyWikis
- Extensions included in ProWiki
- Extensions included in Telepedia
- Extensions included in wiki.gg
- Extensions included in WikiForge
- Syntax highlighting extensions