Upgrading to version 3

Version 3 does not depart too much from 2.x API, and sites that use
CodeMirror in a very simple way might be able to upgrade without
trouble. But it does introduce a number of incompatibilities. Please
at least skim this text before upgrading.

Note that version 3 drops full support for Internet
Explorer 7. The editor will mostly work on that browser, but
it'll be significantly glitchy.

DOM structure

This one is the most likely to cause problems. The internal
structure of the editor has changed quite a lot, mostly to implement a
new scrolling model.

Editor height is now set on the outer wrapper element (CSS
class CodeMirror), not on the scroller element
(CodeMirror-scroll).

Other nodes were moved, dropped, and added. If you have any code
that makes assumptions about the internal DOM structure of the editor,
you'll have to re-test it and probably update it to work with v3.

Gutter model

In CodeMirror 2.x, there was a single gutter, and line markers
created with setMarker would have to somehow coexist with
the line numbers (if present). Version 3 allows you to specify an
array of gutters, by class
name,
use setGutterMarker
to add or remove markers in individual gutters, and clear whole
gutters
with clearGutter.
Gutter markers are now specified as DOM nodes, rather than HTML
snippets.

The gutters no longer horizontally scrolls along with the content.
The fixedGutter option was removed (since it is now the
only behavior).

Event handling

Most of the onXYZ options have been removed. The same
effect is now obtained by calling
the on method with a string
identifying the event type. Multiple handlers can now be registered
(and individually unregistered) for an event, and objects such as line
handlers now also expose events. See the
full list here.

(The onKeyEvent and onDragEvent options,
which act more as hooks than as event handlers, are still there in
their old form.)

markText method arguments

The markText method
(which has gained some interesting new features, such as creating
atomic and read-only spans, or replacing spans with widgets) no longer
takes the CSS class name as a separate argument, but makes it an
optional field in the options object instead.

Bracket matching no longer in core

The matchBrackets
option is no longer defined in the core editor.
Load addon/edit/matchbrackets.js to enable it.

Mode management

The CodeMirror.listModes
and CodeMirror.listMIMEs functions, used for listing
defined modes, are gone. You are now encouraged to simply
inspect CodeMirror.modes (mapping mode names to mode
constructors) and CodeMirror.mimeModes (mapping MIME
strings to mode specs).

New features

Some more reasons to upgrade to version 3.

Bi-directional text support. CodeMirror will now mostly do the
right thing when editing Arabic or Hebrew text.

Arbitrary line heights. Using fonts with different heights
inside the editor (whether off by one pixel or fifty) is now
supported and handled gracefully.