1. Introduction

Sublime Text is a fast and thoroughly-customizable text editor, adept at everything from editing source code to prose. It is designed with the ethos that “everything is customizable”. You can both add your own features to the editor, as well as add your own programming languages if yours are not already supported.

Sublime Text exposes its internals via an Application Programming Interface (API) that programmers can interact with by creating Plugins using the Python programming language.

1.1. Getting Sublime Text

The cutting-edge build can be useful for things like when you report a bug and then they fix it and release a new build right away (happened to me on build 4199).

1.2. Sublime Basics

1.2.1. Starting Sublime Text

Starting Sublime Text is as easy as launching sublime_text.exe from its installation directory. Normally this is done by opening the Sublime Text icon that was installed with it. subl.exe is a command-line helper designed to make it easier on Windows to deal with certain things. It launches sublime_text.exe.

There are a few command-line options that may be of interest. Here is the output of subl --help:

Sublime Text build 4192

Usage: subl [arguments] [files]         Edit the given files
   or: subl [arguments] [directories]   Open the given directories
   or: subl [arguments] -- [files]      Edit files that may start with '-'
   or: subl [arguments] -               Edit stdin
   or: subl [arguments] - >out          Edit stdin and write the edit to stdout

Arguments:
  --project <project>:    Load the given project
  --command <command>:    Run the given command
  -n or --new-window:     Open a new window
  --launch-or-new-window: Only open a new window if the application is open
  -a or --add:            Add folders to the current window
  -w or --wait:           Wait for the files to be closed before returning
  -b or --background:     Don't activate the application
  -s or --stay:           Keep the application activated after closing the file
  --safe-mode:            Launch using a sandboxed (clean) environment
  -h or --help:           Show help (this message) and exit
  -v or --version:        Show version and exit

Filenames may be given a :line or :line:column suffix to open at a specific
location.

See official documentation here: https://www.sublimetext.com/docs/command_line.html

1.3. Major Concepts

Sublime Text is built up from a number of simple-but-powerful concepts. It is this fact that makes it—once you get to know it—a joy to work with, and easy to customize for the type of editing you engage in most. These concepts are summarized here with links to more detailed information.

Application:

A Process in the Operating System sense of the word (sublime_text.exe on Windows), is a “singleton-type” application, meaning there can be at most one running on any given computer, but it can host any number of open Sublime Text Windows simultaneously, each potentially having a different Project open.

Window:

A Window is a single unit of the UI with title bar, and minimize, maximize and close buttons in the upper right.

Each Window has (in top-to-bottom order):

The Client-Area panel has (in left-to-right order):

Screenshot of a Sublime |nbsp| Text Window

Fig. 1.3.1 Screenshot of a Sublime Text Window

Focus Group Panel:

A Focus Group Panel is a single sub-panel of the Editing Panel that contains 1 or more Sheets. While a Focus Group can host any number of Sheets, it normally only displays one Sheet at a time.

To display 2 or more Sheets simultaneously (e.g. side by side or one above the other), you invoke a Layout that hosts more than one Focus Group Panel at a time.

To see examples of different Focus-Group-Panel Layouts, hold down the [alt+shift] keys and hit the following numbers in this sequence: 2, 3, 8, 9, and finally 1 to return to the original Layout. Each of those “areas” is called a Focus Group Panel (or just “Focus Group”).

Screenshot showing Focus Group Panel

Fig. 1.3.4 Focus Group Panel

Layout:

A Layout controls how the Editing Panel divides its area among 1 or more Focus Group Panels.

See Layouts for more details.

Sheet:

A Sheet represents 1 file (or display output, such as the “Find Results” display resulting from a Find-in-Files operation), each having a Tab at the top and a display/editing area below it.

Sheets come in one of 3 types:

  • Text

  • Image

  • miniHTML

Screenshot showing Sheet

Fig. 1.3.5 Sheet

When the area below the Tab contains text, the text display and editing functions (assuming it is not in read-only mode) are carried out by a View.

If you single click a file containing text in the Side Bar, the contents appear in the View in “peek” mode. (File name is in italics in the Tab.) If you open the file by one of these methods:

  • File > Open File... from the menu,

  • double-click the filename in the Side Bar,

  • double-click the Tab (when it is already showing in “peek” mode), or

  • start editing it,

then the file is considered “officially” open, the filename will no longer be in italics in the Tab, and then its name will also appear in the OPEN FILES list at the top of the Side Bar. You can drag these names in the OPEN FILES list, or drag the Tabs at the top of the Focus Group, to reorder them.

