Syntax definitions and color schemes in Sublime Text interact through the use of
scope names. Scopes are dotted strings, specified from least-to-most specific.
For example, the
if keyword in PHP could be specified via the scope name
Sublime Text supports TextMate language grammars, and inherited its default syntaxes from various open-source bundles. The TextMate language grammar documentation provided a base set of scope names that have been slowly expanded and changed by the community.
This is a living document that attempts to document best practices for using scope names in syntax definitions and color schemes. All of the Sublime Text default packages strive to adhere to these recommendations.
The scopes documented below are a recommended base set of scope names to use when creating a syntax definition.
In this documentation, the syntax name is omitted from the end of the dotted
scope name. When writing a syntax, unless otherwise noted, the syntax name
should be the final segment of a dotted name. For example, a control keyword in
Ruby would be
keyword.control.ruby, whereas in Python it would be
It is an on-going process to improve and expand upon the default syntaxes that are shipped with Sublime Text. As of early-2019, the following syntaxes have been recently re-worked, and may be used as a reference:
The following, top-level, list of scopes is sorted alphabetically. It is recommended to read through the entire list at least once before writing or modifying a syntax.
Numeric literals, including integers, floats, etc. should use one of:
Constants that are built into the language, such as booleans and null values, should use:
Character escapes in strings, e.g.
\x20, should use:
Formatting placeholders, such as those used for
Other language-specific constant values, such as symbols in Ruby, should use:
The entity scopes are generally assigned to the names of data structures, types
and other uniquely-identifiable constructs in code and markup. The notable
are used in HTML and XML tags.
The names of data structures will use one of the following scopes, or a new
entity.name – this list is not exhaustive. To provide rich
semantic information, use the specific terminology for a given language
unnecessarily nest scope labels under
forward-decl variants of the above are used in languages such as C and C++.
Such scopes can be used to exclude identifiers from the symbol list and
Class, interface and trait names listed as an inherited class or implemented interface/trait should use:
Function names receive one of the following scopes. These are included in the symbol list and index.
Namespaces, packages and modules use the following scope. There are usually not multiple types of such constructs in a language, so this scope should suffice.
Constants should use the following scope or
depending on the language semantics. This scope is often included in the symbol
list and index.
Labels for goto-like constructs should use:
Heading names in markup languages, such as Markdown and Textile, should use:
HTML and XML tags should use the following scope. This is the only
entity.name scope that is applied to repeated constructs.
HTML, CSS and XML use the following for tag attribute names:
Elements that are illegal in a specific context should use the following scope. Overuse of this will likely lead to unpleasant highlighting for users as they edit code.
Deprecated elements should be scoped using the following scope. This should be very rarely used, as users may be working with older versions of a language.
Control keywords examples include
syntaxes prefer to mark
else with the
import variant is often used in appropriate situations.
Keywords that contain punctuation, such as the
@ symbol in CSS, add the
following scope to the symbols:
All remaining non-operator keywords fall under the
Operators are typically symbols, so the term
keyword can seem somewhat
contradictory. Specific variants are sometimes referenced based on the type of
When the operator is a word, such as
not, the following
variant is used:
Markup scopes are used for content, as opposed to code. This includes syntaxes such as Markdown and Textile.
Section headings should use:
Lists should use one of:
Basic text styling should use one of:
Inserted and deleted content, such as with
diff output, should use:
Links should use:
Blockquotes and other quote styles should use:
Inline and block literal quoting, often used for code, should use:
Other markup, including constructs such as footnotes and tables, should use:
Meta scopes are used to scope larger sections of code or markup, generally containing multiple, more specific scopes. These are not intended to be styled by a color scheme, but used by preferences and plugins.
The complete contents of data structures should be scoped using one of the
following scopes. Similar to
entity.name, they should be customized per
language to provide rich semantic information. They should include all
elements, such as the name, inheritance details and body.
The entire scope of a function should be covered by one of the following scopes.
Each variant should be applied to a specific part, and not stacked. For
meta.function.php meta.function.parameters.php should never occur,
but instead the scopes should alternate between
meta.function.parameters.php and back to
The entirety of a namespace, module or package should use:
Preprocessor statements in language such as C should use:
Annotations, attributes and decorator statements that are used to modify the
behavior or implementation of a class, method or function should use one of the
meta scopes for each component of the annotation. That is to say,
there should never be more than one
meta.annotation* scope on the stack at
any given time. See
variable.annotation for scoping the identifier.
Complete identifiers, including namespace names, should use the following scope.
Such identifiers are the fully-qualified forms of variable, function and class
names. For example, in C++ a path may look like
myns::myclass, whereas in
PHP it would appears such as
Function names, including the full path, and all parameters should receive the
following scope. The name of the function or method should be
variable.function, unless the function is scoped with
Sections of code delineated by curly braces should use one the following
meta scopes, based on appropriate semantics. The
should additionally use the
Sections of code delineated by parentheses should use one the following
scopes, based on appropriate semantics. The
) characters should
additionally use the
Sections of code delineated by square brackets should use the following scope.
] characters should additionally use the
Generic data type constructs should use the following scope. Any symbols that
denote the beginning and end, such as
additionally use the
HTML and XML tags, including punctuation, names and attributes should use the following:
Paragraphs in markup languages use:
The following scopes are punctuation scopes that are not embedded within other scopes. For instance, the string. section includes documentation about scopes for string punctuation.
Separators such as commas and colons should use:
Semicolons or other statement terminators should use:
Line-continuation characters, such as in Python and R, should use:
Member access, scope resolution, or similar constructs should use the following
.. In PHP this would be
::. In C++, this would be applied to all three.
A language-specific variant of the following scope is typically applied to the entirety of a source code file:
Types should use the following scope. Examples include
Keywords that affect the storage of a variable, function or data structure
should use the following scope. Examples include
Keywords for functions or methods should use the following scopes. Example
def. This includes
storage.type for backwards compatibility with older color schemes.
Keywords for classes, structs, interfaces, etc should use the following scopes –
this list is not exhaustive. Example keywords include
typedef. This includes
storage.type for backwards
compatibility with older color schemes.
Basic strings use the one of the following scopes, based on the type of quotes used:
Strings that used unconventional quotes, such as
> with C imports,
The entirety of a string, along with all punctuation, prefixes, suffixes and interpolations should use:
Punctuation at the beginning and end of strings should use:
Unquoted strings, such as in Shell and Batch File, should use:
Regular expression literals should use:
When a string contain interpolated code, such as a variable or expression, the
string.* scope should be removed using
clear_scopes:, and the following
should be added to the entirety of the interpolation, including punctuation:
The punctuation for an interpolated expression should be:
Between the punctuation, the interpolated expression should get:
While also used for base frameworks, many syntaxes apply these to scopes unrecognized classes and types, effectively scoping all user constructs.
Programming languages use source. as their base scope, whereas content uses
text.. One of the biggest differences is the fact that many plugins and
other dynamic functionality is disabled within
text. scopes. markup.
scopes are typically used within text.
HTML should use the following scope. Variants for this scope are different than
other scopes, in that the variant is always added after the
.html, such as
XML should use:
A generic variable should use the following scope. Some languages use the
readwrite variant for contrast with the
constant variant discussed
Symbols that are part of the variable name, should additionally be applied the
following scope. For example, the
$ in PHP and Shell.
Immutable variables, often via a
const modifier, should receive the
following scope. Depending on the language and semantics,
entity.name.constant may be a better choice.
Reserved variable names that are specified by the language, such as
super, etc. should use:
Parameters to a function or methods should use the following scope. This may also be used for other parameter-like variables, such as receivers or named return values in Go.
Fields, properties, members and attributes of a class or other data structure should use:
Function and method names should be scoped using the following, but only when
they are being invoked. When defined, they should use
The final label in an identifier that is part of an annotation should use the
following. For the entire identifier, the
meta.path scope should be used.
The entire annotation should get
The leading symbol used to delineate an annotation should use:
In general, when applying colors and styles to scopes in a color scheme, the most general form of a selector should be styled first. High-quality syntaxes utilizing the scopes outlined in the previous section should result is good user experience for end users.
Minimal Scope Coverage🔗
The following is a recommended minimal set of scopes to highlight. Adding extra may result in a slightly improved experience, however being too specific will result in a color scheme that often only looks good for one or two syntaxes.
When styling scopes, resist the urge to directly style
meta scopes. They are
primarily intended to provide contextual information for preferences and
Historically, many color schemes have provided one color for
entity.name.type, and often a different color
entity.name.tag. This leaves new
Color schemes should instead specify a color for
entity.name that will be
applied to classes, types, structs, interfaces and many other data structures.
This color can be overridden for the two scopes
entity.name.section, that are used for different types of constructs.