Master Doom Emacs: A Fast, Keyboard‑Centric Emacs Configuration Guide

Overview

Doom Emacs is an Emacs distribution that focuses on fast startup, a fully keyboard‑driven workflow, and a modular configuration. It targets users who are comfortable with Vim‑style keybindings but want to leverage Emacs’ extensibility.

Prerequisite: Install Emacs

A recent stable Emacs (26.1 or newer) is required. Installation examples:

macOS (Homebrew):

brew tap railwaycat/emacsmacport
brew install --cask emacs-mac
# Ensure /usr/local/bin precedes /usr/bin in /etc/paths

Arch Linux: pacman -S emacs Debian (10+): apt install emacs Other distributions: use the native package manager or third‑party tools (snap, nix, flatpak, Linuxbrew) to obtain Emacs 26.1+.

Install Doom Emacs

Doom lives in ~/.emacs.d. The recommended installation steps are:

# Backup any existing configuration
[ -d ~/.emacs.d ] && mv -v ~/.emacs.d ~/.emacs.d.bak
[ -f ~/.emacs ] && mv -v ~/.emacs ~/.emacs.bak
# Clone the develop branch
git clone -b develop https://github.com/hlissner/doom-emacs.git ~/.emacs.d
# Initialise the configuration (downloads plugins and fonts)
~/.emacs.d/bin/doom quickstart

The first run may take 30 minutes or more on a slow network because it fetches many plugins and fonts.

Configuration layout

User customisations are stored in ~/.doom.d/: init.el – list of enabled modules. config.el – personal Emacs Lisp settings. packages.el – additional packages to install.

Core concepts

Keybindings : The space bar ( SPC) is the primary prefix. Example: SPC f . searches the current directory; C-g aborts an unfinished key sequence.

Buffers : Each opened file creates a buffer. Switch with SPC b or SPC <.

Windows : Split a frame into windows; manage with SPC w or C-w.

Frames : Physical OS windows; accessed via C-x 5 (rarely needed).

Major/Minor modes : Major mode reflects file type (e.g., .py → python‑mode). Minor modes add features such as line numbers ( SPC t l).

Projects & workspaces : Directories containing a .git or .projectile are recognised as projects. Switch projects with SPC p p; manage workspaces with SPC TAB.

Session : On exit Doom saves the session; restore with SPC q l.

Server/Client : Doom runs an Emacs server; files can be opened from the terminal with emacsclient -n filename.

Management commands

~/.emacs.d/bin/doom help      # List all Doom commands
doom upgrade                 # Upgrade Doom Emacs
doom update                  # Update all plugins
doom doctor                  # Diagnose configuration problems

Help shortcuts include SPC h k <key> (describe a key), SPC h f <command> (describe a command), and SPC h I (browse documentation).

Modules

Modules are declared in ~/.doom.d/init.el. Example snippet:

:lang
  python +ipython   # Python support with IPython integration
:ui
  +pretty-code      # Render symbols like "∀ i ∈ array"
:completion
  ivy +icons +fuzzy # Ivy with icons and fuzzy matching

After editing the module list, run ~/.emacs.d/bin/doom refresh to install or update the associated packages.

Custom module example – Youdao Dictionary

This example shows how to create a personal module mytools/youdao that installs the youdao-dictionary.el package and binds SPC h y to look up the word under the cursor.

(package! youdao-dictionary)

(use-package! youdao-dictionary
  :config
  (map! :leader
        :prefix ("h" . "help")
        :desc "Lookup Dictionary"
        :n "y" #'youdao-dictionary-search-at-point-tooltip))

Add the module to ~/.doom.d/init.el:

:mytools
  youdao

Refresh the configuration and reload:

~/.emacs.d/bin/doom refresh   # Install the new package
SPC h r r                     # Reload Doom configuration

Further resources

Emacs China forum: https://emacs-china.org

Emacs China Telegram: https://t.me/emacszh

Doom Emacs wiki: https://github.com/hlissner/doom-emacs/wiki

Chinese Emacs tutorials: https://github.com/lujun9972/emacs-document