How to switch, customize, or write themes

gagbo · October 7, 2020, 8:37pm

Themes control Emacs’ color scheme. You will no doubt want to customize them, if Doom’s or Emacs’ default themes don’t suit you. This usually means one of four things:

You want to change the active theme
You want to tweak the current theme a little
You want a whole new theme based on the current one
You want to write a whole new theme from scratch

This guide will walk you through each.

Changing the current theme

If the theme is already installed, changing the theme is a one-liner:

;;; add to $DOOMDIR/config.el
(setq doom-theme 'theme-name)
;; or
(load-theme 'theme-name t)

Install a third party theme

If the theme is not installed, use Doom’s Package Manager to install a third party theme or copy its *-theme.el file to the $DOOMDIR/themes/ directory (creating it if it doesn’t exist).

Tweak the current theme

An Emacs theme is comprised of faces. Faces are styles applied to text or UI elements in Emacs. To tweak a theme, you must tweak its faces.

Use the custom-set-faces! macro to do so. For example, to make the cursor red:

(custom-set-faces!
  '(cursor :background "#FF0000"))

Use SPChf (or C-hf for users with Evil disabled) followed by custom-set-faces\! to look up documentation and more demonstrations of its use.

If you are using one of Doom’s built-in themes, then an API for retrieving palette variables is available for you to use. With backquoting, you can craft more flexible modifications to those faces:

(custom-set-faces!
  `(markdown-code-face :background ,(doom-color 'bg-alt))
  `(markdown-markup-face :foreground ,(doom-color 'blue)))

To see what palette variables are available, check out the theme’s source code. For example, this is doom-one’s palette.

Looking up Faces

To look up what face you’ll need to modify, there are several options:

Place the cursor on a character and call M-x describe-char (on SPCh’ in normal mode or C-h’ for non-evil users). A popup buffer will appear with diagnostics about the character under your cursor. Near the bottom, the overlays and text properties present are listed along with the faces that are applied to them, like so:
```
There is an overlay here:
 From 110 to 153
  face                 hl-line
  priority             -50
  window               #<window 58 on rjsx-mode.el>

There are text properties here:
  face                 font-lock-comment-face
  fontified            t
```
This indicates the hl-line and font-lock-comment-face faces are in use here.

M-x describe-faces (or M-x list-faces-display) will list all known faces and an inline preview of them. This is bound to SPChF by default (or C-hF for non-evil users).

This only lists faces that have been defined. i.e. A face belonging to a package that hasn’t yet loaded will be absent.

Write your own theme

Doom looks for themes in $DOOMDIR/themes/. That is where your custom themes must go.

A theme’s filename must end in -theme.el or Emacs won’t recognize it.

Once it’s there, you can (setq doom-theme 'X) to make it your default theme. As for how to write the theme…

Writing a theme based on a Doom theme

Using a Doom theme as a base offers two advantages:

You gain access to doomemacs/themess API.
Any theme based on a Doom theme provides theme support for a wide number of packages, so you don’t have to.

Before you can create your own Doom theme derivative, doomemacs/themes must be installed (and it will be if the :ui doom module is enabled – otherwise, install it with Doom’s Package Manager).

This example will use solarized as a base to build your own selenized theme:

Create the $DOOMDIR/themes directory if it doesn’t already exist.
Download doom-solarized-dark-theme.el from the doomemacs/themes repo to $DOOMDIR/themes/.
Rename $DOOMDIR/themes/doom-solarized-dark-theme.el to $DOOMDIR/themes/doom-selenized-dark-theme.el.

Replace the following line in doom-selenized-dark-theme.el:

-(def-doom-theme doom-solarized-dark
+(def-doom-theme doom-selenized-dark

Tweak the color palette as you like.
Add (setq doom-theme 'doom-selenized-dark) to $DOOMDIR/config.el.

Writing a non-Doom or vanilla theme

The main advantage of using a vanilla theme is that it is a single, standalone file, but will require more work to support third party packages.

Create the $DOOMDIR/themes directory if it doesn’t already exist.
Download or write a theme in $DOOMDIR/themes/modus-operandi-theme.el
Add (setq doom-theme 'modus-operandi) to $DOOMDIR/config.el