Color themes are stored in JSON format files, with the .theme extension.

In the KSyntaxHighlighting source code, the JSON files of built-in themes are located in the data/themes/ directory. Note that in text editors, the built-in themes are compiled into the KSyntaxHighlighting library, therefore, the way to access them is through the source code or by exporting them from the GUI to manage themes of KTextEditor.

It is also possible to easily add additional or custom themes, which are loaded from the file system. User-customized theme files are located in the org.kde.syntax-highlighting/themes/ directory in your user folder, which you can find with the command qtpaths --paths GenericDataLocation and are commonly $HOME/.local/share/ and /usr/share/.

In Flatpak and Snap packages, the above directory will not work as the data location is different for each application. In a Flatpak application, the location of custom theme files is usually $HOME/.var/app/flatpak-package-name/data/org.kde.syntax-highlighting/themes/ and in a Snap application that location is $HOME/snap/snap-package-name/current/.local/share/org.kde.syntax-highlighting/themes/.

On Windows® these files are located %USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes. %USERPROFILE% usually expands to C:\Users\user-name.

In summary, for most configurations the custom themes directory is as follows:

If multiple theme files exist with the same name, the file with the highest revision will be loaded.

The structure of a JSON file is explained on their website. Basically, a JSON format file consists of:

The nomenclature “key”, “value”, “object” and “array” will be used in this article. If this is your first time working with JSON files, understanding them is as simple as looking at the examples below.

The root object of the color theme JSON file contains the following schema keys:

The JSON language does not support comments. However, you can use the optional key _comments in the root object to write comments, for example, if you are adapting an existing theme you can put the URL of the original repository. The most practical way is to use an array of strings.

Below is an example file for the “Breeze Light” theme. You can notice that, to avoid the example being too large, the editor-colors and text-styles objects do not contain all the required keys. You can see the full archive of the “Breeze Light” theme in the KSyntaxHighlighting repository.

{
    "_comments": [
        "This is a comment.",
        "If this theme is an adaptation of another, put the link to the original repository."
    ],
    "metadata": {
        "name" : "Breeze Light",
        "revision" : 5,
        "copyright": [
            "SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>",
            "SPDX-FileCopyrightText: 2016 Dominik Haumann <dhaumann@kde.org>"
        ],
        "license": "SPDX-License-Identifier: MIT"
    },
    "editor-colors": {
        "BackgroundColor" : "#ffffff",
        "CodeFolding" : "#94caef",
        "BracketMatching" : "#ffff00",
        "CurrentLine" : "#f8f7f6",
        "IconBorder" : "#f0f0f0",
        "IndentationLine" : "#d2d2d2",
        "LineNumbers" : "#a0a0a0",
        "CurrentLineNumber" : "#1e1e1e",
        The other editor color keys...

    },
    "text-styles": {
        "Normal" : {
            "text-color" : "#1f1c1b",
            "selected-text-color" : "#ffffff",
            "bold" : false,
            "italic" : false,
            "underline" : false,
            "strike-through" : false
        },
        "Keyword" : {
            "text-color" : "#1f1c1b",
            "selected-text-color" : "#ffffff",
            "bold" : true
        },
        "Function" : {
            "text-color" : "#644a9b",
            "selected-text-color" : "#452886"
        },
        "Variable" : {
            "text-color" : "#0057ae",
            "selected-text-color" : "#00316e"
        },
        The other text style keys...

    },
    "custom-styles": {
        "ISO C++": {
            "Data Type": {
                "bold": true,
                "selected-text-color": "#009183",
                "text-color": "#00b5cf"
            },
            "Keyword": {
                "text-color": "#6431b3"
            }
        },
        "YAML": {
            "Attribute": {
                "selected-text-color": "#00b5cf",
                "text-color": "#00b5cf"
            }
        }
    }
}

The JSON object of the metadata key contains relevant information on the theme. This object has the following keys:

"metadata": {
    "name" : "Breeze Light",
    "revision" : 5,
    "copyright": [
        "SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>",
        "SPDX-FileCopyrightText: 2016 Dominik Haumann <dhaumann@kde.org>"
    ],
    "license": "SPDX-License-Identifier: MIT"
}

Corresponds to the colors of the text editing area.

In the JSON theme file, the respective key editor-colors has as value an object where each key references an attribute color of the text editor. Here, all available keys are mandatory, their values are strings with hexadecimal color codes, like “#00B5CF”.

In the GUI to manage themes of KTextEditor, these attributes can be modified in the Colors tab.

