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](#doom---module-declaration)
- [`package!` - Package Declaration](#package---package-declaration)
- [`use-package!` / `use-package` - Package Configuration](#use-package--use-package---package-configuration)
- [`add-hook!` - Hook Registration](#add-hook---hook-registration)
- [`setq-hook!` - Set Variables in Hooks](#setq-hook---set-variables-in-hooks)
- [`map!` - Keybinding](#map---keybinding)
- [`after!` - Run Code After Package](#after---run-code-after-package)
- [`load!` - Load Sub-config Files](#load---load-sub-config-files)

---

## `doom!` - Module Declaration

Declares enabled modules and their flags in `init.el`.

**Location:** `init.el`

**Syntax:**
```elisp
(doom! :module
       (module +flag1 +flag2)
       :another-module)
```

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

**Example:**
```elisp
(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:**
```elisp
(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:**
```elisp
(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

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

### Bind Syntax with Maps

```elisp
(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:**
```elisp
(add-hook! HOOK-SPEC
  (defun my-hook-function ()
    "Description."
    (do-something)))
```

**Example:**
```elisp
(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:**
```elisp
(setq-hook! MODE-SPEC VARS...)
```

**Example:**
```elisp
(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:**
```elisp
(map! KEYCOMBO COMMAND
      KEYCOMBO COMMAND
      ...)

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

**Example:**
```elisp
(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:**
```elisp
(after! PACKAGE
  BODY...)
```

**Example:**
```elisp
(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:**
```elisp
(load! "path/to/file")  ; Without .el extension
```

**Example:**
```elisp
;; 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](https://docs.doomemacs.org)
- [Doom Modules Index](https://github.com/doomemacs/doomemacs/blob/master/docs/modules.org)
- [Getting Started Guide](https://github.com/doomemacs/doomemacs/blob/master/docs/getting_started.org)