salutis/marginalia

:scroll: marginalia.el - Marginalia in the minibuffer

marginalia.el - Marginalia in the minibuffer

Introduction

This package provides marginalia-mode which adds marginalia to the minibuffer completions. 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 with the command marginalia-cycle.

Configuration

It is recommended to use Marginalia together with either the Selectrum, Vertico or the Icomplete-vertical completion system. Furthermore Marginalia can be combined with Embark for action support and Consult, which provides many useful commands.

;; 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))

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.

(add-to-list 'marginalia-prompt-categories '("face" . face))

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 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:

(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))))

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.

(add-to-list 'marginalia-annotator-registry
             '(face my-face-annotator marginalia-annotate-face builtin none))

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.

Using 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.

(defun marginalia-use-builtin ()
  (interactive)
  (mapc
   (lambda (x)
     (setcdr x (cons 'builtin (remq 'builtin (cdr x)))))
   marginalia-annotator-registry))

If a completion category supports two annotators, you can toggle between those using this command.

(defun marginalia-toggle ()
  (interactive)
  (mapc
   (lambda (x)
     (setcdr x (append (reverse (remq 'none
                                      (remq 'builtin (cdr x))))
                       '(builtin none))))
   marginalia-annotator-registry))

After cycling the annotators you may want to automatically save the configuration. This can be achieved using an advice which calls customize-save-variable.

(advice-add #'marginalia-cycle :after
            (lambda ()
              (let ((inhibit-message t))
                (customize-save-variable 'marginalia-annotator-registry
                                         marginalia-annotator-registry))))

Contributions

Since this package is part of GNU ELPA contributions require a copyright assignment to the FSF.