Emacs: How to Define Templates in YASnippet

By Xah Lee. Date: 2009-02-18. Last updated: 2014-06-22.

This page shows you how to define templates for emacs's YASnippet template package.

If you don't know what's yasnippet, see a intro here: Emacs Templates with YASnippet.

This page describes yasnippet version dated in 2014. Info here may be outdated.

Snippets are organized by Folders

Directory Structure by Emacs's Modes

In your yasnippet folder, you'll find a path like this:

~/.emacs.d/plugins/yasnippet/yasnippet-0.8.0/snippets/

All template definitions are inside this folder.

In the snippets dir, there are subdirs:

text-mode
  c-mode
  perl-mode
  python-mode
  html-mode
  css-mode
  …

Each dir contains templates that will be active when you are in that mode.

One Template Definition Per File

Each template definition is a file. For example, suppose you have a template definition for “while” keyword for the Perl language. Then, there should be a file at this path: text-mode/perl-mode/while.

Each file may end with the suffix “.yasnippet”.

By default, the file's name is the abbrev for the template. For example, if you have a file html-mode/h1, then, typing h1 then Tab, will expand according to that template file's definition.

Technically, each file's name, up to the first period, defines the abbrev. For example: you might have these files:

doctype.xhml1
doctype.xhtml1_1
doctype.xhtml1_strict
doctype.xhtml1_transitional

When user types doctype then press Tab, a multiple choice menu will be shown.

File names starting with a period are not template definition but provide information purposes. For example: .readme.

Template Syntax

Each template file has this line: # -- (there MUST be a space). Everything above that line is either comment or directive (don't worry about directives for now). Below the line is the actual template definition.

Here's a example of the template html-mode/doctype.

#name : Doctype HTML 4.01 Strict
# --
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

When you type doctype then Tab, while in html-mode, it'll expand to:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

The line #name : is for a short title for the template. This title is used in menus. For example, look at the menu [YASnippet]. When there are multiple templates for the same abbrev, yasnippet will popup a multiple-choice menu, and each template's title is also shown in the menu.

Special Characters

In the template definition, some chars have special meaning:

$0: The position the cursor (after the snippte is inserted). You don't need to put a $0 if you don't need to.
$n: A field, where the n is a integer starting with 1. (Example: $1, $2, etc.). Pressing tab will move cursor to these stops for user to fill in. Multiple occurrence of the same $n means typing in one field will automatically fill the other.
${n:default_text}: Same as $n, but provides a default text.
$&: Means indent the line according to the mode's indentation rule.
`…`: (backtick) is used to enclose elisp code. The lisp code will be evaluated in the same buffer the snippet is being expanded.

Sample Snippet Files

Examples of defining HTML tags with field stop points:

<h1>$1</h1>

<img src="$1" class="$2" alt="$3">

You can also include lisp code in your template. For example, you might want to have a date stamp. Here's a example that insert user's email address and datestamp.

`user-mail-address`

`(current-time-string)`

Loading Your Template

Once you create a template file, you have to load it. Alt+x yas-reload-all.

Expand Word Including Hyphen

Emacs YASnippet Tip: Expand Whole hyphenated-word as Input

Using Abbrev Mode

I recommend using emacs builtin abbrev mode instead of yasnippet.

See: Emacs: Abbrev Mode by Lisp Code