doom/docs/doom-macros-reference.md

Doom Emacs Macros and Keywords Reference

This document describes the macros and their keywords used in Doom Emacs 3 configuration.

Table of Contents

• doom! - Module Declaration
• package! - Package Declaration
• use-package! / use-package - Package Configuration
• add-hook! - Hook Registration
• setq-hook! - Set Variables in Hooks
• map! - Keybinding
• after! - Run Code After Package
• load! - Load Sub-config Files

---

doom! - Module Declaration

Declares enabled modules and their flags in init.el.

Location: init.el

Syntax:

(doom! :module
       (module +flag1 +flag2)
       :another-module)

Keywords: Module names and optional flags (prefixed with +).

Example:

(doom! :completion
       (company +orderless)
       :lang
       (org +brain +crypt)
       :tools
       lsp)

---

package! - Package Declaration

Declares packages to install in packages.el.

Location: packages.el

Keyword	Description
:recipe	MELPA-style straight recipe with :host, :repo, :branch, :files, etc.
:disable	Disable the package (t to disable)
:built-in	Mark as built-in ('prefer)
:pin	Pin to a specific commit hash
:local-repo	Local repository path

Example:

(package! super-save)

(package! copilot
  :recipe (:host github :repo "copilot-emacs/copilot.el" :files ("*.el")))

(package! org-re-reveal :disable t)

---

use-package! / use-package - Package Configuration

Configures packages with a declarative DSL.

Location: config.el or modular config files

Keyword	Description
:init	Code to run immediately (before package loads)
:config	Code to run after package loads
:defer	Defer loading (boolean or integer seconds)
:after	Load after another package or packages
:hook	Hook into specific hooks
:bind	Define key bindings
:commands	Autoload commands
:custom	Set customization variables
:custom-face	Customize faces
:pre-init	Run before package's own :init
:pre-config	Run before package's own :config
:post-init	Run after package's own :init
:post-config	Run after package's own :config

Example:

(use-package! org-roam
  :after org
  :custom
  (org-roam-directory "~/org/roam")
  (org-roam-completion-everywhere t)
  :config
  (org-roam-db-autosync-mode)
  :bind (("C-c n l" . org-roam-buffer-toggle)
         ("C-c n f" . org-roam-node-find)))

Hook Syntax

(use-package! some-package
  :hook ((prog-mode . some-package-mode)
         (org-mode . some-package-mode)))

Bind Syntax with Maps

(use-package! anki-editor
  :after org
  :bind (:map org-mode-map
              ("C-c a" . anki-editor-push-notes)))

---

add-hook! - Hook Registration

Add hooks with inline function definitions.

Location: Any config file

Keyword	Description
:local	Make the hook local to current buffer

Syntax:

(add-hook! HOOK-SPEC
  (defun my-hook-function ()
    "Description."
    (do-something)))

Example:

(add-hook! 'org-agenda-finalize-hook
  (defun +org-exclude-agenda-buffers-from-workspace-h ()
    "Don't associate temporary agenda buffers with current workspace."
    (when (and org-agenda-new-buffers
               (bound-and-true-p persp-mode)
               (not org-agenda-sticky))
      (let (persp-autokill-buffer-on-remove)
        (persp-remove-buffer org-agenda-new-buffers
                             (get-current-persp)
                             nil)))))

---

setq-hook! - Set Variables in Hooks

Set variables specifically for particular mode hooks.

Syntax:

(setq-hook! MODE-SPEC VARS...)

Example:

(setq-hook! 'python-mode-hook
  python-indent-offset 4
  python-shell-interpreter "bpython")

---

map! - Keybinding

Define key bindings with a declarative syntax.

Location: Any config file

Keyword	State/Scope
:leader	Normal state leader key (SPC)
:n	Normal state
:v	Visual state
:i	Insert state
:e	Emacs state
:o	Operator-pending state
:ic	Insert+normal (after ESC)
:nv	Normal+visual combined
:after	Delay until package loads
:map	Specific keymap
:prefix	Key sequence prefix
:desc	Description for which-key display

Syntax:

(map! KEYCOMBO COMMAND
      KEYCOMBO COMMAND
      ...)

(map! :leader
      (:prefix ("KEY" . "DESC")
       KEYCOMBO COMMAND
       ...))

Example:

(map! :n "C-s" #'consult-line
      :n "M-s" (lambda () (interactive) (consult-line (thing-at-point 'symbol))))

(map! :leader
      (:prefix ("C" . "claude-code")
       :desc "Start Claude" "c" #'claude-code
       :desc "Kill Claude" "k" #'claude-code-kill))

---

after! - Run Code After Package

Run code after a package loads (shorthand for with-eval-after-load).

Syntax:

(after! PACKAGE
  BODY...)

Example:

(after! org
  (require 'org-re-reveal)
  (setq org-re-reveal-root "https://cdn.jsdelivr.net/npm/reveal.js"))

---

load! - Load Sub-config Files

Load additional configuration files from config.el.

Location: config.el

Syntax:

(load! "path/to/file")  ; Without .el extension

Example:

;; In config.el
(load! "security")
(load! "core")
(load! "org")
(load! "ai/gptel")

---

Summary Table

Macro	Purpose	Location
doom!	Declare enabled modules	init.el
package!	Declare packages to install	packages.el
use-package!	Configure packages	config.el or modular configs
add-hook!	Register hooks	Any config file
setq-hook!	Set vars for mode hooks	Any config file
map!	Define keybindings	Any config file
after!	Run code after package loads	Any config file
load!	Load sub-config files	config.el

---

See Also

• Doom Emacs Documentation
• Doom Modules Index
• Getting Started Guide