emmetio / codemirror-plugin

Emmet plugin for CodeMirror web editor

Emmet extension for CodeMirror editor

CodeMirror extension that adds Emmet support to text editor.

How to use

This extension can be installed as a regular npm module:

npm i @emmetio/codemirror-plugin

The package comes in two flavors: a stand-alone browser bundle and ES/CommonJS modules that you can use in your app.

If you’re building an app, you can use extension like this:

import CodeMirror from 'codemirror';
import emmet from '@emmetio/codemirror-plugin';

// Register extension on CodeMirror object
emmet(CodeMirror);

// Create editor instance and provide keymap for Emmet actions
const editor = CodeMirror.fromTextArea(document.getElementById('code'), {
    mode : "text/html",
    extraKeys: {
        'Tab': 'emmetExpandAbbreviation',
        'Esc': 'emmetResetAbbreviation',
        'Enter': 'emmetInsertLineBreak'
    }
});

For a stand-alone, basic usage, simply add dist/browser.js file into your page:

<script src="./node_modules/codemirror/lib/codemirror.js"></script>
<script src="./node_modules/@emmetio/codemirror-plugin/dist/browser.js"></script>

<form>
    <textarea id="code" name="code"></textarea>
</form>

<script>
var editor = CodeMirror.fromTextArea(document.getElementById("code"), {
    mode : "text/html",
    extraKeys: {
        'Tab': 'emmetExpandAbbreviation',
        'Esc': 'emmetResetAbbreviation',
        'Enter': 'emmetInsertLineBreak'
    }
});
</script>

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:

Run emmetExpandAbbreviation command to expand tracked abbreviation or emmetResetAbbreviation to reset it. Suggested key bindings are Tab for emmetExpandAbbreviation and Esc for emmetResetAbbreviation.

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.

If you already have abbreviation in editor, you can capture it to continue editing: run emmetCaptureAbbreviation action (Ctrl-Space by default):

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 emmetEnterAbbreviationMode command to enter this mode: everything user types will be tracked as abbreviation with preview and validation. Use emmetExpandAbbreviation command to expand it or emmetResetAbbreviation to quit abbreviation mode.

JSX abbreviation

In order to not distract user with unexpected abbreviation tracking, in JSX syntax Emmet requires to prefix abbreviation with < to provide more natural context where JSX markup is required.

Tag pair marking and renaming

Extension is able to mark paired open and close HTML tags in editor: it adds emmet-class-tag and emmet-close-tag name to matched tag names. Optionally, extension can display preview of matching open tag when cursor is inside close tag.

When tag pair tag marking is enabled, it’s possible to automatically rename tag pair when you update open or close tag:

Commands

The package itself follows CodeMirror extension convention and registers new commands in CodeMirror namespace. In order to use Emmet, you should create CodeMirror instance and provide keymap with the following Emmet actions:

• emmetExpandAbbreviation – expand tracked abbreviation from current cursor position (see Expanding abbreviations).
• emmetResetAbbreviation – reset tracked abbreviation in editor (see Expanding abbreviations).
• emmetEnterAbbreviationMode – enters abbreviation mode.
• emmetInsertLineBreak – inserts formatted line break if cursor is between tags.
• emmetExpandAbbreviationAll – expands abbreviation from current cursor position. Unlike emmetExpandAbbreviation, it doesn’t require tracked abbreviation: it extracts abbreviation from current cursor position and can be used in any document syntax.
• emmetWrapWithAbbreviation — Wrap with Abbreviation.
• emmetBalance/emmetBalanceInward — Balance.
• emmetToggleComment — Toggle Comment
• emmetEvaluateMath — Evaluate Math Expression
• emmetGoToNextEditPoint/emmetGoToPreviousEditPoint — Go to Edit Point
• emmetGoToTagPair — Go to Matching Pair
• emmetIncrementNumberN/emmetDecrementNumberN — Increment/Decrement Number where N is 1, 01 or 10.
• emmetRemoveTag — Remove Tag
• emmetSplitJoinTag — Split/Join Tag
• emmetSelectNextItem/emmetSelectPreviousItem — Select Item

Options

You can pass emmet object when creating CodeMirror editor instance to modify extension behavior:

