Add your own Snippets
Spacemacs has lots of snippets for most of the languages and modes it supports. However, YASnippets also uses a simple template system in plain text, so its pretty easy to learn. Lets look at how to add your own snippets with Spacemacs.
automatically create snippets
Select a code block that you often create and using the yasnippets tools to create your own generic template
vfor visual mode and move the cursor around to select the text, or
SPC vto grow the selected region
SPC SPC helm-yas-create-snippet-on-regioncreates a new snippet
- Enter the name you wish to refer to this snippet
- Select the major mode you want to add the snippet too (eg. clojure, markdown, html)
- Edit the text and delete any text that is not required
- Add tab points in the snippet if relevant
$1initial cursor position,
$2next cursor position on tab,
$0end cursor position.
SPC SPC yas-tryout-snippetto test the snippet has the right behaviour
SPC SPC yas-load-snippet-bufferto load the snippet into the defined mode
Manually adding snippets
The easiest place to add your own snippet definitions is in the
~/.emacs.d/private/snippets directory. Under this directory structure you should create a folder named after the relevant mode for your snippets, eg
markdown-mode. Inside this mode folder, create files whos names are based on the snippet alias you wish.
So for a work in progress snipped called
wip in markdown mode I created
You need to load this new snippet into Spacemacs by either restarting or using the command
M-x yas-load-snippet-buffer command in the buffer of the new snippet you have just written. Ths snippet with then work within any markdown mode buffer.
Managing your snippets
Although the private snippets directory is easy to use, it is not under version control. So although its not over-riddend by Spacemacs it also means your private snippets are not backed up anywhere.
If you use the
~/.spacemacs.d/snippets/modename-mode/ directory structure for your snippets then you can version them with Git or similar versioning tools.
How to write a snippet
Each snippet template is contained in its own file, named after the alias of the snippet. So a snippet called
wip will be in a filename wip, in a directory named after the relevant Emacs mode.
The basic structure of a snippet template is:
#name : FullNameOfSnippet (not the alias name, the full name shows in autocompletion menu) #contributor: John Stevenson <email@example.com> # -- Add the content you want to replace the snippet name with when it expands
The content can be anything, simple text or more usefully a code strucuture with placeholders
Example: Simple text replacement
I use markdown mode for writing a lot of content, especially for technical workshops. As I am developing these workshops its useful to highlight which sections are still work in progress. Rather than type the common message I use, I've created a simple snippet called
#name : WorkInProgress #contributor: John Stevenson <firstname.lastname@example.org> # -- > **Fixme** work in progress
When you expand this snippet with
M-/ then the snippet name is replaced by the content.
Example: Using tab stops
Lets look at an existing snippet called
form in the
html-mode. This expands into a html form, but also helps you jump from method, id, action and content.
#contributor : Jimmy Wu <email@example.com> #name :<form method="..." id="..." action="..."></form> # -- <form method="$1" id="$2" action="$3"> $0 </form>
This snippet is the same as the simpler example, except we have added tab stops using the
$ sign and a number. When you expand this snippet, the snippet name is replaced by the content as usual but the cursor is placed at the first tab stop
$1. Each time you press
TAB you move to the next tab stop.
$0 is our exit point from the snippet, so pressing
TAB reverts to the usual behaviour outside of YASnippet.
Testing your snippets
Once you have written your snippet, you can quickly test it using
M-x yas-tryout-snippet. This opens a new empty buffer in the appropriate major mode and inserts the snippet so you can then test it with
If you just want to try the snippet in an existing buffer, then use
M-x yas-load-snippet-buffer to load this new snippet into the correct mode.
M-x yas-load-snippet-buffer does exactly the same except it kills the snippet buffer (prompting to save first if neccessary).
There are no default keybindings for these commands in Spacemacs, so you could create a binding under
C-o, for example
C-o C-s tto try a snippet and
C-o C-s lto load a snippet.
Adding yas-snippets to autocompletion in Spacemacs
By adding the
autocompletion layer in Spacemacs the YASnippets can be shown in the autocompletion menu as you type.
By default, snippets are not shown in the auto-completion popup, so set the variable
(setq-default dotspacemacs-configuration-layers '((auto-completion :variables auto-completion-enable-snippets-in-popup t)))
Find out more about YASnippets and autocompletion from the Github repository for Spacemacs autocompletion layer. Also take a look at Writing Snippets from kazu634.