Custom Themes#
There are a few ways you can customise novelWriter yourself. Currently, you can relatively easily add new GUI themes. You can also add new icon themes, although this is not as straightforward.
Colour Themes#
Adding your own colour themes is relatively easy, although it requires that you manually edit config files with colour values. The themes are defined by simple plain text config files with meta data and colour settings.
In order to make your own versions, first copy one of the existing files to your local computer and modify it as you like.
The existing colour themes are stored in novelwriter/assets/themes.
Remember to also change the name of your theme by modifying the name setting at the top of the
file, otherwise you may not be able to distinguish them in Preferences.
For novelWriter to be able to locate the custom theme files, you must copy them to the
Application Data location in your home or user area. There should be a folder
there named themes for colour themes. These folders are created the first time you start
novelWriter.
Once the files are copied there, they should show up in Preferences with the label you
set as name inside the file.
Note
The theme file formats change regularly in new releases. It is up to you to keep custom theme files up to date.
The Theme File Format#
A colour theme .conf file consists of the following settings:
[Main]
name = Default Light Theme
mode = light
author = Veronica Berglyd Olsen
credit = Veronica Berglyd Olsen
url = https://github.com/vkbo/novelWriter
[Base]
base = #fcfcfc
default = #303030
faded = #6c6c6c
red = #a62a2d
orange = #b36829
yellow = #a39c34
green = #296629
cyan = #269999
blue = #3a70a6
purple = #b35ab3
[Project]
root = blue
folder = yellow
file = default
title = green
chapter = red
scene = blue
note = yellow
active = green
inactive = red
disabled = faded
[Icon]
tool = default
sidebar = default
accept = green
reject = red
action = blue
altaction = orange
apply = green
create = yellow
destroy = faded
reset = green
add = green
change = green
remove = red
shortcode = default
markdown = orange
systemio = yellow
info = blue
warning = orange
error = red
[Palette]
window = base:D105
windowtext = default
base = base
alternatebase = #e0e0e0
text = default
tooltipbase = #ffffc0
tooltiptext = #15150d
button = #efefef
buttontext = default
brighttext = base
highlight = #3087c6
highlightedtext = base
link = blue
linkvisited = blue
accent = #3087c6
[GUI]
helptext = #5c5c5c
fadedtext = #6c6c6c
errortext = red
[Syntax]
background = base
text = default
line = default:32
link = blue
headertext = green
headertag = green:L135
emphasis = orange
whitespace = orange:64
dialog = blue
altdialog = red
note = yellow:D125
hidden = faded
shortcode = blue
keyword = red
tag = green
value = green
optional = blue
spellcheckline = red
errorline = green
replacetag = green
modifier = blue
texthighlight = yellow:72
Theme Sections#
The theme file is made up of different sections depending on what part of novelWriter the theme affects.
Section |
Description |
|---|---|
|
Meta data about the theme, You must at least set |
|
The base colours of the theme. These are also selectable colours in various places inside the app, like for icon colours in Preferences. |
|
The colours used for icons and markers for the different project item types. |
|
The colours used for icons and buttons on the user interface. The names correspond to button and icon roles. |
|
The colours used for styling the user interface. The values correspond to the ColorRole values in the Qt library. |
|
The colours used for styling additional elements of the user interface. |
|
The colours used for syntax highlighting in documents. |
Colour Value Formats#
There are several ways to enter colour values:
Syntax |
Description |
|---|---|
|
A CSS style hexadecimal values, like |
|
A CSS style hexadecimal values with transparency, like |
|
A name referring to one of the colours already specified under the |
|
A name referring to one of the colours already specified under the |
|
A name referring to one of the colours already specified under the |
|
A name referring to one of the colours already specified under the |
|
A set of red, green and blue numbers in the range |
|
A set of red, green, blue and alpha numbers in the range |
New in version 2.5: The fadedtext and errortext theme colour entries were added.
New in version 2.7: The icontheme setting was dropped as the icon theme is now its own setting.
The [Icons] and [Project] sections were added, and the status* settings removed.
New in version 2.8: The [Syntax] section was moved into the main theme file. Previously, these settings were in
their own file. The [Icons] section was renamed to [Base], and a new [Icon] section
added for button and icon roles. Added the line and whitespace settings. Dropped the
license, licenseurl, and description settings. The author field is now required
if the theme is included in the app, but not for user themes.
Icon Themes#
Icon themes are not straightforward to add, but if you want to make the effort, this section describes how to do it.
The existing icon themes are stored in novelwriter/assets/icons.
As with colour themes, remember to change the name of your theme by modifying the name setting
at the top of the file, otherwise you may not be able to distinguish them in Preferences.
For novelWriter to be able to locate the custom theme files, you must copy them to the
Application Data location in your home or user area. There should be a folder
there icons for icon themes. These folders are created the first time you start novelWriter.
The Icons File Format#
Icon themes are kept in files with the .icons file extension. The file format is a custom
format with entries on the form section:key = value.
# Meta
meta:name = Material Symbols - Rounded Medium
meta:author = Google Inc
meta:license = Apache 2.0
# Icons
icon:alert_error = <svg ...>
icon:alert_info = <svg ...>
icon:alert_question = <svg ...>
icon:alert_warn = <svg ...>
icon:cls_archive = <svg ...>
icon:cls_character = <svg ...>
icon:cls_custom = <svg ...>
icon:cls_entity = <svg ...>
icon:cls_none = <svg ...>
icon:cls_novel = <svg ...>
icon:cls_object = <svg ...>
icon:cls_plot = <svg ...>
icon:cls_template = <svg ...>
icon:cls_timeline = <svg ...>
icon:cls_trash = <svg ...>
icon:cls_world = <svg ...>
The icon keys are associated with icon placement locations inside novelWriter, and the template for them is defined in the script that generates the default icon themes.
The script can be found under utils/icon_themes.py in the source code.
This file includes all the code needed to generate the themes that are included in novelWriter. The
icon keys are mapped to icon keys from the specific themes in JSON files in the icon_themes
folder next to the script. This is the recommended way to generate these themes. Doing it manually
is not advisable.
Icon Value Format#
As can be seen from the example, an icon is defined in the icon section with a key and an
in-line SVG XML block. The XML must fit on one line and obey the following rules:
It must be single colour, that is, the fill colour attribute must be able to colourise the entire icon.
The fill colour attribute must be defined and must be set to:
fill="#000000". This value is replaced by the relevant theme colour when the icon is processed in novelWriter.
New in version 2.7: The icon theme files were added. Previously, icons were stored as individual SVG files with a config file mapping the file names to the internal icon keys.