CodeMirror.fromTextArea(document.getElementById("code"), {
    mode : "text/html",
    lineNumbers : true,

    // Pass Emmet extension options
    emmet: {
        mark: true,
        markTagPairs: true,
        previewOpenTag: false,
    }
});

Extension supports the following options:

• mark (boolean or string[]): enables abbreviation tracking and marking in editor. If true is provided, it will work in all known syntaxes. You can specify array of syntaxes/modes where abbreviation marking should work; array may include markup or stylesheet keyword to enable option for all known markup or stylesheet syntaxes.
• preview (boolean or string[]): enable preview of tracked abbreviation. Preview is displayed only when abbreviation will expand in more than one element. Same as with mark option, you can enable it for all syntaxes (true) or limit it to specified syntaxes or syntax groups.
• markTagPairs (boolean): enable HTML tag pair marking in editor.
• previewOpenTag (boolean): displays open tag preview when cursor is inside its matching closing tag. Preview is displayed only if open tag has attributes and works only if markTagPairs is enabled
• autoRenameTags (boolean): automatically rename tag pair when updating open or close tag name. Works only if markTagPairs is enabled.
• attributeQuotes ('single' or 'double'): quotes to use in generated HTML attribute values. Default is 'double'.
• markupStyle ('html', 'xhtml' or 'xml'): style for self-closing elements (like <br>) and boolean attributes in HTML syntax.
• comments (boolean): enable automatic tag commenting. When enabled, elements generated from Emmet abbreviation with id and/or class attributes will receive a comment with these attribute values.
• commentsTemplate (string): commenting template. Default value is \n<!-- /[#ID][.CLASS] -->. Outputs everything between [ and ] only if specified attribute name (written in UPPERCASE) exists in element. Attribute name is replaced with actual value. Use \n to add a newline.
• bem (boolean): enable BEM support. When enabled, Emmet will treat class names starting with - as element and with _ as modifier in BEM notation. These class names will inherit block name from current or ancestor element. For example, the abbreviation ul.nav.nav_secondary>li.nav__item can be shortened to ul.nav._secondary>li.-item when this option enabled.
• config (object): Emmet config with snippets and advanced options.

Emmet config

With config option (see above) you can add custom abbreviation snippets and fine-tune Emmet behavior.

Snippets are grouped by syntax (like html, css, pug etc.) and syntaxes are grouped by type: markup or stylesheet. You can specify snippets that should be available for all syntaxes in group or specific syntax only.

Snippets are just short aliases for Emmet abbreviations: you either specify shorthand for a larger abbreviation or define shape for a specific element:

CodeMirror.fromTextArea(document.getElementById("code"), {
    mode : "text/html",
    lineNumbers : true,

    // Pass Emmet extension options
    emmet: {
        config: {
            // Specify snippets for all markup syntaxes: HTML, XML, Pug etc.
            markup: {
                // Shorthand for larger abbreviation
                foo: 'div.foo>section.bar*3',

                // Define shape of element, looks like recursive abbreviation
                a: 'a[href title]',
                br: 'br/'
            },

            // Specify snippets for specific syntax only
            html: {
                nav: 'ul.nav>.nav-item*4>a'
            }
        }
    }
});

Note that markup and stylesheet snippet definitions are different. Markup snippets are written as Emmet abbreviations (e.g. you simply describe element name and its default attributes) while stylesheet snippets are aliases to CSS properties with optional keywords list, separated by | character. These keywords are used in abbreviation resolving process. For more examples, see check out default Emmet snippets.

See all available config params in GlobalConfig type.

codemirror-plugin's Issues

Minifying with uglify fails because build doesn't target ES5

I'm attempting to use this project in a project that uses Create React App, which uses Uglify when building. When I try to build I get the following error message

Failed to compile.

Failed to minify the code from this file: 

        ./node_modules/@emmetio/stream-reader/dist/stream-reader.es.js:4 

Read more here: http://bit.ly/2tRViJ9

The link in the error message is very instructive and explains the issue well. Basically Uglify needs code that is compiled to ES5 to work and codemirror-plugin doesn't do this

I have already forked codemirror-plugin and its dependencies and have begun the process of modifying them to target ES5, but it's slow going because I'm not familiar with rollup or mocha and I'm unable to get any of the tests to pass and I don't know if what I have at the end of it will be good enough to merge into this project.

Pasting a URL, Emmet Throws Expansion Error

After pressing Tab it doesn't remove the symbol itself.

If I enter "p" + Tab it gives: '

p' . Is there anything wrong with the settings? Thanks.

Codemirror 6

Are there any plans to support codemirror 6?

No 'dist' folder

Repository didn't contains a 'dist' folder, how can i make emmet work on codemirror then?

CodeMirror 5 + Sublime Text Key Bindings + Multiple Selections =

So Command-D in "normal" emmet does outward-expansion. But in CodeMirror, if you turn on the official Sublime Text bindings:

https://codemirror.net/demo/sublime.html

Then Command-D gets replaced with "select next occurrence" (selectNextOccurrence).

Because CodeMirror supports multiple selections/multiple cursors, that means you don't just have the original selection, but it keeps adding to the selection.

That's all fine, and so far working as expected:

CleanShot.2021-06-22.at.05.52.22.mp4

But that's without Emmet.

I would test it here, but this demo doesn't have Sublime Text bindings on:

https://download.emmet.io/codemirror/index.html

On CodePen, we do (you have to turn on Sublime Text bindinds, and Emmet, in Editor Preferences).

When BOTH are active, in HTML specifically, something gets funky with line positions. You can see here:

CleanShot.2021-06-22.at.05.54.24.mp4

It looks like maybe Emmet's tag-matching thing is catching the second-and-beyond selection?

the plugin does not work well

It's been a while since the plugin looks like this and I don't know why

this is my package.json

my code is exactly the same as shown in their documentation

Custom Snippet Breakage

A user of CodePen found that if you make a custom snippet that is essentially:

"gt": "grid-template: repeat(2,auto) / repeat(auto-fit, minmax(250px, 1fr))"

Emmet 2 doesn't expand that but instead moves focus out of the editor.

abbreviation preview doesn't work

I have a project using codemirror and emmetio which uses some other functionality from codemirror.
The preview of abbreviation does not show up.
I have tried removing all extra functinality except for syntax highlighting and sublime however that did not work (emmet didn't even work at all without syntax highlighting)

there are no errors and i can use emmet as usual just without the preview.

help?

Preview not close on change instance

I working with codemirror 5.2 and stand alone mode with Browser.js
I suggest add the events swapDoc and Blur
editor.on('blur', () => proxy.hidePreview()); editor.on('swapDoc', () => proxy.hidePreview());
Any suggestions?

Unable to consume abbreviation node, unexpected 60 at char 5

How i can fix or avoid this warning?

Snippets with Multiple Cursors

CodeMirror supports multiple cursors, so Emmet snippets could too!

Like:

width: ${1};\nheight: ${1};

Emmet html5

Hello,
I to try generate html5 (!+tab), but get code:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Document</title>
</head>
<body>
  
</body>
</html>

How to get code like this?

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Document</title>
</head>
<body>
    
</body>
</html>

Tab-expanding dash-separated properties

If you TAB after a fully-written CSS property, it has weird effects:

body {
  background-color[CURSOR]
}

Then press tab, you get:

body {
  background: color;
}

Which is pretty weird, you'd think it would either do nothing since it's already expanded, or give you the more complete syntax like:

body {
  background-color: #fff;
}

Invalid preview trigger on uppercased word

Typing Uppercase word incorrectly triggers abbreviation preview

react-codemirror2

please show me how to connect it with react-codemirror2. I make mistakes...

This Combo Freezes the Browser

1. Put <div>1</div> in the HTML
2. Select characters >1</div with cursor
3. Hit Backspace
4. The page stops responding and finally crashes with error "Out of Memory"

Can reproduce at http://download.emmet.io/codemirror/index.html

Adding Emmet to already initialized CodeMirror

Hello,

I'm coding a chrome extension to Shopify to add emmet to the built-in online editor.

The CodeMirror editor in there is already initialized and I'm grabbing it as so:

var $cm = document.querySelector('.CodeMirror').CodeMirror;

How could I initialize emmet using this existing instance without FromTextArea?

Thanks!