{"id":13443242,"url":"https://github.com/minad/marginalia","last_synced_at":"2025-04-12T23:42:46.657Z","repository":{"id":39519366,"uuid":"318215450","full_name":"minad/marginalia","owner":"minad","description":":scroll: marginalia.el - Marginalia in the minibuffer","archived":false,"fork":false,"pushed_at":"2025-03-17T16:32:31.000Z","size":823,"stargazers_count":821,"open_issues_count":0,"forks_count":28,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-04-12T23:42:41.972Z","etag":null,"topics":["annotations","emacs","minibuffer"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/minad.png","metadata":{"files":{"readme":"README.org","changelog":"CHANGELOG.org","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["minad","oantolin"]}},"created_at":"2020-12-03T14:14:16.000Z","updated_at":"2025-04-12T05:09:03.000Z","dependencies_parsed_at":"2023-02-09T23:30:33.215Z","dependency_job_id":"31d80217-5c07-461a-94d3-8d85295ee6e4","html_url":"https://github.com/minad/marginalia","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minad%2Fmarginalia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minad%2Fmarginalia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minad%2Fmarginalia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minad%2Fmarginalia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/minad","download_url":"https://codeload.github.com/minad/marginalia/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647256,"owners_count":21139081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotations","emacs","minibuffer"],"created_at":"2024-07-31T03:01:58.001Z","updated_at":"2025-04-12T23:42:46.637Z","avatar_url":"https://github.com/minad.png","language":"Emacs Lisp","readme":"#+title: marginalia.el - Marginalia in the minibuffer\n#+author: Omar Antolín Camarena, Daniel Mendler\n#+language: en\n#+export_file_name: marginalia.texi\n#+texinfo_dir_category: Emacs misc features\n#+texinfo_dir_title: Marginalia: (marginalia).\n#+texinfo_dir_desc: Marginalia in the minibuffer\n\n#+html: \u003ca href=\"https://www.gnu.org/software/emacs/\"\u003e\u003cimg alt=\"GNU Emacs\" src=\"https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true\"/\u003e\u003c/a\u003e\n#+html: \u003ca href=\"https://elpa.gnu.org/packages/marginalia.html\"\u003e\u003cimg alt=\"GNU ELPA\" src=\"https://elpa.gnu.org/packages/marginalia.svg\"/\u003e\u003c/a\u003e\n#+html: \u003ca href=\"https://elpa.gnu.org/devel/marginalia.html\"\u003e\u003cimg alt=\"GNU-devel ELPA\" src=\"https://elpa.gnu.org/devel/marginalia.svg\"/\u003e\u003c/a\u003e\n#+html: \u003ca href=\"https://melpa.org/#/marginalia\"\u003e\u003cimg alt=\"MELPA\" src=\"https://melpa.org/packages/marginalia-badge.svg\"/\u003e\u003c/a\u003e\n#+html: \u003ca href=\"https://stable.melpa.org/#/marginalia\"\u003e\u003cimg alt=\"MELPA Stable\" src=\"https://stable.melpa.org/packages/marginalia-badge.svg\"/\u003e\u003c/a\u003e\n\n#+html: \u003cimg src=\"https://upload.wikimedia.org/wikipedia/commons/4/4f/Marginalia_%285095211566%29.jpg\" align=\"right\" width=\"30%\"\u003e\n\nThis package provides =marginalia-mode= which adds marginalia to the minibuffer\ncompletions. [[https://en.wikipedia.org/wiki/Marginalia][Marginalia]] are marks or annotations placed at the margin of the\npage of a book or in this case helpful colorful annotations placed at the margin\nof the minibuffer for your completion candidates. Marginalia can only add\nannotations to the completion candidates. It cannot modify the appearance of the\ncandidates themselves, which are shown unaltered as supplied by the original\ncommand.\n\nThe annotations are added based on the completion category. For example\n=find-file= reports the =file= category and =M-x= reports the =command= category. You\ncan cycle between more or less detailed annotators or even disable the annotator\nwith command =marginalia-cycle=.\n\n#+html: \u003cimg src=\"https://github.com/minad/marginalia/blob/screenshots/marginalia-mode.png?raw=true\"\u003e\n\n#+toc: headlines 8\n\n* Configuration\n\nIt is recommended to use Marginalia together with either the [[https://github.com/minad/vertico][Vertico]], [[https://github.com/protesilaos/mct][Mct]],\n[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html][Icomplete]] or the default completion UI. Furthermore Marginalia can be combined\nwith [[https://github.com/oantolin/embark][Embark]] for action support and [[https://github.com/minad/consult][Consult]], which provides many useful commands.\n\n#+begin_src emacs-lisp\n;; Enable rich annotations using the Marginalia package\n(use-package marginalia\n  ;; Bind `marginalia-cycle' locally in the minibuffer.  To make the binding\n  ;; available in the *Completions* buffer, add it to the\n  ;; `completion-list-mode-map'.\n  :bind (:map minibuffer-local-map\n         (\"M-A\" . marginalia-cycle))\n\n  ;; The :init section is always executed.\n  :init\n\n  ;; Marginalia must be activated in the :init section of use-package such that\n  ;; the mode gets enabled right away. Note that this forces loading the\n  ;; package.\n  (marginalia-mode))\n#+end_src\n\n* Information shown by the annotators\n\nIn general, to learn more about what different annotations mean, a good starting\npoint is to look at ~marginalia-annotator-registry~, and follow up to the\nannotation function of the category you are interested in.\n\nFor example the annotations for Elisp symbols include their symbol class - =v= for\nvariable, =f= for function, =c= for command, etc. For more information on what the\ndifferent classifications mean, see the docstring of ~marginalia--symbol-class~.\n\n* Adding custom annotators or classifiers\n\n*IMPORTANT NOTICE FOR PACKAGE AUTHORS*: The intention of the Marginalia package is\nto give the user means to overwrite completion categories and to add custom\nannotators for existing commands in their user configuration. *Marginalia is a\nuser facing package and is not intended to be used as a library*. Therefore\nMarginalia does not expose library functions as part of its public API. If you\nadd your own completion commands to your package we recommend to specify an\n=annotation-function= or an =affixation-function=, avoiding the Marginalia\ndependency this way. The =annotation-function= and =affixation-function= are\ndocumented 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\n=:annotate= keyword argument.\n\nThere is an exception to our recommendation: If you want to implement\nannotations for an existing package =hypothetic.el=, which does not have\nannotations and where annotations cannot be added, then the creation of a\n=marginalia-hypothetic.el= package is a good idea, since Marginalia provides the\nfacilities to enhance existing commands from the outside.\n\nCommands that support minibuffer completion use a completion table of all the\navailable candidates. Candidates are associated with a *category* such as =command=,\n=file=, =face=, or =variable= depending on what the candidates are. Based on the\ncategory of the candidates, Marginalia selects an *annotator* to generate\nannotations for display for each candidate.\n\nUnfortunately, not all commands (including Emacs' builtin ones) specify the\ncategory of their candidates. To compensate for this shortcoming, Marginalia\nhooks into the Emacs completion framework and runs the *classifiers* listed in the\nvariable =marginalia-classifiers=, which use the command's prompt or other\nproperties of the candidates to specify the completion category.\n\nFor example, the =marginalia-classify-by-prompt= classifier checks the minibuffer\nprompt against regexps listed in the =marginalia-prompt-categories= alist to\ndetermine a category. The following is already included but would be a way to\nassign the category =face= to all candidates from commands with prompts that\ninclude the word \"face\".\n\n#+begin_src emacs-lisp\n  (add-to-list 'marginalia-prompt-categories '(\"\\\\\u003cface\\\\\u003e\" . face))\n#+end_src\n\nThe =marginalia-classify-by-command-name= classifier uses the alist\n=marginalia-command-categories= to specify the completion category based on the\ncommand name. This is particularly useful if the prompt classifier yields a\nfalse positive.\n\nCompletion categories are also important for [[https://github.com/oantolin/embark][Embark]], which associates actions\nbased on the completion category and benefits from Marginalia's classifiers.\n\nOnce the category of the candidates is known, Marginalia looks in the\n=marginalia-annotator-registry= to find the associated annotator to use. An\nannotator is a function that takes a completion candidate string as an argument\nand returns an annotation string to be displayed after the candidate in the\nminibuffer. More than one annotator can be assigned to each each category,\ndisplaying more, less or different information. Use the =marginalia-cycle= command\nto cycle between the annotations of different annotators defined for the current\ncategory.\n\nHere's an example of a basic face annotator:\n\n#+begin_src emacs-lisp\n  (defun my-face-annotator (cand)\n    (when-let (sym (intern-soft cand))\n      (concat (propertize \" \" 'display '(space :align-to center))\n              (propertize \"The quick brown fox jumps over the lazy dog\" 'face sym))))\n#+end_src\n\nAfter defining a new annotator, associate it with a category in the annotator\nregistry as follows:\n\n#+begin_src emacs-lisp\n  (add-to-list 'marginalia-annotator-registry\n               '(face my-face-annotator marginalia-annotate-face builtin none))\n#+end_src\n\nThis makes the =my-face-annotator= the first of four annotators for the face\ncategory. The others are the annotator provided by Marginalia\n(=marginalia-annotate-face=), the =builtin= annotator as defined by Emacs and the\n=none= annotator, which disables the annotations. With this setting, after\ninvoking =M-x describe-face RET= you can cycle between all of these annotators\nusing =marginalia-cycle=.\n\n* Disabling annotators, builtin or lightweight annotators\n\nMarginalia activates rich annotators by default. Depending on your preference\nyou may want to use the builtin annotators or even no annotators by default and\nonly activate the annotators on demand by invoking ~marginalia-cycle~.\n\nIn order to disable an annotator permanently, the ~marginalia-annotator-registry~\ncan be modified. For example if you prefer to never see file annotations, you\ncan delete all file annotators from the registry.\n\n#+begin_src emacs-lisp\n  (setq marginalia-annotator-registry\n        (assq-delete-all 'file marginalia-annotator-registry))\n#+end_src\n\nTo use the builtin annotators by default, you can run the following code.\nReplace =builtin= by =none= to disable annotators by default.\n\n#+begin_src emacs-lisp\n(mapc (lambda (x)\n        (setcdr x (cons 'builtin (remq 'builtin (cdr x)))))\n      marginalia-annotator-registry)\n#+end_src\n\nAs an alternative to ~marginalia-cycle~, if a completion category supports two\nannotators, you can toggle between them using the following command.\n\n#+begin_src emacs-lisp\n  (defun marginalia-toggle ()\n    (interactive)\n    (mapc\n     (lambda (x)\n       (setcdr x (append (reverse (remq 'none\n                                        (remq 'builtin (cdr x))))\n                         '(builtin none))))\n     marginalia-annotator-registry))\n#+end_src\n\nAfter cycling the annotators you may want to automatically save the\nconfiguration. This can be achieved using an advice which calls\n~customize-save-variable~.\n\n#+begin_src emacs-lisp\n  (advice-add #'marginalia-cycle :after\n              (lambda ()\n                (let ((inhibit-message t))\n                  (customize-save-variable 'marginalia-annotator-registry\n                                           marginalia-annotator-registry))))\n#+end_src\n\n* Icons in the minibuffer\n\nMarginalia focuses on text annotations. The [[https://github.com/rainstormstudio/nerd-icons-completion][nerd-icons-completion]] package is\ncompatible with Marginalia and uses the special NerdFonts to add icons in front\nof minibuffer completion candidates. There exist related packages to enhance\nDired, Ibuffer, Corfu and other modes with icons consistently.\n\n* Contributions\n\nSince this package is part of [[https://elpa.gnu.org/packages/marginalia.html][GNU ELPA]] contributions require a copyright\nassignment to the FSF.\n","funding_links":["https://github.com/sponsors/minad","https://github.com/sponsors/oantolin"],"categories":["Emacs Lisp"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminad%2Fmarginalia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fminad%2Fmarginalia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminad%2Fmarginalia/lists"}