The available keys are the following; the keys used in the JSON file are listed in bold, the names used in the GUI are shown in parentheses.

The default text styles are inherited by the highlight text styles, allowing the editor to present text in a very consistent way, for example comment text is using the same style in almost all of the text formats that KSyntaxHighlighting can highlight.

In the JSON file, the respective key text-styles has as value an object where each key corresponds to the name of a default text style, which are equivalent to those used in the syntax highlighting definitions. Here, all available text style keys are mandatory, these are listed below.

"text-styles": {
    "Normal" : {
        "text-color" : "#1f1c1b",
        "selected-text-color" : "#ffffff",
        "bold" : false,
        "italic" : false,
        "underline" : false,
        "strike-through" : false
    },
    "Keyword" : {
        "text-color" : "#1f1c1b",
        "selected-text-color" : "#ffffff",
        "bold" : true
    },
    "Function" : {
        "text-color" : "#644a9b",
        "selected-text-color" : "#452886"
    },
    The other text style keys...
}

In the GUI to manage color themes of KTextEditor, these attributes can be modified in the Default Text Styles tab. The name in the list of styles is using the style configured for the item, providing you with an immediate preview when configuring a style. Each style lets you select common attributes as well as foreground and background colors. To unset a background color, right-click to use the context menu.

The available text style keys are the following; the keys used in the JSON file are listed in bold, the names used in the GUI are shown in parentheses if they are different.

Here you can establish text styles for a specific syntax highlighting definition, overriding the default text style described in the previous section.

In the JSON theme file, this corresponds to the custom-styles key, whose value is an object where each subschema key corresponds to the name of a syntax highlighting definition. Its value is an object where each key refers to the style attributes name defined in the itemData elements of the syntax highlighting XML file, and the respective value is a sub-object with the keys text-color, selected-text-color, bold, italic, underline, strike-through, background-color and selected-background-color, defined in the previous section. Each of these values are optional, since if they are not present, the style set in text-styles is considered.

For example, in this piece of code, the “ISO C++” syntax highlighting definition has a special text style for the “Type Modifiers” and “Standard Classes” attributes. In the corresponding XML file “isocpp.xml”, the defined attribute “Standard Classes” uses the default style BuiltIn (or dsBuiltIn). In this attribute, only the value of text-color is overwritten by the new color “#6431b3”.

"custom-styles": {
    "ISO C++": {
        "Standard Classes": {
            "text-color": "#6431b3"
        },
        "Type Modifiers": {
            "bold": true,
            "selected-text-color": "#009183",
            "text-color": "#00b5cf"
        }
    }
}

In the GUI to manage themes of KTextEditor, these attributes can be modified in the Highlighting Text Styles tab. By default, the editor preselects the highlighting of the current document. You will notice that many highlights contain other highlights represented by groups in the style list. For example most highlights import the “Alert” highlight, and many source code formats import the “Doxygen” highlight.

To create a new theme, it is first necessary to copy an existing one. Select an existing theme which you want to use as a base, such as “Breeze Light” or “Breeze Dark”, and click Copy. Then write a name for the new theme.

If you want to modify a built-in or read-only theme, you must first copy it under a different name.

You can export a selected theme (including built-in ones) to a JSON file with .theme extension, with the Export button. This will open a dialog to save the file. To add a color theme from an external JSON file, just press the Import button and select the .theme file from the dialog.

An important aspect when working with color themes is to choose a text contrast that makes it easier to read, especially in combination with the background.

The Kontrast application is a color contrast checker. It tells you that the text color and background color combinations are readable and accessible, so this is an excellent tool to help you create color themes.

You can download Kontrast from the KDE Applications website or from the Flatpak package on Flathub (only in GNU/Linux).

The GNOME Contrast application is similar. You can download the Flatpak package on Flathub (only in GNU/Linux).

KSyntaxHighlighting includes more than 300 syntax highlighting definitions, therefore it is ideal that you make sure your new theme looks good in all syntax highlighting definitions. The built-in color themes have the following similarities that it is recommended (but not required) to follow to achieve a correct display of all syntax highlighting definitions:

Most of the syntax highlighters are intended to look good on the default themes “Breeze Light” and “Breeze Dark”, therefore, another way to maintain consistency is to use similar colors in the text styles, like green for “Preprocessor” and “Others”, blue for “DataType” and “Attribute”, or purple for “Function”.

Note that these recommendations are not mandatory when creating and publishing a theme.