Quick start

The easiest way to install Embark is from GNU ELPA, just run ‘M-x package-install RET embark RET’. (It is also available on MELPA.) It is highly recommended to also install Marginalia (also available on GNU ELPA), so that Embark can offer you preconfigured actions in more contexts. For ‘use-package’ users, the following is a very reasonable starting configuration:

(use-package marginalia
  :ensure t
  :config
  (marginalia-mode))

(use-package embark
  :ensure t

  :bind
  (("C-." . embark-act)         ;; pick some comfortable binding
   ("C-;" . embark-dwim)        ;; good alternative: M-.
   ("C-h B" . embark-bindings)) ;; alternative for `describe-bindings'

  :init

  ;; Optionally replace the key help with a completing-read interface
  (setq prefix-help-command #'embark-prefix-help-command)

  ;; Show the Embark target at point via Eldoc. You may adjust the
  ;; Eldoc strategy, if you want to see the documentation from
  ;; multiple providers. Beware that using this can be a little
  ;; jarring since the message shown in the minibuffer can be more
  ;; than one line, causing the modeline to move up and down:

  ;; (add-hook 'eldoc-documentation-functions #'embark-eldoc-first-target)
  ;; (setq eldoc-documentation-strategy #'eldoc-documentation-compose-eagerly)

  ;; Add Embark to the mouse context menu. Also enable `context-menu-mode'.
  ;; (context-menu-mode 1)
  ;; (add-hook 'context-menu-functions #'embark-context-menu 100)

  :config

  ;; Hide the mode line of the Embark live/completions buffers
  (add-to-list 'display-buffer-alist
               '("\\`\\*Embark Collect \\(Live\\|Completions\\)\\*"
                 nil
                 (window-parameters (mode-line-format . none)))))

;; Consult users will also want the embark-consult package.
(use-package embark-consult
  :ensure t) ; only need to install it, embark loads it after consult if found

About the suggested key bindings for ‘embark-act’ and ‘embark-dwim’:

• Those key bindings are unlikely to work in the terminal, but terminal users are probably well aware of this and will know to select different bindings.
• The suggested ‘C-.’ binding is used by default in (at least some installations of) GNOME to input emojis, and Emacs doesn’t even get a chance to respond to the binding. You can select a different key binding for ‘embark-act’ or use ‘ibus-setup’ to change the shortcut for emoji insertion (Emacs 29 uses ‘C-x 8 e e’, in case you want to set the same one system-wide).
• The suggested alternative of ‘M-.’ for ‘embark-dwim’ is bound by default to ‘xref-find-definitions’. That is a very useful command but overwriting it with ‘embark-dwim’ is sensible since in Embark’s default configuration, ‘embark-dwim’ will also find the definition of the identifier at point. (Note that ‘xref-find-definitions’ with a prefix argument prompts you for an identifier, ‘embark-dwim’ does not cover this case).

Other Embark commands such as ‘embark-act-all’, ‘embark-become’, ‘embark-collect’, and ‘embark-export’ can be run through ‘embark-act’ as actions bound to ‘A’, ‘B’, ‘S’ (for "snapshot"), and ‘E’ respectively, and thus don’t really need a dedicated key binding, but feel free to bind them directly if you so wish. If you do choose to bind them directly, you’ll probably want to bind them in ‘minibuffer-local-map’, since they are most useful in the minibuffer (in fact, ‘embark-become’ only works in the minibuffer).

The command ‘embark-dwim’ executes the default action at point. Another good keybinding for ‘embark-dwim’ is ‘M-.’ since ‘embark-dwim’ acts like ‘xref-find-definitions’ on the symbol at point. ‘C-.’ can be seen as a right-click context menu at point and ‘M-.’ acts like left-click. The keybindings are mnemonic, both act at the point (‘.’).

Embark needs to know what your minibuffer completion system considers to be the list of candidates and which one is the current candidate. Embark works out of the box if you use Emacs’s default tab completion, the built-in ‘icomplete-mode’ or ‘fido-mode’, or the third-party packages Vertico or Ivy.

If you are a Helm or Ivy user you are unlikely to want Embark since those packages include comprehensive functionality for acting on minibuffer completion candidates. (Embark does come with Ivy integration despite this.)