*emmet.txt* *Emmet* for Vim ------------------------------------------------------- Emmet: vim plugins for HTML and CSS hi-speed coding ------------------------------------------------------- Author: Yasuhiro Matsumoto WebSite: http://mattn.kaoriya.net/ Repository: https://github.com/mattn/emmet-vim Site: https://mattn.github.com/emmet-vim License: BSD style license ============================================================================== CONTENTS *emmet-contents* Introduction |emmet-introduction| Install |emmet-install| Tutorial |emmet-tutorial| 1. Expand abbreviation |emmet-expand-abbr| |,| 2. Wrap with abbreviation |emmet-wrap-with-abbreviation| |v_,| 3. Balance tag inward |emmet-balance-tag-inward| |d| 4. Balance tag outward |emmet-balance-tag-outward| |D| 5. Go to next edit point |emmet-goto-next-point| |n| 6. Go to previous edit point |emmet-goto-previous-point| |N| 7. Add and update size |emmet-update-image-size| |i| 8. Merge lines |emmet-merge-lines| |m| 9. Remove tag |emmet-remove-tag| |k| 10. Split/join tag |emmet-split-join-tag| |j| 11. Toggle comment |emmet-toggle-comment| |/| 12. Make anchor from URL |emmet-make-anchor-url| |a| 13. Make quoted text from URL |emmet-quoted-text-url| |A| 14. Code pretty |emmet-code-pretty| |c| 15. Lorem ipsum |emmet-lorem-ipsum| HTML expression syntax |emmet-html-expression-syntax| 1. Elements |emmet-html-syntax-elements| 2. Nesting operators |emmet-html-syntax-nesting-operators| 2.1. Child |emmet->| 2.2. Sibling |emmet-+| 2.3. Climb-up |emmet-^| 2.4. Multiplication |emmet-star| 2.5. Grouping |emmet-()| 3. Attribute operators |emmet-html-syntax-attribute-operators| 3.1. ID and CLASS |emmet-.| |emmet-#| 3.2. Custom attributes |emmet-[]| 3.3. Item numbering |emmet-$| 3.3.1. Changing numbering origin and direction |emmet-@| 3.4. Quote character |emmet-html-attr-quote-char| 4. Text |emmet-{}| 5. Implicit tag names |emmet-html-implicit-tag-names| 6. Notes on abbreviation formatting |emmet-html-syntax-notes| 7. Choose position to insert text when wrap abbreviation |emmet-$#| CSS expression syntax |emmet-css-expression-syntax| 1. Properties |emmet-css-properties| 2. Values |emmet-css-values| 3. Units |emmet-css-units| 4. Vendor prefixes |emmet-css-vendor-prefixes| Commands |emmet-commands| :Emmet |:Emmet| :EmmetInstall |:EmmetInstall| Variables |emmet-variables| g:emmet_html5 |g:emmet_html5| g:emmet_docroot |g:emmet_docroot| g:emmet_curl_command |g:emmet_curl_command| g:user_emmet_complete_tag |g:user_emmet_complete_tag| g:user_emmet_leader_key |g:user_emmet_leader_key| g:user_emmet_install_global |g:user_emmet_install_global| g:user_emmet_install_command |g:user_emmet_install_command| g:user_emmet_settings |g:user_emmet_settings| g:user_emmet_mode |g:user_emmet_mode| Customize |emmet-customize| 1. Key mappings |emmet-customize-key-mappings| 2. Indent size |emmet-indent-size| 3. Define tag's behavior |emmet-define-tags-behavior| 4. Adding custom snippets |emmet-custom-snippets| Filters |emmet-filters-list| Escapes XML-unsafe characters |emmet-filter-e| Add comments around 'important tags' |emmet-filter-c| Outputs as a single line |emmet-filter-s| Trim list markers |emmet-filter-t| Links |emmet-links| ToDo |emmet-todo| ============================================================================== INTRODUCTION *emmet-introduction* *emmet* Emmet is an editor plugin for high-speed HTML, XML, XSL (or any other structured code format) coding and editing. The core of this plugin is a powerful abbreviation engine which allows you to expand expressions, similar to CSS selectors, into HTML code: > div#page>div.logo+ul#navigation>li*5>a < can be expanded into: >
< Read more about current Emmet syntax |emmet-html-expression-syntax| |emmet-css-expression-syntax| http://docs.emmet.io/abbreviations/ Abbreviation engine has a modular structure which allows you to expand abbreviations into different languages. Emmet currently supports CSS, HTML, XML/XSL and HAML, Slim languages via filters (see |emmet-filter|). ============================================================================== INSTALL *emmet-install* Install the distributed files into Vim runtime directory which is usually '~/.vim/', or '$HOME/vimfiles' on Windows. If you install pathogen (https://github.com/tpope/vim-pathogen) that provided by Tim Pope, you should extract the file into 'bundle' directory. ============================================================================== TUTORIAL *emmet-tutorial* If you are seeing this file as :help, then you can't edit this file. You should copy this section and create new buffer, paste and write as 'emmet-tutor.txt'. Formally, open the file to start tutorial. 1. Expand abbreviation *emmet-expand-abbr* *,* Type abbreviation as 'div>p#foo$*3>a' and type ','. >

