Use Snippets as Shortcuts

Snippets are short fragments of text that you use frequently. Use snippets to save yourself tedious typing. Snippets are smart templates that will insert text for you and adapt it to their context.

You can associate snippets with triggers, that is, specific keystrokes. For example, if you configured a snippet for an RST ordered list with the trigger ol, when you enter ul, the following snippet is added at the cursor:

#. Step one.

#. Step two.

#. Step three.

After it’s added at the cursor, you can edit the snippet as needed. You can configure the snippet so you can tab through subsequent parts of the text.

The following video demonstrates using some custom snippets for common RST structures.

Snippets are stored on your computer. To share snippets within a team, you must manually share the snippet files.

For a good overview of snippets, see Snippets Saved My Life.

Add a Snippet

You add a snippet in Sublime.

  1. From the Tools menu, select Developer >> New Snippet.

    A new file opens with the snippet template:

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

  2. Modify the content within [CDATA[.

    • To be able to tab through text fields in the snippet, use ${n:text}, where n is the number for the tab order, and text is the default text in the snippet.

    • To add a key shortcut, uncomment the <tabTrigger> element and enter the keystrokes that will add the snippet:

      <tabTrigger>code</tabTrigger>

  3. Save the file.

You can then add the snippet to RST files by typing the tab trigger text.

Example Snippets

You can create snippets to suit your needs. Anything you find yourself repeating is a good candidate for a snippet. Following are snippets for common RST uses. You can copy the files for these snippets from the repository for this document into your Sublime user package.

H1

<snippet>
  <content><![CDATA[
.. _${1:this}:

${1:this} 
###################

${2:Content starts here}
]]></content>
  <tabTrigger>h1</tabTrigger> 
</snippet>

H2

<snippet>
  <content><![CDATA[
${1:this} 
***********************

${2:Content starts here}
]]></content>
  <tabTrigger>h2</tabTrigger> 
</snippet>

H3

<snippet>
  <content><![CDATA[
${1:this} 
=========================

${2:Content starts here}
]]></content>
  <tabTrigger>h3</tabTrigger> 
</snippet>

Anchor

<snippet>
  <content><![CDATA[
.. _${1:this}:

]]></content>
  <tabTrigger>anchor</tabTrigger> 
</snippet>

Code

<snippet>
  <content><![CDATA[
.. code-block:: ${1:type}
  :linenos:

  code


]]></content>
  <tabTrigger>code</tabTrigger> 
</snippet>

File Include

<snippet>
  <content><![CDATA[
.. include:: ${1:filename}

]]></content>
  <tabTrigger>inc</tabTrigger> 
</snippet>

List

<snippet>
  <content><![CDATA[
* ${1:this} 

* ${2:this}

* ${3:this}

]]></content>
  <tabTrigger>ul</tabTrigger> 
</snippet>

Internal Reference

<snippet>
  <content><![CDATA[
:ref:`${1:this}`

]]></content>
  <tabTrigger>ref</tabTrigger> 
</snippet>

Steps

<snippet>
  <content><![CDATA[
#. ${1:this} 

#. ${2:this}

#. ${3:this}

]]></content>
  <tabTrigger>ol</tabTrigger> 
</snippet>

Substitution

<snippet>
  <content><![CDATA[
|${1:this}|

]]></content>
  <tabTrigger>sub</tabTrigger> 
</snippet>

Index Page TOC

<snippet>
  <content><![CDATA[
.. toctree::
    :maxdepth: 1

      file
      file
      file
      file
]]></content>
  <!-- Optional: Set a tabTrigger to define how to trigger the snippet -->
  <tabTrigger>toc</tabTrigger>
</snippet>

YouTube Video

<snippet>
  <content><![CDATA[
.. youtube:: ${1:Youtube ID}

]]></content>
  <tabTrigger>ytube</tabTrigger> 
</snippet>