Loading snippets

Snippet definitions are stored in files in the filesystem and you have to arrange for YASnippet to load them (unless you use a YASnippet bundle (see No storage (bundle)),

The non-bundle version of YASsnippet, once unpacked, comes with a full directory of snippets, which you can copy somewhere and use. You can also create or download, one or more directories.

Once these are in place reference them in the variable yas/root-directory and then load them with yas/load-directory:

;; Develop and keep personal snippets under ~/emacs.d/mysnippets
(setq yas/root-directory "~/emacs.d/mysnippets")

;; Load the snippets
(yas/load-directory yas/root-directory)

The point in using yas/root-directory (as opposed to calling yas/load-directory directly) is considering "~/emacs.d/mysnippets" for snippet development, so you can use commands like yas/new-snippet and others described here)

If you make this variable a list and store more items into it...

;; Develop in ~/emacs.d/mysnippets, but also
;; try out snippets in ~/Downloads/interesting-snippets
(setq yas/root-directory '("~/emacs.d/mysnippets"
                           "~/Downloads/interesting-snippets"))

;; Map `yas/load-directory' to every element
(mapc 'yas/load-directory yas/root-directory)

, the directories after the first are loaded, their snippets considered for expansion, but development still happens in "~/emacs.d/mysnippets"

Organizing snippets

Once you've setup yas/root-directory , you can store snippets inside subdirectories of these directories.

Common to both cases, snippet definitions are put in plain text files. They are arranged by subdirectories, and the name of these directories correspond to the Emacs mode where you want expansion to take place. For example, snippets for c-mode are put in the c-mode subdirectory. You can also skip snippet storage altogether and use the bundle (see No storage (bundle)).

Nested organization

Here is an excerpt of a directory hierarchy containing snippets for some modes:

$ tree
.
`-- text-mode
    |-- cc-mode
    |   |-- c-mode
    |   |   `-- printf
    |   |-- for
    |   |-- java-mode
    |   |   `-- println
    |   `-- while
    |-- email
    |-- perl-mode
    |   |-- cperl-mode
    |   `-- for
    `-- time

The parent directory acts as the parent mode. This is the way of YASnippet to share snippet definitions among different modes. As you can see above, c-mode and java-mode share the same parents cc-mode, while all modes are derived from text-mode. This can be also used to as an alias -- cperl-mode is an empty directory whose parent is perl-mode.

The .yas-parents file

If you place a plain text file .yas-parents inside one of the subdirectories you can bypass nesting and still have parent modes. In this file you just write whitespace-separated names of modes. This allows more flexibility and readability of your snippet hierarchy.

$ tree
.
|-- c-mode
|   |-- .yas-parents    # contains "cc-mode text-mode"
|   `-- printf
|-- cc-mode
|   |-- for
|   `-- while
|-- java-mode
|   |-- .yas-parents    # contains "cc-mode text-mode"
|   `-- println
`-- text-mode
    |-- email
    `-- time

The .yas-make-groups file

images/group.png

If you place an empty plain text file .yas-make-groups inside one of the mode directories, the names of these subdirectories are considered groups of snippets and the YASsnippet menu is organized much more cleanly, as you can see in the image.

Another alternative way to achieve this is to place a # group: directive inside the snippet definition. See Writing snippets

$ tree ruby-mode/
ruby-mode/
|-- .yas-make-groups
|-- collections
|   |-- each
|   `-- ...
|-- control structure
|   |-- forin
|   `-- ...
|-- definitions
|   `-- ...
`-- general
    `-- ...

Using plain file names

Normally, file names act as the snippet trigger key, see Expanding snippets. However, if you customize the variable yas/ignore-filenames-as-triggers to be true or place an empty file .yas-ignore-filename-triggers you can use much more descriptive file names. This is useful (but not mandatory) if many snippets within a mode share the same trigger key.

$ tree rails-mode/
rails-mode/
|-- .yas-make-groups
|-- .yas-ignore-filename-triggers
|-- Insert ERb's <% __ %> or <%= __ %>.yasnippet
|-- asserts
|   |-- assert(var = assigns(%3Avar)).yasnippet
|   |-- assert_difference.yasnippet
|   |-- assert_no_difference.yasnippet
|   |-- assert_redirected_to (nested path plural).yasnippet
|   |-- assert_redirected_to (nested path).yasnippet
|   |-- assert_redirected_to (path plural).yasnippet
|   |-- assert_redirected_to (path).yasnippet
|   |-- assert_rjs.yasnippet
|   `-- assert_select.yasnippet

No storage (bundle)

The most convenient way to define snippets for YASnippet is to put them in a directory arranged by the mode and use yas/load-directory to load them.

However, this might slow down the Emacs startup speed if you have many snippets. You can use yas/define-snippets to define a bunch of snippets for a particular mode in an emacs-lisp file.

Since this is hard to maintain, there's a better way: define your snippets in directory and then call M-x yas/compile-bundle to compile it into a bundle file when you modified your snippets.

The release bundle of YASnippet is produced by yas/compile-bundle. The bundle uses yas/define-snippets to define snippets. This avoids the IO and parsing overhead when loading snippets.

Further more, the generated bundle is a stand-alone file not depending on yasnippet.el. The released bundles of YASnippet are all generated this way.

See the internal documentation for the functions yas/define-snippets and yas/compile-bundle.