< 2. Wrap with abbreviation *emmet-wrap-with-abbreviation* *v_,* Write as below. > test1 test2 test3 < Then do visual select (line wise) and type ','. If you request 'Tag:', then type > ul>li* < Result: >
  • test1
  • test2
  • test3
< If you type tag name, for example > blockquote < then you'll see as following: >
test1 test2 test3
< See also: |emmet-filter-t|, |emmet-$#| 3. Balance tag inward *emmet-balance-tag-inward* *d* To select inward of '
    ' tag, type 'd' in insert mode. >
      *
    < If cursor is at '*', 'd' select from begin of '
      ' to end of '
    '. If cursor is at first of '
  • ', it select '
  • '. 4. Balance tag outward *emmet-balance-tag-outward* *D* To select outward of '
      ' tag type 'D' in insert mode. >
        *
      < If cursor is at '*', 'D' select from next letter of '
        ' to previous letter of '
      '. If cursor is at first of '
    • ', it select '
    • '. 5. Go to next edit point *emmet-goto-next-point* *n* To jump next point that need to edit, type 'n' in insert mode. > *
      foo
      < If cursor is at '*', type 'n' to move a cursor into attribute value of '
      ' specified id as 'foo'. And type again 'n' to move a cursor into inner of '
      ' specified id as 'bar'. 6. Go to previous edit point *emmet-goto-previous-point* *N* To jump previous point that need to edit, type 'N' in insert mode. >
      foo
      * < If cursor is at '*', type 'N' to move a cursor into '
      ' specified id as 'bar'. And type again 'N' to move a cursor into attribute value of 'foo'. 7. Add and update size *emmet-update-image-size* *i* To add or update 'width' and 'height' attributes of image, type 'i' on '' tag > < Type 'i' on '' tag > < If you change image, then type it again. it will be following. > < Image size retrieved using 'identify' (ImageMagick.org) (if available) or |xxd|. 8. Merge lines *emmet-merge-lines* *m* To join multi line text like following, type |J|. >
      < If you select part of line include '
    • ' and type |m|, it will be following. >
      < 9. Remove tag *emmet-remove-tag* *k* To remove tag in the block, type 'k'. > < Type 'k' in insert mode, then >
      < And type 'k' in there again, then '
      ' will be removed. 10. Split/join tag *emmet-split-join-tag* *j* To join block, type 'j'. >
      cursor is here
      < Type 'j' in insert mode. Then, >
      < And type 'j' in there again. >
      < 11. Toggle comment *emmet-toggle-comment* */* Move cursor to block >
      hello world
      < Type '/' in insert mode. > < Type '/' in there again. >
      hello world
      < 12. Make anchor from URL *emmet-make-anchor-url* *a* Move cursor to URL > http://www.google.com/ < Type 'a' > Google < Text retrieved using command, specified by |g:emmet_curl_command|. 13. Make quoted text from URL *emmet-quoted-text-url* *A* Move cursor to URL > https://github.com/ < Type 'A' >
      Secure source code hosting and collaborative development - GitHub

      How does it work? Get up and running in seconds by forking a project, pushing an existing repository...

      https://github.com/
      < Text retrieved using command, specified by |g:emmet_curl_command|. 14. Code pretty *emmet-code-pretty* *c* Select code block, for example select following code from 'int main()'. >

      Writing in C language

      int main() { puts("hello world"); } < Type 'c' > int main() {
        puts("hello world");
      }
      < To convert text into html used command |:TOhtml|. 15. Lorem ipsum *emmet-lorem-ipsum* To insert dummy text (30 words by default). > div>lorem < Type |,| >
      Adipisicing asperiores deleniti ipsum fuga deserunt perferendis molestiae sunt excepturi aut quo nihil! Optio accusantium corporis molestiae deserunt ab, veritatis commodi. Eius nobis ab deserunt magni iure quo laboriosam laboriosam.
      < For japanese user, put like follow into your |g:user_emmet_settings|: > let g:user_emmet_settings = { ... \ 'custom_expands1' : { \ '^\%(lorem\|lipsum\)\(\d*\)$' : function('emmet#lorem#ja#expand'), \ }, ... < You will get japanese dummy text. Text retrieved from url 'http://www.aozora.gr.jp/cards/000081/files/470_15407.html' using command, specified by |g:emmet_curl_command|. To insert 3 words of dummy text. > div>lorem3 < Type |,| >
      Elit libero id.
      < ============================================================================== HTML EXPRESSION SYNTAX *emmet-html-expression-syntax* Emmet uses syntax similar to CSS selectors for describing elements' positions inside generated tree and elements' attributes. 1. Elements *emmet-html-syntax-elements* You can use elements' names like 'div' or 'p' to generate HTML tags. > p ->

      div ->
      < You can write any word and transform it into a tag: > foo -> bar -> < Emmet knowns set of empty elements: > br ->
      or
      meta -> or < To choose between HTML '>' and XHTML ' />' use |g:emmet_html5| or |g:user_emmet_settings|: > let g:user_emmet_settings = { \ ... \ 'html': { \ ... \ 'empty_element_suffix': ' />', \ ... \ }, \ ... \} < Emmet will automatically insert some attributes: > a -> link -> < Set of inserted attributes can be changed using |g:user_emmet_settings|: > let s:emmet_settings = { \ ... \ 'html': { \ ... \ 'default_attributes': { \ ... \ 'a': {'href': ''}, \ 'ins': {'datetime': '${datetime}'}, \ 'iframe': [{'src': ''}, {'frameborder': '0'}], \ 'textarea': [{'name': ''}, {'id': ''}, {'cols': '30'}, {'rows': '10'}], \ ... \ }, \ ... \ }, \ ... \} < 2. Nesting operators *emmet-html-syntax-nesting-operators* Nesting operators are used to position abbreviation elements inside generated tree: whether it should be placed inside or near the context element. Operator Description Link ~ > Child |emmet->| + Sibling |emmet-+| ^ Climb-up |emmet-^| * Multiplication |emmet-star| () Grouping |emmet-()| 2.1. Child *emmet->* You can use '>' operator to nest elements inside each other: > div>ul>li < will produce >
      < 2.2. Sibling *emmet-+* Use '+' operator to place elements near each other, on the same level: > div+p+bq < will output >

      < 2.3. Climb-up *emmet-^* With '>' operator you're descending down the generated tree and positions of all sibling elements will be resolved against the most deepest element: > div+div>p>span+em < will be expanded to >

      < With '^' operator, you can climb one level up the tree and change context where following elements should appear: > div+div>p>span+em^bq < outputs to >

      < You can use as many '^' operators as you like, each operator will move one level up: > div+div>p>span+em^^^bq < will output to >

      < 2.4. Multiplication *emmet-star* With '*' operator you can define how many times element should be outputted: > ul>li*5 < outputs to >
      < Expression may contain several '*' operators: > tr*2>td*3 < become > < 2.5. Grouping *emmet-()* Parentheses '()' are used by Emmets' power users for grouping subtrees in complex abbreviations: > div>(header>ul>li*2>a)+footer>p < expands to >

      < If you're working with browser's DOM, you may think of groups as Document Fragments: each group contains abbreviation subtree and all the following elements are inserted at the same level as the first element of group. You can nest groups inside each other and combine them with multiplication '*' operator: > (div>dl>(dt+dd)*3)+footer>p < produces >

      < With groups, you can literally write full page mark-up with a single abbreviation, but please don't do that. 3. Attribute operators *emmet-html-syntax-attribute-operators* Attribute operators are used to modify attributes of outputted elements. For example, in HTML and XML you can quickly add 'class' attribute to generated element. Operator Description Link ~ . Attribute 'class' |emmet-.| # Attribute 'id' |emmet-#| [] Custom attributes |emmet-[]| $ Number |emmet-$| @ Number origin and direction |emmet-@| 3.1. ID and CLASS *emmet-.* *emmet-#* In CSS, you use 'elem#id' and 'elem.class' notation to reach the elements with specified 'id' or 'class' attributes. In Emmet, you can use the very same syntax to add these attributes to specified element: > span.class1 -> span.class1.class2 -> div#wrapper ->
      div#wrapper.content ->
      < More complex expression: > div#header+div.page+div#footer.class1.class2.class3 < will output >
      < 3.2. Custom attributes *emmet-[]* You can use '[attr]' notation (as in CSS) to add custom attributes to your element: > td[title="Hello world!" colspan=3] < outputs > < You can place as many attributes as you like inside square brackets. Attribute values may be omitted: > td[colspan title] < will produce > < You can use single or double quotes for quoting attribute values. > div[a='value1' b="value2"] < become >
      < You don't need to quote values if they don't contain spaces: > td[title=hello colspan=3] < will output > < 3.3. Item numbering *emmet-$* With multiplication '*' operator you can repeat elements, but with '$' you can number them. Place '$' operator inside element's name, attribute's name or attribute's value to output current number of repeated element: > ul>li.item_$*5 < outputs to >
      < You can use multiple '$' in a row to pad number with zeroes: > ul>li.item_$$$*5 < outputs to >
      < Also '$' can be used in element name and in text (|emmet-{}|): > h$[title=item$]{Header $}*3 < transformed to >

      Header 1

      Header 2

      Header 3

      < 3.3.1. Changing numbering origin and direction *emmet-@* With '@' modifier, you can change - numbering direction (ascending or descending) and - origin (i. e. start value). For example, to change direction, add '@-' after '$': > ul>li.item_$@-*5 < outputs to >
      < To change counter origin value, add '@N' modifier to '$': > ul>li.item_$@3*5 < transforms to >
      < You can use these modifiers together: > ul>li.item_$@-3*5 < is transformed to >
      > 3.4. Quote character *emmet-html-attr-quote-char* |g:user_emmet_settings| may be used to change attribute quote character: > let g:user_emmet_settings = { ... \ 'html' : { ... \ 'quote_char': "'", ... \ }, ... \} < Then abbreviation > a[target=_blank] < will expand to > < instead of > < Default quote is '"'. 4. Text *emmet-{}* You can use curly braces to add text to element: > a{Click me} < will produce > Click me < Note that '{text}' is used and parsed as a separate element (like, 'div', 'p' etc), but has a special meaning when written right after element. For example, > a{click} < and > a>{click} < will produce the same output, but > a{click}+b{here} < and > a>{click}+b{here} < won't: > clickhere clickhere < In second example the '' element is placed inside '' element. And that's the difference: when '{text}' is written right after element, it doesn't change parent context. Here's more complex example showing why it is important: > p>{Click }+a{here}+{ to continue} < produces >

      Click here to continue

      < In this example, to write 'Click here to continue' inside '

      ' element we have explicitly move down the tree with '>' operator after 'p', but in case of 'a' element we don't have to, since we need '' element with here word only, without changing parent context. For comparison, here's the same abbreviation written without child '>' operator: > p{Click }+a{here}+{ to continue} < produces >

      Click

      here to continue < 5. Implicit tag names *emmet-html-implicit-tag-names* Even with such a powerful abbreviation engine, which can expand large HTML structures from short abbreviation, writing tag names may be very tedious. In many cases you can skip typing tag names and Emmet will substitute it for you. For example, instead of > div.content < you can simply write > .content < and expand it into >
      < Other examples: > .wrapper ->
      #popup -> < When you expand abbreviation, Emmet tries to grab parent context, e. g. the HTML element, inside which you're expanding the abbreviation. If the context was grabbed successfully, Emmet uses its name to resolve implicit names. Emmet looks at the parent tag name every time you're expanding the abbreviation with an implicit name. Here's how it resolves the names for some parent elements: Inserted element Parent elements ~ li ul, ol tr table, tbody, thead, tfoot td tr option select, optgroup span Inline elements div Block elements Take a look at some abbreviations equivalents with implicit and explicit tag names: > .wrap>.content -> div.wrap>div.content em>.info -> em>span.info ul>.item*3 -> ul>li.item*3 table>.row>.col -> table>tr.row>td.col table>#row$*4>[colspan=2] -> table>tr#row$*4>td[colspan=2] < 6. Notes on abbreviation formatting *emmet-html-syntax-notes* When you get familiar with Emmet's abbreviations syntax, you may want to use some formatting to make your abbreviations more readable. For example, use spaces between elements and operators, like this: > (header > ul.nav > li*5) + footer < But it won't work, because space is a stop symbol where Emmet stops abbreviation parsing. Many users mistakenly think that each abbreviation should be written in a new line, but they are wrong: you can type and expand abbreviation anywhere in the text: This is why Emmet needs some indicators (like spaces) where it should stop parsing to not expand anything that you don't need. If you're still thinking that such formatting is required for complex abbreviations to make them more readable: - abbreviations are not a template language, they don't have to be "readable", they have to be "quickly expandable and removable"; - you don't really need to write complex abbreviations. Stop thinking that "typing" is the slowest process in web-development. You'll quickly find out that constructing a single complex abbreviation is much slower and error-prone than constructing and typing a few short ones. 7. Choose position to insert text when wrap abbreviation *emmet-$#* When wrap abbreviation (|emmet-wrap-with-abbreviation|) you can choose position to insert text using '$#' operator. Operator '$#' may be used only inside |emmet-[]| and/or |emmet-{}|. For example, do visual select (line wise) following text: > First Second Third < Then press ',' and type > ul>li[ title="[$#]" ]* < Result: >
      • First
      • Second
      • Third
      < You may type > input[ type=input value=$# ] < to get > < Using '$#' you can type text (|emmet-{}|) only once: > a[title=$#]{foo} < will be expanded to > foo < ============================================================================== CSS EXPRESSION SYNTAX *emmet-css-expression-syntax* 1. Properties *emmet-css-properties* Emmet has a lot of predefined snippets for CSS properties. > < become > < In above example '|' denotes a cursor (caret) position. Other examples: > t -> top: ; d -> display: ; o -> outline: ; ov -> overflow: ; cu -> cursor: ; bdrs -> border-radius: ; < '+' operator may be used to insert number of properties: > m1+p2 < become > margin: 1px; padding: 2px; < 2. Values *emmet-css-values* Some properties have default values: > c -> color: #000; bgc -> background-color: #FFF; zoo -> zoom: 1; < To insert predefined property value after abbreviation type colon ':' and first character of predefined keyword: > d:n -> display: none; d:b -> display: block; d:i -> display: inline; < Numerical value can be typed directly after abbreviation: > m10 -> margin: 10px; m2e -> margin: 2em; < Use a hyphen '-' to separate some numerical values: > m10-20 -> margin: 10px 20px; p1-2-3 -> padding: 1px 2px 3px; < To negative values precede the first value with hyphen and all the rest with double hyphens: > m-10 -> margin: -10px; m-1--2 -> margin: -1px -2px; p-2--1-0-1 -> padding: -2px -1px 0 1px; < To insert '!important' append '!' to property abbreviation: > m! -> margin: !important; bac! -> background: !important; < You can use special abbreviation 'lg(...)' to insert definition of linear gradient. Example: > lg(left, #fc0 30%, red) < will expand to > background-image: -webkit-gradient(left, 0 0, 0 100, from(#fc0 30%), to(red)); background-image: -webkit-linear-gradient(#fc0 30%, red); background-image: -moz-linear-gradient(#fc0 30%, red); background-image: -o-linear-gradient(#fc0 30%, red); background-image: linear-gradient(#fc0 30%, red); < 3. Units *emmet-css-units* By default, when you expand an abbreviation with integer value, Emmet outputs it with a 'px' unit: > bor2 -> border: 2px; fs100 -> font-size: 100px; miw20 -> min-width: 20px; < By default, if you're expanding an abbreviation with a float value, it is outputted with an 'em' unit: > fs1.5 -> font-style: 1.5em; < But you can explicitly provide the unit name by putting one of characters right after value: Character Unit ~ p % e em Examples: > fs2e -> font-style: 2em; w100p -> width: 100%; < 4. Vendor prefixes *emmet-css-vendor-prefixes* To automatically create vendor-prefixed copies of property, precede abbreviation with a hyphen '-'. For example, abbreviation > -bdrs < will be expanded into > -webkit-border-radius: ; -moz-border-radius: ; border-radius: ; < ============================================================================== COMMANDS *emmet-commands* :Emmet {expression} *:Emmet* Expand {expression} and insert result under cursor. {expression} is |emmet-html-expression|. Also see |g:user_emmet_install_command|. :EmmetInstall *:EmmetInstall* Create Emmet mappings to current buffer (|mapping|, |:map-|) and, if set |g:user_emmet_complete_tag|, change |'omnifunc'| option to emmet#completeTag() ============================================================================== VARIABLES *emmet-variables* g:emmet_html5 *g:emmet_html5* If set to 1, enable HTML 5 support: - use ">" instead of "/>": > < - omit some HTML 4 attributes: >