To install this package, run in Emacs:
M-x package-install RET marginalia RET
#+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: <a href="http://elpa.gnu.org/packages/marginalia.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/marginalia.svg"/></a> #+html: <a href="http://elpa.gnu.org/devel/marginalia.html"><img alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/marginalia.svg"/></a> #+html: <a href="https://melpa.org/#/marginalia"><img alt="MELPA" src="https://melpa.org/packages/marginalia-badge.svg"/></a> #+html: <a href="https://stable.melpa.org/#/marginalia"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/marginalia-badge.svg"/></a> * Introduction #+html: <img src="https://upload.wikimedia.org/wikipedia/commons/4/4f/Marginalia_%285095211566%29.jpg" align="right" width="30%"> 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 cycle between more or less detailed annotators or even disable the annotator with command =marginalia-cycle=. #+html: <img src="https://github.com/minad/marginalia/blob/main/marginalia-mode.png?raw=true"> * Configuration It is recommended to use Marginalia together with either the [[https://github.com/raxod502/selectrum][Selectrum]], [[https://github.com/minad/vertico][Vertico]] 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)) #+end_src * Adding custom annotators or classifiers Minibuffer completion commands can specify the type of the candidates which are being completed, called the *completion category*. For example the =M-x= command (=execute-extended-command=) specifies the category =command=. However many commands do not specify a completion category, this includes many of the Emacs built-in completion commands. In order to repair existing commands, Marginalia provides heuristic classifiers, which try to determine the completion category based on the prompt string or based on other properties of the completion candidates. You can for example define that commands with a prompt containing "face", have the associated =face= completion category. #+begin_src emacs-lisp (add-to-list 'marginalia-prompt-categories '("face" . face)) #+end_src Another useful classifier uses the =marginalia-command-categories= variable, which allows do define the completion category per command name. This is particularily useful if for example the prompt classifier yields a false positive. The list of all available classifiers is specified by the variable =marginalia-classifiers=. The completion categories are also important for [[https://github.com/oantolin/embark][Embark]], which associates its minibuffer actions depending on the completion commands. Marginalia uses the annotators depending on the completion category of the current command as registered in =marginalia-annotator-registry=. It is possible to specify multiple annotators per completion category (for example with more or less information). You can cycle between the different annotators by invoking the =marginalia-cycle= command during the current completion. An annotation function is a function taken a completion candidate string as argument and returns the annotation string. For example a basic face annotator can be written as follows: #+begin_src emacs-lisp (defun my-face-annotator (cand) (when-let (sym (intern-soft cand)) (concat (propertize " " 'display '(space :align-to center)) (propertize "The quick brown fox jumps over the lazy dog" 'face sym)))) #+end_src There are a few helper functions available internally which can be used to write the annotation functions more conveniently, in particular =marginalia--fields=. After defining the annotator, it must be added to the annotator registry. #+begin_src emacs-lisp (add-to-list 'marginalia-annotator-registry '(face my-face-annotator marginalia-annotate-face builtin none)) #+end_src We also add the annotator provided by Marginalia (=marginalia-annotate-face=), the =builtin= annotator as defined by Emacs and the =none= annotator, which disables the annotations. You can cycle between all of those annotators using =marginalia-cycle= after invoking =M-x describe-face RET=. * Disabling annotators, builtin or lightweight annotators Marginalia activates rich annotators by default. Depending on your preference you may want to use the builtin annotators or even no annotators by default and only activate the annotators on demand by invoking ~marginalia-cycle~. In order to use the builtin annotators by default, you can use the following command. Replace =builtin= by =none= to disable annotators by default. #+begin_src emacs-lisp (defun marginalia-use-builtin () (interactive) (mapc (lambda (x) (setcdr x (cons 'builtin (remq 'builtin (cdr x))))) marginalia-annotator-registry)) #+end_src If a completion category supports two annotators, you can toggle between those using this command. #+begin_src emacs-lisp (defun marginalia-toggle () (interactive) (mapc (lambda (x) (setcdr x (append (reverse (remq 'none (remq 'builtin (cdr x)))) '(builtin none)))) marginalia-annotator-registry)) #+end_src After cycling the annotators you may want to automatically save the configuration. This can be achieved using an advice which calls ~customize-save-variable~. #+begin_src emacs-lisp (advice-add #'marginalia-cycle :after (lambda () (let ((inhibit-message t)) (customize-save-variable 'marginalia-annotator-registry marginalia-annotator-registry)))) #+end_src In order to disable an annotator permanently, the ~marginalia-annotator-registry~ can be modified. For example if you prefer to never see file annotations, you can delete all file annotators from the registry. #+begin_src emacs-lisp (setq marginalia-annotator-registry (assq-delete-all 'file marginalia-annotator-registry)) #+end_src * Contributions Since this package is part of [[http://elpa.gnu.org/packages/marginalia.html][GNU ELPA]] contributions require a copyright assignment to the FSF.