README.org (11005B)
1 #+title: marginalia.el - Marginalia in the minibuffer 2 #+author: Omar Antolín Camarena, Daniel Mendler 3 #+language: en 4 #+export_file_name: marginalia.texi 5 #+texinfo_dir_category: Emacs misc features 6 #+texinfo_dir_title: Marginalia: (marginalia). 7 #+texinfo_dir_desc: Marginalia in the minibuffer 8 9 #+html: <a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true"/></a> 10 #+html: <a href="https://elpa.gnu.org/packages/marginalia.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/marginalia.svg"/></a> 11 #+html: <a href="https://elpa.gnu.org/devel/marginalia.html"><img alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/marginalia.svg"/></a> 12 #+html: <a href="https://melpa.org/#/marginalia"><img alt="MELPA" src="https://melpa.org/packages/marginalia-badge.svg"/></a> 13 #+html: <a href="https://stable.melpa.org/#/marginalia"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/marginalia-badge.svg"/></a> 14 15 #+html: <img src="https://upload.wikimedia.org/wikipedia/commons/4/4f/Marginalia_%285095211566%29.jpg" align="right" width="30%"> 16 17 This package provides =marginalia-mode= which adds marginalia to the minibuffer 18 completions. [[https://en.wikipedia.org/wiki/Marginalia][Marginalia]] are marks or annotations placed at the margin of the 19 page of a book or in this case helpful colorful annotations placed at the margin 20 of the minibuffer for your completion candidates. Marginalia can only add 21 annotations to the completion candidates. It cannot modify the appearance of the 22 candidates themselves, which are shown unaltered as supplied by the original 23 command. 24 25 The annotations are added based on the completion category. For example 26 =find-file= reports the =file= category and =M-x= reports the =command= category. You 27 can cycle between more or less detailed annotators or even disable the annotator 28 with command =marginalia-cycle=. 29 30 #+html: <img src="https://github.com/minad/marginalia/blob/screenshots/marginalia-mode.png?raw=true"> 31 32 #+toc: headlines 8 33 34 * Configuration 35 36 It is recommended to use Marginalia together with either the [[https://github.com/minad/vertico][Vertico]], [[https://github.com/protesilaos/mct][Mct]], 37 [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html][Icomplete]] or the default completion UI. Furthermore Marginalia can be combined 38 with [[https://github.com/oantolin/embark][Embark]] for action support and [[https://github.com/minad/consult][Consult]], which provides many useful commands. 39 40 #+begin_src emacs-lisp 41 ;; Enable rich annotations using the Marginalia package 42 (use-package marginalia 43 ;; Bind `marginalia-cycle' locally in the minibuffer. To make the binding 44 ;; available in the *Completions* buffer, add it to the 45 ;; `completion-list-mode-map'. 46 :bind (:map minibuffer-local-map 47 ("M-A" . marginalia-cycle)) 48 49 ;; The :init section is always executed. 50 :init 51 52 ;; Marginalia must be activated in the :init section of use-package such that 53 ;; the mode gets enabled right away. Note that this forces loading the 54 ;; package. 55 (marginalia-mode)) 56 #+end_src 57 58 * Information shown by the annotators 59 60 In general, to learn more about what different annotations mean, a good starting 61 point is to look at ~marginalia-annotator-registry~, and follow up to the 62 annotation function of the category you are interested in. 63 64 For example the annotations for Elisp symbols include their symbol class - =v= for 65 variable, =f= for function, =c= for command, etc. For more information on what the 66 different classifications mean, see the docstring of ~marginalia--symbol-class~. 67 68 * Adding custom annotators or classifiers 69 70 *IMPORTANT NOTICE FOR PACKAGE AUTHORS*: The intention of the Marginalia package is 71 to give the user means to overwrite completion categories and to add custom 72 annotators for existing commands in their user configuration. *Marginalia is a 73 user facing package and is not intended to be used as a library*. Therefore 74 Marginalia does not expose library functions as part of its public API. If you 75 add your own completion commands to your package we recommend to specify an 76 =annotation-function= or an =affixation-function=, avoiding the Marginalia 77 dependency this way. The =annotation-function= and =affixation-function= are 78 documented in the [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html][Elisp manual]]. If you use =consult--read=, you can specify an 79 =:annotate= keyword argument. There is an exception to our recommendation: If you 80 want to implement annotations for an existing package =hypothetic.el=, which does 81 not have annotations and where annotations cannot be added, then the creation of 82 a =marginalia-hypothetic.el= package is a good idea, since Marginalia provides the 83 facilities to enhance existing commands from the outside. If you have questions 84 feel free to ask on the Marginalia issue tracker. 85 86 Commands that support minibuffer completion use a completion table of all the 87 available candidates. Candidates are associated with a *category* such as =command=, 88 =file=, =face=, or =variable= depending on what the candidates are. Based on the 89 category of the candidates, Marginalia selects an *annotator* to generate 90 annotations for display for each candidate. 91 92 Unfortunately, not all commands (including Emacs' builtin ones) specify the 93 category of their candidates. To compensate for this shortcoming, Marginalia 94 hooks into the Emacs completion framework and runs the *classifiers* listed in the 95 variable =marginalia-classifiers=, which use the command's prompt or other 96 properties of the candidates to specify the completion category. 97 98 For example, the =marginalia-classify-by-prompt= classifier checks the minibuffer 99 prompt against regexps listed in the =marginalia-prompt-categories= alist to 100 determine a category. The following is already included but would be a way to 101 assign the category =face= to all candidates from commands with prompts that 102 include the word "face". 103 104 #+begin_src emacs-lisp 105 (add-to-list 'marginalia-prompt-categories '("\\<face\\>" . face)) 106 #+end_src 107 108 The =marginalia-classify-by-command-name= classifier uses the alist 109 =marginalia-command-categories= to specify the completion category based on the 110 command name. This is particularly useful if the prompt classifier yields a 111 false positive. 112 113 Completion categories are also important for [[https://github.com/oantolin/embark][Embark]], which associates actions 114 based on the completion category and benefits from Marginalia's classifiers. 115 116 Once the category of the candidates is known, Marginalia looks in the 117 =marginalia-annotator-registry= to find the associated annotator to use. An 118 annotator is a function that takes a completion candidate string as an argument 119 and returns an annotation string to be displayed after the candidate in the 120 minibuffer. More than one annotator can be assigned to each each category, 121 displaying more, less or different information. Use the =marginalia-cycle= command 122 to cycle between the annotations of different annotators defined for the current 123 category. 124 125 Here's an example of a basic face annotator: 126 127 #+begin_src emacs-lisp 128 (defun my-face-annotator (cand) 129 (when-let (sym (intern-soft cand)) 130 (concat (propertize " " 'display '(space :align-to center)) 131 (propertize "The quick brown fox jumps over the lazy dog" 'face sym)))) 132 #+end_src 133 134 Look at Marginalia's various annotators for examples of formatting annotations. 135 In particular, the helper function =marginalia--fields= can be used to format 136 information into columns. 137 138 After defining a new annotator, associate it with a category in the annotator 139 registry as follows: 140 141 #+begin_src emacs-lisp 142 (add-to-list 'marginalia-annotator-registry 143 '(face my-face-annotator marginalia-annotate-face builtin none)) 144 #+end_src 145 146 This makes the =my-face-annotator= the first of four annotators for the face 147 category. The others are the annotator provided by Marginalia 148 (=marginalia-annotate-face=), the =builtin= annotator as defined by Emacs and the 149 =none= annotator, which disables the annotations. With this setting, after 150 invoking =M-x describe-face RET= you can cycle between all of these annotators 151 using =marginalia-cycle=. 152 153 * Disabling annotators, builtin or lightweight annotators 154 155 Marginalia activates rich annotators by default. Depending on your preference 156 you may want to use the builtin annotators or even no annotators by default and 157 only activate the annotators on demand by invoking ~marginalia-cycle~. 158 159 In order to use the builtin annotators by default, you can use the following 160 command. Replace =builtin= by =none= to disable annotators by default. 161 162 #+begin_src emacs-lisp 163 (defun marginalia-use-builtin () 164 (interactive) 165 (mapc 166 (lambda (x) 167 (setcdr x (cons 'builtin (remq 'builtin (cdr x))))) 168 marginalia-annotator-registry)) 169 #+end_src 170 171 If a completion category supports two annotators, you can toggle between 172 those using this command. 173 174 #+begin_src emacs-lisp 175 (defun marginalia-toggle () 176 (interactive) 177 (mapc 178 (lambda (x) 179 (setcdr x (append (reverse (remq 'none 180 (remq 'builtin (cdr x)))) 181 '(builtin none)))) 182 marginalia-annotator-registry)) 183 #+end_src 184 185 After cycling the annotators you may want to automatically save the 186 configuration. This can be achieved using an advice which calls 187 ~customize-save-variable~. 188 189 #+begin_src emacs-lisp 190 (advice-add #'marginalia-cycle :after 191 (lambda () 192 (let ((inhibit-message t)) 193 (customize-save-variable 'marginalia-annotator-registry 194 marginalia-annotator-registry)))) 195 #+end_src 196 197 In order to disable an annotator permanently, the ~marginalia-annotator-registry~ 198 can be modified. For example if you prefer to never see file annotations, you 199 can delete all file annotators from the registry. 200 201 #+begin_src emacs-lisp 202 (setq marginalia-annotator-registry 203 (assq-delete-all 'file marginalia-annotator-registry)) 204 #+end_src 205 206 * Icons in the minibuffer 207 208 Icons in the minibuffer completion UI are a commonly requested feature. 209 Marginalia focuses on text annotations only. The following packages are 210 compatible with Marginalia and use special fonts to add icons in front of 211 completion candidates. There also exist related packages to enhance Dired, 212 Ibuffer and other modes with icons consistently. 213 214 - [[https://github.com/iyefrat/all-the-icons-completion][all-the-icons-completion]]: Relies on the =all-the-icons.el= package which 215 configures multiple icon fonts. 216 - [[https://github.com/rainstormstudio/nerd-icons-completion][nerd-icons-completion]]: Relies on patched fonts including icons. This package 217 works even in the terminal where only a single font can be used. 218 219 * Contributions 220 221 Since this package is part of [[https://elpa.gnu.org/packages/marginalia.html][GNU ELPA]] contributions require a copyright 222 assignment to the FSF.