# 3.6. Theming

Alot can be run in 1, 16 or 256 colour mode. The requested mode is determined by the command-line parameter -C or read from option colourmode config value. The default is 256, which scales down depending on how many colours your terminal supports.

Most parts of the user interface can be individually coloured to your liking. To make it easier to switch between or share different such themes, they are defined in separate files (see below for the exact format). To specify the theme to use, set the theme config option to the name of a theme-file. A file by that name will be looked up in the path given by the themes_dir config setting which defaults to $XDG_CONFIG_HOME/alot/themes, and `~/.config/alot/themes/`, if XDG_CONFIG_HOME is empty or not set. If the themes_dir is not present then the contents of $XDG_DATA_DIRS/alot/themes will be tried in order. This defaults to `/usr/local/share/alot/themes` and `/usr/share/alot/themes`, in that order. These locations are meant to be used by distro packages to put themes in.

## 3.6.1. Theme Files

contain a section for each MODE plus “help” for the bindings-help overlay and “global” for globally used themables like footer, prompt etc. Each such section defines colour attributes for the parts that can be themed. The names of the themables should be self-explanatory. Have a look at the default theme file at `alot/defaults/default.theme` and the config spec `alot/defaults/default.theme` for the exact format.

## 3.6.2. Colour Attributes

Attributes are sextuples of urwid Attribute strings that specify foreground and background for mono, 16 and 256-colour modes respectively. For mono-mode only the flags blink, standup, underline and bold are available, 16c mode supports these in combination with the colour names:

    brown    dark red     dark magenta    dark blue    dark cyan    dark green
    yellow   light red    light magenta   light blue   light cyan   light green
    black    dark gray    light gray      white

In high-colour mode, you may use the above plus grayscales g0 to g100 and colour codes given as # followed by three hex values. See here and here for more details on the interpreted values. A colour picker that makes choosing colours easy can be found in `alot/extra/colour_picker.py`.

As an example, check the setting below that makes the footer line appear as underlined bold red text on a bright green background:

    [[global]]
      #name    mono fg     mono bg   16c fg                        16c bg         256c fg                 256c bg
      #        |                 |   |                             |              |                             |
      #        v                 v   v                             v              v                             v
      footer = 'bold,underline', '', 'light red, bold, underline', 'light green', 'light red, bold, underline', '#8f6'

## 3.6.3. Search mode threadlines

The subsection ‘[[threadline]]’ of the ‘[search]’ section in Theme Files determines how to present a thread: here, attributes ‘normal’ and ‘focus’ provide fallback/spacer themes and ‘parts’ is a (string) list of displayed subwidgets. Possible part strings are:

- authors

- content

- date

- mailcount

- subject

- tags

For every listed part there must be a subsection with the same name, defining

normal:

  attribute used for this part if unfocussed

focus:

  attribute used for this part if focussed

width:

  tuple indicating the width of the part. This is either (‘fit’, min, max) to force the widget to be at least min and at most max characters wide, or (‘weight’, n) which makes it share remaining space with other ‘weight’ parts.

alignment:

  how to place the content string if the widget space is larger. This must be one of ‘right’, ‘left’ or ‘center’.

### 3.6.3.1. Dynamic theming of thread lines based on query matching

To highlight some thread lines (use different attributes than the defaults found in the ‘[[threadline]]’ section), one can define sections with prefix ‘threadline’. Each one of those can redefine any part of the structure outlined above, the rest defaults to values defined in ‘[[threadline]]’.

The section used to theme a particular thread is the first one (in file-order) that matches the criteria defined by its ‘query’ and ‘tagged_with’ values:

- If ‘query’ is defined, the thread must match that querystring.

- If ‘tagged_with’ is defined, is value (string list) must be a subset of the accumulated tags of all messages in the thread.

Note

that ‘tagged_with = A,B’ is different from ‘query = “is:A AND is:B”’: the latter will match only if the thread contains a single message that is both tagged with A and B.

Moreover, note that if both query and tagged_with is undefined, this section will always match and thus overwrite the defaults.

The example below shows how to highlight unread threads: The date-part will be bold red if the thread has unread messages and flagged messages and just bold if the thread has unread but no flagged messages:

    [search]
        # default threadline
        [[threadline]]
            normal = 'default','default','default','default','#6d6','default'
            focus = 'standout','default','light gray','dark gray','white','#68a'
            parts = date,mailcount,tags,authors,subject
            [[[date]]]
                normal = 'default','default','light gray','default','g58','default'
                focus = 'standout','default','light gray','dark gray','g89','#68a'
                width = 'fit',10,10
            # ...

        # highlight threads containing unread and flagged messages
        [[threadline-flagged-unread]]
            tagged_with = 'unread','flagged'
            [[[date]]]
                normal = 'default','default','light red,bold','default','light red,bold','default'

        # highlight threads containing unread messages
        [[threadline-unread]]
            query = 'is:unread'
            [[[date]]]
                normal = 'default','default','light gray,bold','default','g58,bold','default'

## 3.6.4. Tagstring Formatting

One can specify how a particular tagstring is displayed throughout the interface. To use this feature, add a section [tags] to you alot config (not the theme file) and for each tag you want to customize, add a subsection named after the tag. Such a subsection may define

normal:

  attribute used if unfocussed

focus:

  attribute used if focussed

translated:

  fixed string representation for this tag. The tag can be hidden from view, if the key translated is set to ‘’, the empty string.

translation:

  a pair of strings that define a regular substitution to compute the string representation on the fly using re.sub. This only really makes sense if one uses a regular expression to match more than one tagstring (see below).

The following will make alot display the “todo” tag as “TODO” in white on red.

    [tags]
      [[todo]]
        normal = '','', 'white','light red', 'white','#d66'
        translated = TODO

Utf-8 symbols are welcome here, see e.g. https://panmental.de/symbols/info.htm for some fancy symbols. I personally display my maildir flags like this:

    [tags]

      [[flagged]]
        translated = ⚑
        normal = '','','light red','','light red',''
        focus = '','','light red','','light red',''

      [[unread]]
        translated = ✉

      [[replied]]
        translated = ⏎

      [[encrypted]]
        translated = ⚷

You may use regular expressions in the tagstring subsections to theme multiple tagstrings at once (first match wins). If you do so, you can use the translation option to specify a string substitution that will rename a matching tagstring. translation takes a comma separated pair of strings that will be fed to `re.sub()`. For instance, to theme all your nmbug tagstrings and especially colour tag notmuch::bug red, do the following:

    [[notmuch::bug]]
      translated = 'nm:bug'
      normal = "", "", "light red, bold", "light blue", "light red, bold", "#88d"

    [[notmuch::.*]]
      translation = 'notmuch::(.*)','nm:\1'
      normal = "", "", "white", "light blue", "#fff", "#88d"

## 3.6.5. ANSI escape codes

Alot’s message display will interpret ANSI escape codes in the “body” text to be displayed.

You can use this feature to let your HTML renderer interpret colours from html mails and translate them to ANSI escapes. For instance, elinks can do this for you if you use the following entry in your ~/.mailcap:

    text/html; elinks -force-html -dump -dump-color-mode 3 -dump-charset utf8 -eval 'set document.codepage.assume = "%{charset}"' %s; copiousoutput

## 3.6.6. Test your theme

Use the script in extra/theme_test.py to test your theme file. You should test with different terminal configurations, take black-on-white and white-on-black themes in account.