minad / Marginalia

#+title: marginalia.el - Marginalia in the minibuffer #+author: Omar Antolín Camarena, Daniel Mendler #+language: en #+export_file_name: marginalia.texi #+texinfo_dir_category: Emacs #+texinfo_dir_title: Marginalia: (marginalia). #+texinfo_dir_desc: Marginalia in the minibuffer

#+html:

#+html: #+html:

• Introduction

This package provides =marginalia-mode= which adds marginalia to the minibuffer completions. [[https://en.wikipedia.org/wiki/Marginalia][Marginalia]] are marks or annotations placed at the margin of the page of a book or in this case helpful colorful annotations placed at the margin of the minibuffer for your completion candidates. Marginalia can only add annotations to be displayed with the completion candidates. It cannot modify the appearance of the candidates themselves, which are shown as supplied by the original commands.

The annotations are added based on the completion category. For example =find-file= reports the =file= category and =M-x= reports the =command= category. You can choose between more or less detailed annotators, by setting the variable =marginalia-annotators= or by invoking the command =marginalia-cycle=.

Since many commands do not report a completion category themselves, Marginalia provides a classifier system, which tries to guess the correct category based for example on the prompt (see the variable =marginalia-prompt-categories=). Usually these heuristic classifiers work well, but if they do not there is always the possibility to overwrite categories by command name. This way you can associate a fixed category with the completion initiated by the command (see the variable =marginalia-command-categories=). The list of available classifiers is specified by the variable =marginalia-classifiers=.

#+html:

• Configuration

It is recommended to use Marginalia together with either the [[https://github.com/raxod502/selectrum][Selectrum]] or the [[https://github.com/oantolin/icomplete-vertical][Icomplete-vertical]] completion system. Furthermore Marginalia can be combined with [[https://github.com/oantolin/embark][Embark]] for action support and [[https://github.com/minad/consult][Consult]], which provides many useful commands.

#+begin_src emacs-lisp ;; Enable richer annotations using the Marginalia package (use-package marginalia ;; Either bind marginalia-cycle globally or only in the minibuffer :bind (("M-A" . marginalia-cycle) :map minibuffer-local-map ("M-A" . marginalia-cycle))

;; The :init configuration is always executed (Not lazy!) :init

;; Must be in the :init section of use-package such that the mode gets ;; enabled right away. Note that this forces loading the package. (marginalia-mode)

;; When using Selectrum, ensure that Selectrum is refreshed when cycling annotations. (advice-add #'marginalia-cycle :after (lambda () (when (bound-and-true-p selectrum-mode) (selectrum-exhibit 'keep-selected))))

;; Prefer richer, more heavy, annotations over the lighter default variant. ;; E.g. M-x will show the documentation string additional to the keybinding. ;; By default only the keybinding is shown as annotation. ;; Note that there is the command `marginalia-cycle' to ;; switch between the annotators. ;; (setq marginalia-annotators '(marginalia-annotators-heavy marginalia-annotators-light nil)) ) #+end_src