Jump to content

Help:Extension:CodeMirror

From mediawiki.org

The CodeMirror extension provides syntax highlighting in wikitext editors. This can make editing easier by using colors and shading to visually separate plain text from links, templates, and other wikitext markup.

Usage

[edit]

Enabling

[edit]

CodeMirror can be enabled by setting "Enable syntax highlighting for wikitext" in your preferences. In WikiEditor (also known as the 2010 editor, enabled with the "Enable the editing toolbar" preference), it can also be toggled on and off using the highlighter button " Syntax" in the toolbar. In the 2017 editor, you can toggle CodeMirror by clicking the "Page options" button in the toolbar, then selecting "Syntax highlighting".

Keyboard shortcuts

[edit]
These keyboard shortcuts do not apply to the 2017 editor, which has its own set of keyboard shortcuts. Those can be reviewed by pressing Ctrl+/ while the editor is open.
Shortcut Shortcut (macOS) Description
Alt+ Ctrl+ Move the cursor one word to the left.
Alt+ Ctrl+ Move the cursor one word to the right.
Alt+ Alt+ Move the selected lines up one line.
Alt+ Alt+ Move the selected lines down one line.
⇧ Shift+Alt+ ⇧ Shift+Alt+ Duplicate the selected lines and keep the selection on the top copy.
⇧ Shift+Alt+ ⇧ Shift+Alt+ Duplicate the selected lines and keep the selection on the bottom copy.
Escape Escape Reduce multiple selections to the main range, or to a cursor if there is only one selection.
Ctrl+↵ Enter ⌘ Command+↵ Enter Insert a blank line below the current line.
Ctrl+[ ⌘ Command+[ Remove indentation from the selected lines.
Ctrl+] ⌘ Command+] Add indentation to the selected lines.
Ctrl+⇧ Shift+[ ⌘ Command+Alt+[ Fold the currently selected templates.
Ctrl+⇧ Shift+] ⌘ Command+Alt+] Unfold the any folded templates in the selection.
Ctrl+Alt+[ Ctrl+Alt+[ Fold all templates on the page.
Ctrl+Alt+] Ctrl+Alt+] Unfold all templates that are currently folded.
Ctrl+f ⌘ Command+f Open the search panel.
Ctrl+g ⌘ Command+g Find the next occurrence of the search string.
⇧ Shift+Ctrl+g ⇧ Shift+⌘ Command+g Find the previous occurrence of the search string.
Ctrl+d ⌘ Command+d Select the next occurrence of the current selection or word, creating multiple selections.
Ctrl+click ⌘ Command+click Add an additional cursor or selection to the area clicked.
Ctrl+⇧ Shift+X ⌘ Command+⇧ Shift+X Toggle viewing the editor in right-to-left and left-to-right.
Ctrl+⇧ Shift+, ⌘ Command+⇧ Shift+, Open the CodeMirror preferences panel.

Features

[edit]

CodeMirror preferences

[edit]
MediaWiki version:
1.44
This feature is not available for the 2017 editor.

Most features documented here can be disabled or enabled by individual users. To open the preferences panel, press Ctrl+⇧ Shift+, (or ⌘ Command+⇧ Shift+, on MacOS). If you use WikiEditor , you can also get to your CodeMirror preferences by clicking on the button in the "Advanced" section of the toolbar. Your CodeMirror preferences will be remembered across different devices and sessions.

Bracket matching

[edit]
Bracket matching

This feature highlights the innermost pair of brackets when the cursor lies between any bracket pair. When the cursor lies directly next to a bracket, the feature highlights the corresponding matching bracket.

Template folding

[edit]
MediaWiki version:
1.43
This feature is not available for the 2017 editor.
Template folding on w:Barack Obama.

Template folding is a form of code folding for templates in wikitext. It allows you to hide all parameters and their values, showing only the template name. This can make managing large, complex templates considerably easier.

Usage

[edit]

When a cursor or selection covers any part of template syntax, a tooltip icon will appear just above the text. Clicking it will fold all parameters and values of the template, leaving only the template name.

Folded templates will have the template name followed by the ellipsis icon . Clicking on it will unfold the template back to its original state.

Keyboard shortcuts
Shortcut Shortcut (macOS) Description
Ctrl+⇧ Shift+[ ⌘ Command+Alt+[ Fold the currently selected templates.
Ctrl+⇧ Shift+] ⌘ Command+Alt+] Unfold the any folded templates in the selection.
Ctrl+Alt+[ Ctrl+Alt+[ Fold all templates on the page.
Ctrl+Alt+] Ctrl+Alt+] Unfold all templates that are currently folded.