View:

A View is the tremendously-capable editing interface of the Sublime Text UI, accepting user keystrokes, displaying its contents, and has vast capabilities. Views are used for a large number of purposes, and can be read-only when appropriate.

Not every View is connected with a file on disk. Examples:

  • displaying report output (e.g. Find-in-Files Results titled “Find Results”),

  • displaying (read-only) Package Resource files stored in .sublime-package (zip) format,

  • new files (File > New File) before they are saved to disk.

Once such content is displayed, it can be saved, if desired, by using File > Save As....

Each View is attached to exactly one Buffer (though multiple Text Views can be attached to the same Buffer).

Views are also used as input “TextBoxes” inside Panels. Examples:

  • Find/Replace/Find-in-Files Panels,

  • Console input and output, and

  • Input field in Command Palette and other input-gathering panels.

The beauty of this is that they have many features (like Undo/Redo), and Plugins can get access to their contents in Text Commands in the same way as they do for regular text being edited.

Screenshot showing View

Fig. 1.3.6 View

Buffer:

The container for the edited content, representing that content as a contiguous sequence of possibly-multi-byte characters. Line separators within the Buffer are always a single newline (’\n’, 0x0A) character. For platforms that use different line separators for text stored in files, this translation occurs during loading and saving, but the line separators in Buffers are consistent across all platforms.

Overlay Panel:

An Overlay Panel is Sublime Text’s version of a GUI Dialog Box. It is called an Overlay Panel because it is anchored to, and overlays part of the Sublime Text Window, usually at the top of the Editing Panel, or at the bottom of the Window above the Status Bar. Overlay Panels are used to gather user input and/or perform certain types of actions that sometimes require more than a single key-stroke to complete.

Screenshot showing Overlay Panel

Fig. 1.3.7 Overlay Panel

Menu:

A tree-structured display, normally collapsed to the top level, allowing the user to select actions to take by topic. The Main Menu is located at the top of the window, just under the Title Bar.

Screenshot showing Main Menu

Fig. 1.3.8 Main Menu

Status Bar:

The Status Bar is the bar at the bottom of the window that shows a variety of helpful information about a number of things you occasionally need to know about (in left-to-right order):

  • current row and column of the caret (cursor) in current View

  • how many Selection Regions (carets) are active in current View

  • state of current Git repository (if any, click to launch Sublime Merge if installed)

  • number of misspelled words (when Spell Checking is turned on)

  • information about the file being displayed in the current View:

    • current encoding (click to change)

    • type of line endings being used (click to change)

    • indentation settings (click to change)

    • current language syntax being used (for highlighting and other behaviors; click to change)

  • When one of the Find Overlay Panels is being displayed, the current row and column are replaced by the number of Find results there are, and which is being highlighted (if any).

Screenshot showing Status Bar

Fig. 1.3.9 Status Bar

Note

line-ending and current-encoding status display are turned off by default, but can be turned on by including these two entries in your custom settings:

{
    "show_encoding": true,
    "show_line_endings": true,
}

Current language syntax controls:

  • syntax highlighting

  • Build Systems that are available

  • some Package functionality that is only available for certain file types

Run-Time Object Model:

All of the above concepts (Application, Window, Side Bar, Editing Panel, Focus Group Panel, Sheet, View, Buffer, Overlay Panel, Menu and Status Bar) have the relationship shown below. This relationship is helpful to understand so you know what you are working with in the Python code you create to make customizations.

In an Entity-Relationship Diagram (ERD), this Run-Time Object Model would look like this:

    +-------------------------+
    |Key:  |       |       |  |
    |      |       |       +  |
    |      |      /|\     /|\ |
    |   Exactly   Zero    One |
    |     One      or      or |
    |             More    More|
    +-------------------------+

                       Sublime Text
                          Process
                             |
                             +
                            /|\
                          Window
    --------------------------------------------------
              |              |         |
          Side Bar        Editing      +-- Title Bar
           /    \          Panel       +-- Main Menu
     Folders    Open         |         +-- Status Bar
     List       Files        +         +-- Zero or One Visible Overlay Panel
      |         List        /|\              (Sublime Text's version
     /|\                Focus Group          of a dialog box)
    Mount                  Panel
    Point                    |
      |                      |
   Directory                 |
     Tree                    +
                            /|\
                           Sheet (flavors:  text [View], Image, HTML)
