Legacy Syntax Definitions

Before Sublime Text invented its own syntax format (.sublime-syntax), TextMate Syntax Definitions (.tmLanguage) were used for backwards compatibility with its spiritual predecessor TextMate.

Sublime Text Syntax Definitions were effectively added in build 3092 and are thus only available to Sublime Text 3. Unless you are targeting Sublime Text 2 (or other software that uses TextMate Syntax Definitions), you should not use the TextMate format. The Sublime Text Syntax Definitions format is based on TextMate's and provides a superset of its capabilities while being easier to read and write, since it uses YAML.

This document exists for when you really need to use the old format and will only cover the basics, mostly ported from the old README.

Background

TextMate Syntax Definitions use the Property List format, which is an XML variant.

Because Property Lists are bothersome to edit by hand, PackageDev initially provided a command to convert a Property List to a JSON document and vice versa, meaning you could edit the syntax definition in JSON without having to bother with Property Lists and have PackageDev convert the file to be used by Sublime Text (or other software).

As time moved on, YAML was "discovered" and added to the conversion functionality forming a triangle of basically equivalent serialization formats. Because YAML was designed specifically for easier human readability and better modification of such, it was deemed the superior format for editing syntax definitions and everything following will focus on this format that we called .YAML-tmLanguage, based on its file extension.

Creating a TextMate Syntax Definition

1. Command Palette: PackageDev: New TextMate Syntax Definition (YAML)
2. Edit the file to your liking.
3. Save the file (in your package or elsewhere).
4. Menu: Tools → Build or press the appropriate keyboard shortcut for your platform to convert the file into a Property List. Make sure you either have the build system set to "Automatic" or "Convert To …".

Remember that you need to build/convert any changes to the file before they can be used!

For documentation, refer to the unofficial documentation.

For an example syntax definition in this format, see the syntax definition for YAML-tmLanguage files itself and compare it to the converted .tmLanuage equivalent.

Features for TextMate Syntax Definitions

• Syntax highlighting, including for Oniguruma regular expressions

• A command to rearrange unsorted (or alphabetically sorted) syntax definitions in YAML. See the source code's docstring for documentation on the various parameters.

• Static and dynamic completions

  • All basic keys like name and captures.
  • Numbers are completed to capture group elements. This means that typing 4<tab> results in '4': {name: }.
  • Scope names are completed just like Sublime Text Syntax Definitions.
  • Includes are completed as per defined repository keys.

General Tips

Since these would be mostly about the YAML format, see the YAML Tips section for Sublime Text Syntax Definitions.

Editing Existing TextMate Syntax Definitions

You can convert a JSON or Property List file to YAML at any point in time. However, for syntax definitions in particular, a custom command was developed that converts and prettifies a TextMate Syntax Definition, because the default formatting is not ideal.

The command is available in the command palette as PackageDev: Convert to YAML and Rearrange Syntax Definition. This works for migrating .JSON-tmLanguage files as well.

To ensure proper markup of the resulting syntax definition, you should explicitly convert indentation to spaces using the Indentation: Convert to Spaces command before converting.

The precise steps are thus as follows:

1. Open the .JSON-tmLanguage or .tmLanguage file you want to convert.
2. Command Palette: Indentation: Convert to Spaces
3. Command Palette: PackageDev: Convert to YAML and Rearrange Syntax Definition