From a14cf7865e40ca43bcff41d6fd54d23d54455571 Mon Sep 17 00:00:00 2001 From: Wong Ding Feng Date: Sat, 4 Apr 2026 14:34:29 +0800 Subject: [PATCH] docs: add Doom Emacs macros and keywords reference --- docs/doom-macros-reference.md | 283 ++++++++++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 docs/doom-macros-reference.md diff --git a/docs/doom-macros-reference.md b/docs/doom-macros-reference.md new file mode 100644 index 0000000..4244fdf --- /dev/null +++ b/docs/doom-macros-reference.md @@ -0,0 +1,283 @@ +# 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)