Creating Themes

SideNotes allows to adjust its look and feel by choosing themes. It offers some predefined ones. More themes you will find on the Themes page.

You can also create your own themes and adjust SideNotes look and feel according to your preferences.

Getting Started

SideNotes stores themes in *.sntheme files. It's actually a JSON file, so editing it is very simple. To get started, download some theme from Themes page and open the file in some code editor.

To edit the file, we recommend to use Visual Studio Code, because it respects schema definition, so you have syntax completion and color rendering right in the editor.

Visual Studio Code – Set Up

Because the file has no .json extension, you need to define new file extension. You can do it by editing settings (press ⇧⌘p and type Open Settings). Simply add "*.sntheme": "json to files.associations. Here is how sample settings file looks like:

{
    "files.associations": {
        "*.sntheme": "json"
    }
}

Next time you open a theme, you'll get syntax highlighting, autocompletion and color rendering.

Theme Installation

To install a theme, double click it and SideNotes will copy it into its directory.

Then you can edit that file directly. Once its changed, SideNotes updates its look and feel.

To access installed theme, go to Preferences → Appearance and click Manage button. Then from the contextual menu (⌃ click on theme) choose Show in Finder* option.

Basic Assumptions

Editing themes seems to quite obvious. We won't describe everything here. We rather describe the basic assumptions.

Themes Overwrites Default Settings

Take a look at the simplest theme code:

{
    "$schema": "https://www.apptorium.com/schemas/sntheme.json"
}

It does not change anything. All the appearance is derived from default look and feel.

In the second line, you can see schema definition. It's not required, but we recommend it. It helps text editors (like VSC) to recognize the file syntax.

Theme Structure

In the following example, you can see the basic structure of a theme (without defining any details):

{
    "$schema": "https://www.apptorium.com/schemas/sntheme.json",
    "light": {
        "folders": {
            "header": {
            },
            "list": {
            }
        },
        "folder": {
            "header": {
            },
            "notes": {
                "clean": {
                },
                "colors": [
                    { },
                    { },
                    { },
                    { },
                    { },
                    { }
                ]
            }
        },
        "search": {
            "searchField": {
                "shadow": {
                }
            }
        }
    },
    "dark": {
        (...)
    },
    "any": {
        (...)
    }
}

On the highest level you can see light, dark and any. They are responsible for defining particular appearances according to system appearance. Notice that light and any are not defined here. They have the same structure as dark.

In the next level you can see folders, folder and search. They define looks of folder list, a folder (with notes) and search view.

As you see, the theme structure goes deeper and deeper and it describes the next elements according to element names.

It is worth mentioning how notes work. It defines look and feel of notes. A regular note is described in clean. In colors, there are note color variations. Here is a sample definition of note look:

"clean": {
    "backgroundColor": "#000000aa",
    "enableVisualEffects": true,
    "textColor": "#129712",
    "secondaryTextColor": "#149414",
    "tertiaryTextColor": "#669666b6",
    "linkColor": "#003cff",
    "buttonColor": "#149414c7",
    "quote": {
        "textColor": "#9ccc9c"
    },
    "mark": {
        "backgroundColor": "#00bb10"
    },
    "codeBlock": {
        "textColor": "#62c05d"
    },
    "code": {
        "textColor": "#62c05d"
    },
    "checkMark": {
        "borderColor": "#0e6b0e",
        "backgroundColor": "#ffffff00",
        "doneBorderColor": "#0e6b0e",
        "doneBackgroundColor": "#ffffff00",
        "checkMarkColor": "#0e6b0e"
    },
    "filePreview": {
        "backgroundColor": "#2b532999"
    }
}

Color Format

Colors are defined in hexadecimal numbers – just like in CSS:

• #rrggbb, example: #1fabc3;
• #rrggbbaa, example: #00000033 – black with 0x33 alpha;
• #rgb, example: #f3a. It is a short form of #ff33aa.

App UI Appearance

Ideally, themes should provide light and dark appearance. By default, SideNotes chooses appearance according to system settings. However, you can define dark or light mode only. To do so, you need to define it in any and provide system appearance (light or dark) for the app. Example:

{
    "$schema": "https://www.apptorium.com/schemas/sntheme.json",
    "any": {
        "systemAppearance": "dark"
    }
}

Dark and Light Inherit Settings From Any

If you need to define common settings, define them in any. Dark and Light will inherit from them.

Note Colors Inherit Settings from Clean Note

In the following example, you can see a clean note (a note with no color set) and first color variation. All color variations inherit their settings from clean note. In this example, textColor is inherited.

{
    "$schema": "https://www.apptorium.com/schemas/sntheme.json",
    "light": {
        "folder": {
            "notes": {
                "clean": {
                    "backgroundColor": "#000000aa",
                    "textColor": "#129712"
                },
                "colors": [
                    {
                        "backgroundColor": "#550404"
                    },

Background Color or Gradient

In notes, you can additionally define backgroundGradient. However, bar (Note Colors set to Bar in Preferences → Appearance) still uses backgroundColor, so it is necessary to be implemented.

Gradient has the following syntax:

"backgroundGradient": {
    "start": "#aaa",
    "end": "#bbb"
}