Doom Emacs: how to customize themes

how-to-customize-themes.md

< back to index

Important

This gist is temporary until the new documentation (docs.doomemacs.org) and community wiki (wiki.doomemacs.org) have been published.

How to customize themes

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:

1. You want to change the active theme
2. You want to tweak the current theme a little
3. You want a whole new theme based on the current one
4. Or you want to write a whole new theme from scratch

This guide will walk you through options 1 and 2.

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"))

Tip

Use SPC h f (or C-h f 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)))

Tip

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 [kbd]SPC h '[/kbd] in normal mode or [kbd]C-h '[/kbd] 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 [kbd]SPC h F[/kbd] by default (or [kbd]C-h F[/kbd] for non-evil users).

Warning

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.

Warning

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...