On this page…

Quickly Insert Text & Code with Sublime Text Snippets

Getting tired of cutting & pasting an HTML5 template? Or typing out the same code all the time? Fortunately, Sublime Text makes it easy to quickly insert code snippets that you define.

As you probably know, when you type a p in an HTML document in Sublime Text & press Tab, it automatically expands to . But what if you don't like that (I don't), & instead want it to expand to this (with the cursor appearing where the pipe is)?

<p>
  |
</p>

Let's create a snippet to do just that.

Create

To create your first snippet in Sublime Text, do the following:

Go to Tools > New Snippet. A new untitled file will open that contains the following:

<snippet>
    <content><![CDATA[
Hello, ${1:this} is a ${2:snippet}.
]]></content>
    <!-- Optional: Set a tabTrigger to define how to trigger the snippet -->
    <!-- <tabTrigger>hello</tabTrigger> -->
    <!-- Optional: Set a scope to limit where the snippet will trigger -->
    <!-- <scope>source.python</scope> -->
</snippet>

The content goes between <content><![CDATA[ & ]]></content>, resulting in this:

<content><![CDATA[
<p>
  $1
</p>
]]></content>

See that $1? That tells Sublime Text to put your cursor there when it's done expanding your snippet. Sublime Text calls that a field marker.

Next is the tabTrigger, the text you type, followed by a Tab, that expands to create the content. In our case, we want to use the letter p. Get rid of the comment describing the tabTrigger, & then change the actual line for the tabTrigger to this:

<tabTrigger>p</tabTrigger>

Finally, the scope, which determines the kinds of files (HTML, CSS, PHP, shell script, etc.) in which the expansion takes place. Again, get rid of the commented line describing the scope, & change the line for the scope to this:

<scope>text.html</scope>

At this point, the file should look like this:

<snippet>
<content><![CDATA[
<p>
  $1
</p>
]]></content>
<tabTrigger>p</tabTrigger>
<scope>text.html</scope>
</snippet>

Save

Save the file. When you do, you'll need to determine two things: its file name & where to save it.

File name: The file must end with .sublime-snippet, like this: foo.sublime-snippet. What goes in front of .sublime-snippet is up to you. I like to use the tabTrigger if at all possible, along with the main part of the scope in front of the tabTrigger, giving me this: html-p.sublime-snippet.

Where to save it: When you press Save, Sublime Text should automatically try to save the file in the right folder.

Mac OS X: /Users/yourname/Library/Application Support/Sublime Text 2/Packages/User
Windows:
Windows Portable (USB Drive):
Linux:

You shouldn't have to worry about the location, as Sublime Text should take care of it for you, but if for some weird reason you're not in the right place, then you'll need to navigate to the right location.

Test

Now let's test our new snippet. Open an HTML document (or open a new tab in Sublime Text & click in the bottom right to change the document type from Plain Text to HTML), click in it, & type p, followed by a Tab. You should see the following appear, with the cursor in place of the pipe symbol (|):

<p>
  |
</p>

Type the content you want between the  & , & then press Tab again, & Sublime Text automatically moves your cursor just after the , so you press Enter & continue typing. Our snippet worked. Excellent!

Other Examples

Here are a few other examples that also illustrate some of the other things you can do with Sublime Text snippets.

HTML5 Template

If you're creating HTML5-based websites, you're probably using the same template over & over again. That's exactly the sort of thing you should turn into a Sublime Text snippet!

Go to Tools > New Snippet & put the following in:

<snippet>
<content><![CDATA[<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>$1</title>
</head>
<body>
<h1>$2</h1>
<p>
  $3
</p>
</body>
</html>]]></content>
<tabTrigger>html5skel</tabTrigger>
<scope>text.html</scope>
</snippet>

Save it as html-html5skel.sublime-snippet¹.

This is the same as the other one we did, with one big difference. Previously, we used $1 to indicate where we wanted the cursor to sit after expansion. In our HTML5 template, you instead see $1, $2, & $3. What's going on?

Use $1 if you want to place your cursor in a particular location & be done with it. In my example above with  & , there really is only one place for the cursor to go, so that's all I need.

But when creating a longer, more complex template, you want your cursor to actually go in several spots.

$1 tells Sublime Text to put the cursor there when the expansion completes, so you can enter an appropriate title for the webpage.
When you're done in that spot, press Tab & your cursor will jump to $2 so you can enter text for the page title that appears in the browser's viewport.
After that, press Tab yet again & the cursor makes a final jump to $3, inside the first paragraph.