Customization

[edit]

If you'd like to keep the keyboard shortcut for folding templates, but hide the visual component, you can do so by adding the following to your personal CSS:[1]

.cm-tooltip-fold {
	display: none;
}

Autocompletion

[edit]
MediaWiki version:
1.44
This feature is not available for the 2017 editor.
Example showing autocompletion of parser functions.

This feature provides autocompletion of magic words , parser extension tags , and URL protocols. If you enter {{#, you should see a list of all parser functions that start with #. Similarly, typing double underscores (__) will show a list of double-underscored magic words. You can continue to type to narrow your search. Use the arrow keys to select the desired text, and hit the ↵ Enter or Tab ↹ key to make your selection. Autocompletion does not work for templates, or for magic words or parser functions that do not begin with # or __.

Line numbering

[edit]
Note how the line numbering knew to account for the lines contained in the collapsed templates.

When enabled, line numbers are automatically displayed in all editors. On the Wikimedia wikis, it is only enabled for specific namespaces of specific wikis.[2]

Line numbers will take into account any hidden lines, such as those through template folding.

Highlight the active line

[edit]
MediaWiki version:
1.44
This feature is not available for the 2017 editor.

In your CodeMirror preferences, you can select "⧼codemirror-prefs-activeline⧽" to enable this feature, which can make it easier to tell which line of text the cursor is on, especially on large pages.

Line wrapping

[edit]
MediaWiki version:
1.44
This feature is not available for the 2017 editor.

Line wrapping is the default behaviour in most editors. Sometimes you may want to disable this, especially when writing complex wikitext or other code. You can disable line wrapping in your CodeMirror preferences.

Multiple cursors and selections

[edit]
This feature is not available for the 2017 editor.

You can add additional cursors or selections by holding the Ctrl key (or ⌘ Command on MacOS) and clicking on the desired content or cursor placement. After doing so, any changes you make will be applied to all the selections at the same time.

You can also press Ctrl+d (or ⌘ Command+d on MacOS) to select the next occurrence of the current selection or word, which create multiple selections. This can be useful as a quick find and replace feature.

Highlight special characters

[edit]
This feature is not available for the 2017 editor.

By default, CodeMirror will highlight non-printable control characters and other characters such as non-breaking spaces. Control characters appear as a red dot, while non-breaking spaces are displayed as a faint gray dot. Hovering over these characters will show a tooltip stating which character it is.

If desired, you can disable this feature in your CodeMirror preferences.

Colorblind mode

[edit]

For users who have difficulty distinguishing between colors, CodeMirror offers a colorblind-friendly mode. This feature can be activated on wikis with CodeMirror enabled with "Enable colorblind-friendly scheme for syntax highlighting when editing wikitext" in your preferences.

With the colorblind-friendly scheme active, the colors of the following page elements change:

Headings, symbols, signatures, section names, magic words #E4A400
Templates #9C3A00
HTML tags, references, mathematical expressions #56B4E9
Variables #009E73

In addition, background highlights and colors are removed from all text and objects. Bolding and underlining behavior remains unaffected.

Bidi isolation

[edit]
This feature is currently a work-in-progress. See phab:T358804 for more information.

On right-to-left pages, CodeMirror can isolate HTML and other tags as bidirectional text, which can improve readability. The standard algorithm for the layout of text places neutral punctuation characters between right-to-left text on the wrong side. With bidi isolation, we can correct this so it reads more legibly:

CodeMirror without bidi isolation
CodeMirror with bidi isolation

Color and style customization

[edit]
This is a partial list of the CodeMirror CSS classes. The complete list of default CodeMirror styling definitions is on Gerrit.

The colors and styles used in CodeMirror can be overridden by defining your own styles for the classes in the table below in your personal CSS.[1] Please be aware that changing some things like the line height or font size may not work in the 2017 wikitext editor.

CSS class(es) Element CodeMirror styling
.cm-mw-skipformatting leading space foo bar
.cm-mw-list asterisk or number sign * foo bar, # foo bar
.cm-mw-signature,
.cm-mw-hr
signature, horizontal rule ∼∼∼∼, ----
.cm-mw-indenting colons ::: foo bar
.cm-mw-html-entity HTML entities &
.cm-mw-comment HTML comment <!-- comment -->
.cm-mw-apostrophes-bold,
.cm-mw-apostrophes-italic
bold and italic '''bold''' ''italic''
Headings
.cm-mw-section-1 level 1 heading[3] = Heading =
.cm-mw-section-2 level 2 heading[3] == Heading ==
.cm-mw-section-3 level 3 heading === Heading ===
.cm-mw-section-4 level 4 heading ==== Heading ====
.cm-mw-section-5 level 5 heading ===== Heading =====
.cm-mw-section-6 level 6 heading ====== Heading ======
.cm-mw-section-header equal signs ==
Templates
example {{cite book|title=foo bar}}
.cm-mw-template other template content foo bar
.cm-mw-template-name template name cite book
.cm-mw-template-argument-name template parameters title=
.cm-mw-template-delimiter pipe |
.cm-mw-template-bracket opening/closing brackets {{ }}
.cm-mw-template-ground
.cm-mw-template2-ground
.cm-mw-template3-ground
whole template
(the number is the level of nesting)
{{foo|{{cite book|title=foo bar}}}}
Variables
example {{{foo|bar}}}
.cm-mw-templatevariable variable bar
.cm-mw-templatevariable-name triple-braced variable name foo
.cm-mw-templatevariable-bracket opening/closing brackets {{{ }}}
.cm-mw-templatevariable-delimiter pipe |
Parser functions
example {{#assessment: A | High }}
.cm-mw-parserfunction parser function parameters High
.cm-mw-parserfunction-name parser function name PAGENAME #invoke
.cm-mw-parserfunction-bracket opening/closing brackets {{ }}
.cm-mw-parserfunction-delimiter delimiter :
Extension tags
Note: Extension may use their own styles and rules for highlighting text within the extension tag.
example <poem style="padding: 1em;">string
whole line
string</poem>
.cm-mw-exttag text inside tags string
.cm-mw-exttag-name,
.cm-mw-ext-poem[4]
tag name poem
.cm-mw-exttag-bracket opening/closing brackets < >
.cm-mw-exttag-attribute reference attributes style="padding: 1em;"
HTML tags
example <span style="foo">foo bar</span>
.cm-mw-htmltag-name HTML tag span
.cm-mw-htmltag-bracket opening/closing brackets < >
.cm-mw-htmltag-attribute parameters and values style="foo"
superscript
subscript
foo<sup>bar</sup>
foo<sub>bar</sub>
Pre-formatted text
.cm-mw-tag-pre pre-formatted text <pre>foo bar</pre>
.cm-mw-tag-nowiki nowiki text <nowiki>foo bar</nowiki>
Internal links
example [[foo bar]] [[foo#section|bar]]
.cm-mw-link-pagename internal link target foo bar
.cm-mw-link # character #section
.cm-mw-link-tosection characters after the # #section
.cm-mw-link-bracket opening/closing brackets [[ ]]
.cm-mw-link-text link label (no additional formatting)
.cm-mw-link-delimiter pipe |
.cm-mw-pagename internal link targets foo bar
External links
example https://www.example.org
[https://www.example.org]
[https://www.example.org example.org]
.cm-mw-extlink,
.cm-mw-free-extlink
external link target www.example.org
.cm-mw-extlink-protocol,
.cm-mw-free-extlink-protocol
protocol https://
.cm-mw-extlink-text link label (no additional formatting)
.cm-mw-extlink-bracket opening/closing brackets [ ]
Tables
example {| class="wikitable"
|-
! Header text !! Header text
|-
| Example || Example
|}
.cm-mw-table-bracket opening/closing brackets and pipe {| |}
.cm-mw-table-delimiter row and column separators | |- !
.cm-mw-table-definition table classes and styles class="wikitable"
.cm-mw-table-caption caption text |+ caption
Other
.cm-mw-double-underscore magic words __TOC__
.cm-mw-list semicolon (definition lists) ;Foo:Bar
.cm-special-char-nbsp non-breaking space · ·
.cm-specialChar control characters

Notes

[edit]
  1. 1.0 1.1 Your personal CSS is at Special:MyPage/common.css. You can also make your changes take effect globally if GlobalCssJs is installed. On Wikimedia wikis, your global CSS is at meta:Special:MyPage/global.css.
  2. Controlled by the $wgCodeMirrorLineNumberingNamespaces configuration setting. See Extension:CodeMirror#Configuration for more information.
  3. 3.0 3.1 The size is not changed in the 2017 wikitext editor.
  4. Where "poem" is the name of the tag.