docs: add Doom Emacs macros and keywords reference
This commit is contained in:
@@ -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)
|
||||||
Reference in New Issue
Block a user