Documentation Scope Naming
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.
Usage in Syntax Definitions
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 mid-2016, the following syntaxes have been recently re-worked, and may be used as a reference:
Top-Level Scope Index
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.
Single and multi-line comments should use, respectively:
Multi-line comments used as documentation, such as Javadoc or PhpDoc, should use:
Symbols that delineate a comment, e.g.
/*, should additionally use:
Comments with special syntax that denote a section of code, should use the following scope on the text only. This will cause it to be shown in the symbol list.
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
%s, should use:
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 exceptions are
entity.other.attribute-name, which are used in HTML and XML tags.
The names of data structures will use one of the following scopes, or a new sub-scope of
entity.name – this list is not exhaustive. To provide rich semantic information, use the specific terminology for a given language construct.
entity.name.type.struct which 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 indexing.
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
variable.other.constant, 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
while. Some syntaxes prefer to mark
else with the
conditional variant. 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 operator.
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 example,
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:
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
} characters should additionally use the
Sections of code delineated by parentheses should use one the following
meta scopes, based on appropriate semantics. The
) characters should additionally use the
Sections of code delineated by square brackets should use the following scope. The
] characters should additionally use the
Generic data type constructs should use the following scope. Any symbols that denote the beginning and end, such as
>, should 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:
.. In PHP this would be applied to
::. 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 and definition/declaration keywords should use the following scope. Examples include
def. Depending on the language and semantics,
const may be this or
Keywords that affect the storage of a variable, function or data structure should use the following scope. Examples include
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, 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:
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
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 below.
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
Usage in Color Schemes
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 plugins.
Historically, many color schemes have provided one color for
entity.name.type, and often a different color for
entity.name.tag. This leaves new
entity.name.* scopes un-highlighted.
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.