----------------------------------------------------------------------------
  |                                  |
 Tab                                View
       ---------------------------------------------------------------------
                      |      |       |        |         |        (possible
                      |      |       +        |         |       other Views)
                  Regions    |      /|\       |         |   /----- View
                Dictionary   |   Selection    |       Buffer ----- View
                             |                |             \----- View
                          Settings           Edit
                         Dictionary    (Change-History
                                            Stack)
Context Menus:

A Context Menu is a pop-up menu that opens as a result of right-clicking any of several objects in the Sublime Text GUI. (Some keyboards also have the ability to open Context Menus.)

Note that Context Menus were not shown in the above diagram to reduce clutter. But for reference, the following types of objects (shown above) can pop up Context Menus:

See Menus for more details.

Screenshot showing Context Menu

Fig. 1.3.10 Context Menu

Viewport:

Todo

Viewport, and its relationship to these View functions:

  • viewport_position(self) -> Vector:

    “”” :returns: The offset of the viewport in layout coordinates. “””

  • set_viewport_position(self, xy: Vector, animate=True):

    “”” Scrolls the viewport to the given layout position. “””

  • viewport_extent(self) -> Vector:

    “”” :returns: The width and height of the viewport. “””

  • layout_extent(self) -> Vector:

    “”” :returns: The width and height of the layout. “””

  • text_to_layout(self, tp: Point) -> Vector:

    “”” Convert a text point to a layout position. “””

  • text_to_window(self, tp: Point) -> Vector:

    “”” Convert a text point to a window position. “””

  • layout_to_text(self, xy: Vector) -> Point:

    “”” Convert a layout position to a text point. “””

  • layout_to_window(self, xy: Vector) -> Vector:

    “”” Convert a layout position to a window position. “””

  • window_to_layout(self, xy: Vector) -> Vector:

    “”” Convert a window position to a layout position. “””

  • window_to_text(self, xy: Vector) -> Point:

    “”” Convert a window position to a text point. “””

  • line_height(self) -> DIP:

    “”” :returns: The light height used in the layout. “””

Key Bindings:

Key Bindings connect key combinations with the actions they perform. See Key Bindings for more details.

Scope:

Scope is the “characteristics of the caret’s location in a text file”.

Syntax definitions make Sublime Text aware of the Scope for any given position in a file. They do so by generating scope names to provide metadata about language tokens. This metadata is updated on-the-fly every time the caret moves in any kind of document, but it is especially applicable in source code where the metadata reveals the nature of the area that the caret is currently sitting in (e.g. keyword, keyword category, number, symbol, comment, etc.).

See Scope for more details.

Selector:

A Selector is a string that is evaluated against the current Scope, and triggers a True or False result based on that evaluation. Its use is to determine whether a particular ‘thing’ is applicable based on the nature of the current caret location, i.e. its Scope.

If you’re familiar with CSS, Sublime Text Selectors behave like selectors in a CSS file: they are a very efficient method of determining whether something “applies” or not.

See Scope, Selectors and Context for more details.

Context:

A Context is an optional element of a Key Binding, that uses the key “context” in the Key Binding dictionary object. When present, it provides a possibly-complex condition under which that key combination can be applied.

See Key Binding Definitions for full details.

Commands:

Commands are how Sublime Text carries out actions that are beyond handling individual printable keystroke. They are ubiquitous: key bindings, menu items, macros and many other types of actions are implement through the command system.

Some commands are implemented in the editor’s core, but the remainder are provided through Plugins, which means you can view and customize their source code and behavior. Every command (including built-in ones) can be called from a Plugin.

See Commands for details.

Settings:

Settings (Preferences) are stored in Sublime-relaxed-JSON format. The global defaults for these are accessed (read-only) by:

Preferences > Settings (left side since Sublime Text 4)

The major sections of that file are:

  • Editor settings (the top 2/3 of the file)

  • UI settings

  • Application

Note that the comments in this file describe each setting key and its possible values and what they mean—which is a great place for this documentation: where and when you need it.

The right side (as of Sublime Text 4) are editable user overrides created by copying the key/value pairs from the left side and pasting them on the right and modifying (and saving) their default values.

Note

If you have the PackageDev Package installed, this copy/pasting can be done by a single mouse click, among many other things.

There are also Package settings, which apply to specific package behavior, which are accessed by:

Preferences > Package Settings > ...

These preferences are applied in layers like CSS, where lower (more specific) preferences override higher-level preferences of the same name.

The “path” of the “layer cascade” is guided by scopes that apply to the that currently shown in the editing area.

Layer

Access

Notes

global defaults

Pref > Settings (left side)

Preferences.sublime-settings

