Theme customisation

Sublime Text makes it easy to extend and customise an existing theme without the need to duplicate or modify the original theme files.

This feature is very useful for tweaking a theme to suit your personal preferences or working style. User customised theme rules are separate from the base theme, reducing unnecessary maintenance or lost changes when upgrading the original theme.

Customisation Setup

To begin customising an existing theme, create a new file in your User folder (located in the Sublime Text Packages directory) with the same name as the theme file you are extending.

For example, to customise Soda Dark, create an empty file called Soda Dark.sublime-theme (or for Sublime Text 3 create an empty file called Soda Dark 3.sublime-theme) in your User folder.

From this point, any valid theme rules you place in this file will automatically be applied by Sublime Text when the related theme is active.

Applying Theme Rules

Changes contained in user theme files are applied after the base theme file has been processed. This allows you to tweak existing theme attributes, override default values or introduce new styles into the base theme.

Theme files use a JSON like structure to organise rules and settings. At a minimum, the file requires an outer array wrapper [] to contain the set of rules.

Components are contained within brace blocks {} and defined by the class property. Rules within each section are configured using comma separated key / value assignments.

Basic User Theme Structure

The following psuedo code represents the basic structure of a user theme file:

[
    {
        "class": "name_of_theme_component",
        "configurable_property": "desired_value",
        "another_property": "desired_value"
    },
    {
        "class": "another_theme_component",
        "configurable_property": "desired_value"
    }
]

User Theme Examples

Below are some examples of the types of quick tweaks that can be applied with a user theme.

For our first example, we will change the height of the UI tabs. Some people prefer short tabs to minimise their screen real estate, while others like tall tabs to improve usability with the mouse.

A user theme is a great way to adjust this element, and is much simpler than creating or maintaining a complete theme.

Short Tabs

Let's make the square tabs as small as they can be while still looking good:

{
    "class": "tabset_control",
    "tab_height": 20
}

Tall Tabs

Alternatively, if you prefer taller square tabs, we can easily do that too:

{
    "class": "tabset_control",
    "tab_height": 35
}

Another theme feature that isn't in the core of Soda Theme, but could easily be set via a user theme, is the colouring of tab labels when there are unsaved changes.

Blue Modifed Tabs

To colour modified tab labels blue for Soda Dark, add the following to your user theme file:

{
    "class": "tab_label",
    "settings": ["highlight_modified_tabs"],
    "parents": [{"class": "tab_control", "attributes": ["dirty"]}],
    "fg": [120, 170, 250]
}

To do a similar customisation for Soda Light, use the colour "fg": [20, 100, 220].

Red Modifed Tabs

Or if you prefer red modified tab labels for Soda Dark, you could use:

{
    "class": "tab_label",
    "settings": ["highlight_modified_tabs"],
    "parents": [{"class": "tab_control", "attributes": ["dirty"]}],
    "fg": [245, 100, 90]
}

To do a similar customisation for Soda Light, use the colour "fg": [220, 30, 15].

Share Your Customisations

Please continue to make suggestions, raise tickets and send pull requests for any changes that you feel would be beneficial to the majority of users so they can be added to the core of Soda Theme.

However, if your customisation appeals to a smaller sub-set of users, the user theme feature is a convenient way to tweak aspects of Soda Theme for your installation without relying on the code changing in the main line. It is also a great way to share your changes with other users to help them adjust their own setup.

Happy tweaking.