jasim / codemirror6-plugin

WIP Plugin for CodeMirror 6

Emmet extension for CodeMirror 6 editor

CodeMirror 6 extension that adds Emmet support to text editor.

Extension development is sponsored by Replit

---

How to use

This extension can be installed as a regular npm module:

npm i @emmetio/codemirror6-plugin

The plugin API follows CodeMirror 6 design: it’s an ES6 module and provides a number of exported extensions which you should import and add into your EditorState instance.

In most cases, this package exports Emmet actions as StateCommand, which should be used as follows:

import { EditorState, EditorView, basicSetup } from '@codemirror/basic-setup';
import { html } from '@codemirror/lang-html';
import { keymap } from '@codemirror/view';

// Import Expand Abbreviation command
import { expandAbbreviation } from '@emmetio/codemirror6-plugin';

new EditorView({
    state: EditorState.create({
        extensions: [
            basicSetup,
            html(),

            // Bind Expand Abbreviation command to keyboard shortcut
            keymap.of([{
                key: 'Cmd-e',
                run: expandAbbreviation
            }]),
        ]
    }),
    parent: document.body
});

Expanding abbreviations

Emmet extension can track abbreviations that user enters in some known syntaxes like HTML and CSS. When user enters something that looks like Emmet abbreviation, extension starts abbreviation tracking (adds emmet-abbreviation class to a text fragment). WHen abbreviation becomes complex (expands to more that one element), it displays abbreviation preview:

To enable abbreviation tracker, you should import abbreviationTracker function and add its result to editor extensions:

import { EditorState, EditorView, basicSetup } from '@codemirror/basic-setup';
import { html } from '@codemirror/lang-html';
import { abbreviationTracker } from '@emmetio/codemirror6-plugin';

new EditorView({
    state: EditorState.create({
        extensions: [
            basicSetup,
            html(),
            abbreviationTracker()
        ]
    }),
    parent: document.body
});

Abbreviation tracker is context-aware: it detect current syntax context and works only where abbreviation expected. For example, in HTML syntax it works in plain text context only and doesn’t work, for example, in attribute value or tag name.

To expand tracked abbreviation, hit Tab key while caret is inside abbreviation, or hit Esc key to reset tracker.

Abbreviation mode

In case if abbreviation tracking is unavailable or you want to give user an opportunity to enter and expand abbreviation with interactive preview, a special abbreviation mode is available. Run enterAbbreviationMode command to enter this mode: everything user types will be tracked as abbreviation with preview and validation. To expand tracked abbreviation, hit Tab key while caret is inside abbreviation, or hit Esc key to reset tracker.

Available commands

The following commands are available in current package:

• expandAbbreviation – expand abbreviation left to current caret position. Unlike abbreviation tracker, this command works anywhere and doesn’t respect current context.
• enterAbbreviationMode – enters abbreviation mode.
• wrapWithAbbreviation — Wrap with Abbreviation. Note that this is not a StateCommand but a function that you should call and pass returned result as extension. You can optionally pass keyboard shortcut as argument (Ctrl-w by default).
• balanceOutward/balanceInward — Balance.
• toggleComment — Toggle Comment
• evaluateMath — Evaluate Math Expression
• goToNextEditPoint/goToPreviousEditPoint — Go to Edit Point
• goToTagPair — Go to Matching Pair
• incrementNumberN/decrementNumberN — Increment/Decrement Number where N is 1, 01 or 10.
• removeTag — Remove Tag
• splitJoinTag — Split/Join Tag
• selectNextItem/selectPreviousItem — Select Item