platform defaults

Tools > View Package File > Default/Preferences (<platform>)

Preferences (Windows).sublime-settings

user-scope overrides

Pref > Settings (right side)

Packages/User/Preferences.sublime-settings

project-scope overrides

Project > Edit Project > “settings”: { ... } entry

Editor preferences only, not UI or APP BEHAVIOR preferences.

file-extension-scope (syntax-specific) defaults

Pref > Settings - Syntax Specific (left)

C.sublime-settings

file-extension-scope (syntax-specific) overrides

Pref > Settings - Syntax Specific (right)

Packages/User/C.sublime-settings
Project:

A Project is how Sublime Text enables the user to rapidly access and open a set of related files from the Side Bar Folders tree. See Projects for details.

Snippet:

A Snippet is an external XML file that enables one to call up static text that you use frequently, and can optionally perform like an HTML form, giving you the opportunity to manually fill out “fields”. Snippets can also be used programmatically by plugins. See Snippets for details.

Completions:

The concept of Completions is an “umbrella” topic that covers different ways Sublime Text saves typing and time by finishing words or inserting boilerplate text. See Completions for details.

Plugins:

Plugins are Python modules that are stored in the root of a Package directory, and serve to provide additional (or modified) functionality for Sublime Text. See Plugins for details.

Packages:

A Package is a group of Package Resource files grouped under one directory name, which name indicates the nature of the additional functionality it provides to Sublime Text. See Packages for more information.

Data Directory:

Once installed, all customizations of Sublime Text go into its data directory. It has a different path depending on the platform:

Windows:

%APPDATA%/Sublime Text/

Windows Portable Version:

path/to/application/Data/

Linux:

~/.config/sublime-text/

MacOS:

~/Library/Application Support/Sublime Text/

This also makes it easy to revert Sublime Text to its freshly-installed state by

  • closing Sublime Text,

  • renaming that directory to a backup directory,

  • re-starting Sublime Text.

From here on in the documentation, we will refer to the Data Directory as simply <data_path>.

Console:

Sublime Text and Plugins can push debug information to the Console by using the Python print() function. To open the Console, press Ctrl+` or select View > Show Console from the main menu.

Screenshot showing Console

Fig. 1.3.11 Console Panel

The upper panel is a read-only View and at this writing cannot be searched. The lower panel sends its input to the built-in Python interpreter, giving you direct access to the Sublime Text API.

Entering sublime.log_commands(True) and/or sublime.log_input(True) is a great way to see what’s going on inside, as well as debug, if something isn’t going as you expected.

Using sublime.log_commands(True) is also the only way currently known by this author to discover the names of internal commands that are built into the Sublime Text core, and therefore not exposed to being gathered and reported by Plugins like generate_cmd_list.py.

1.3.1. Path Syntax

Sublime Text uses forward slashes as directory separators on all platforms.

While on Windows systems, native Windows path syntax (using backslashes) is supported in the “Where” field (path(s) + filters) of the “Find-in-Files” Panel, and in the path element of Sublime Project files, and possibly in other places where paths are used, forward slashes are fully supported everywhere, including in those places.

1.3.2. Sublime Python

Sublime Text has its own internal Python engine. It does not interact with, impact, or use Python in your system PATH variable in any way, unless directed to do so by a Build System.

1.3.3. Sublime API

The Sublime Text Python API is contained in:

If you are a Python developer and want to customize Sublime Text, this is a great place to look to better understand the facilities that are available. The above Run-Time Object Model should help you better understand where objects of each class are (e.g. Window, View, Buffer, etc.), and their relation to the whole.

1.3.4. JSON

Most types of settings in Sublime Text are stored (or represented) in Sublime-relaxed-JSON format.

1.4. Additional Information Resources

1.4.1. Documentation

1.4.2. In-Application References

  • Tools > Command Palette... > View Package File: lets you see all the default “things” you might want to customize, such as default settings, menus, commands available to the Command Palette, etc., and where they have overrides in place from installed packages. Example: type in “sublime-menu”. Main.sublime-menu contains all the default menu bar items starting at the top level and showing all their children.

    See Menus for more details.

  • Comments in default settings that document each individual setting value: Preferences > Settings

1.4.3. Training Videos

1.4.4. Sublime Text Community

1.4.5. 3rd-Party Contributions, Examples, Etc.

There are literally dozens if not hundreds of of GitHub accounts and other sites that host repositories for publicly-released 3rd-Party Packages. These often show great example Plugins and Packages for Sublime Text that you can both install and learn from.