You can add as many of these as you want, with as many jumps as you'd like or would be appropriate. Oh, & if you want to jump back instead of forward, press Shift-Tab.

3 Paragraphs

I use this all the time. I often find myself wanting not one paragraph, but three.

<snippet>
<content><![CDATA[<p>
  $1
</p>
<p>
  $2
</p>
<p>
  $3
</p>]]></content>
<tabTrigger>p3</tabTrigger>
<scope>text.html</scope>
</snippet>

I saved this as, cleverly enough, html-p3.sublime-snippet. Note my use again of the field markers so that I can jump between paragraphs after they've been created.

CSS

What about CSS? You can use snippets for CSS as well as HTML (actually, you can use snippets with any language or text that works inside Sublime Text).

This is one that is pretty handy & also illustrates some additional things you need to know about Sublime Text snippets. I saved it as css-font.sublime-snippet:

<snippet>
    <content><![CDATA[font: ${1:normal|italic|oblique} ${2:normal|small-caps} ${3:normal|bold|bolder|lighter} ${4:1em}/${5:1.5} ${6:sans-serif|serif|monospace};
]]></content>
    <tabTrigger>font</tabTrigger>
    <description>font: 1em/1.5 sans-serif;</description>
    <scope>source.css</scope>
</snippet>

The first thing to notice is that there is a <description>…</description> line. You can put anything in there, as it's entirely for your eyes only. As you start to type the tabTrigger, you'll see the description appear as a little tooltip to remind you what the snippet does. You can use <description> with any snippet, not just CSS, so feel free to put them wherever it would help you.

The next thing to discuss is that the scope is different. For an HTML snippet, we had to use text.html, but for CSS, we instead use source.css. Why the difference? According to Syntax Definitions in the Sublime Text Docs:

The top level scope for this syntax definition. It takes the form source.<lang_name> or text.<lang_name>. For programming languages, use source. For markup and everything else, text.

So, if you're creating a snippet for HTML or other markup languages (like XML, YAML, LaTeX, Textile, & Markdown), use text.<lang_name>. For everything else—the programming languages like C, C++, Erlang, Python, Perl, Java, JavaScript, PHP, Ruby on Rails, & bash shell scripts—use source.<lang_name>². CSS isn't normally what I'd think of as a programming language, but it sure isn't a markup language, so it gets source.css.

Finally, focus on the content of the snippet:

font: ${1:normal|italic|oblique} ${2:normal|small-caps} ${3:normal|bold|bolder|lighter} ${4:1em}/${5:1.5} ${6:sans-serif|serif|monospace};

To understand what this means, let's see the results. When you type font & press Tab, you'll see the following:

font: normal|italic|oblique normal|small-caps normal|bold|bolder|lighter 1em/1.5 sans-serif|serif|monospace;

Your cursor isn't apparent in there; instead, the following is selected: normal|italic|oblique, which corresponds to this code in your snippet: ${1:normal|italic|oblique}. To Sublime Text, ${1:normal|italic|oblique} is a field marker that also contains a place holder. The ${1} is just like $1: it's a field marker. The normal|italic|oblique produces place holder text that is selected when the snippet is expanded. The idea is that you'll see your three choices as a reminder, & you can then type out the one you want.

When you've finished typing, press Tab & the next place holder—normal|small-caps—is selected because it corresponds to ${2}. Type normal or small-caps (or anything, really—the place holder is just a suggestion that you're free to ignore), press Tab, & the third field marker's place holder text is selected: normal|bold|bolder|lighter. And so on.

One more thing about place holders: if you instead use something like ${1:foo}, then when you expand your snippet, foo will be selected. You can then change foo to something else, or you can just press Tab & leave foo there while jumping ahead to the next field marker. The point is, place holder text can be just one item, or it can be several. It's your choice. Either way, field markers with place holders are a powerful, useful tool that make Sublime Text great.

More info

For more info about Sublime Text's snippets, see the canonical source: Sublime Text Docs: Snippets.

The "skel" is short for "skeleton". You could also use "template" in the tabTrigger & file name; I prefer "skel" because it's shorter. ↩
Be careful with the lang_name portion. For JavaScript, for instance, you actually use source.js, & for bash shell scripts, you use source.shell. When in doubt, search the examples in the Packages directory of your Sublime Text installation. ↩

Email	scott@granneman.com
Voice	314-780-0489
Address	39 Summit Place St. Louis, MO 63119 United States