Kristoffer Balintona — #Guide

Surprisingly, Emacs on Android is pretty good

Thu, 29 May 2025 19:38:00 GMT

The good and bad: what to expect on Android
Installation
- Option 1
- Option 2 (recommended)
Configuring an Android-specific Emacs
Conclusion
- Bonus: My wish list

Recently I got around to making steps toward a better mobile-PC workflow. Until now, I’ve pretty much exclusively been using the community-developed orgzly-revived app on Android. My intention was to use orgzly-revived for simple todo management and another app for more note-taking purposes—but I could never find another app I was happy with on Android. But I happened to remember reading good things about the native Emacs app on Android a few months ago. So I tried it out… and was immediately sold!

The good and bad: what to expect on Android §

First, let’s make sure our expectations are tempered: Emacs on Android won’t be as pleasant as the full desktop experience.^[1] Of course. A phone’s screen is tiny, and unless you have a physical keyboard connected, you’ll have to manage with a virtual one (see Use a Special virtual keyboard). On top of that:

Tooling: To have non-Emacs programs available, you have to install Emacs in a particular way with Termux to expose Termux’s binaries to Emacs. (See the recommended way to install Emacs.) The initial set up is longer, but it’s worth it.
File paths: Android “sandboxes” each app. You can think of each app having their own “section” of the file system that they can read or write to (unless they are given explicit access to that outside directory; see info "(emacs) Android Document Providers"). As such, one finds themselves fiddling with the obnoxiously long Android file paths if they want to, for instance, access their notes directory that is outside the Emacs app sandbox.^[2] This is a minor inconvenience though.
Writing to the file system: Relatively speaking, writing to the file system can be long sometimes. Not too long, but long nonetheless, As far as I’ve experienced, this has only been the case when saving files that are outside the Emacs sandbox.

So, really, the situation is pretty good!

And finally: YMMV on other Android devices. My current phone is the OnePlus 7 Pro running Android version 12.

Installation §

Option 1 §

The first option is as easy as it can get, but you won’t have a way to access other CLI tools:

Download the F-droid app store. For the layperson who doesn’t know what it is: it’s basically an alternative to the Play Store. Some apps that can’t be on the Play Store (fact check, maybe link tk) are there.
Download the Emacs app.
Open Emacs! The version of Emacs as I write this that is available is Emacs 30.1.

Using Emacs this way is totally possible if all you need is elisp. But if you need other tools, like git, I recommend the second way to install Emacs.

Option 2 (recommended) §

This option makes other CLI tools accessible to the Emacs Android application container. It is a little bit more of a hassle.

The method is outlined in this SourceForge repository. In essence, inside the termux/ directory of this SourceForge repository are modified Emacs .apk files. These .apk files allow the Emacs app container to access the Termux (explain what Termux is tk) app container, meaning the CLI tools installed with Termux will become accessible to Emacs. But the installation is specific; read the instructions detailed inside that repository. I will outline them briefly below, but be careful if you are reading this in the future, for the instructions could have changed relevantly.

In short,

Delete any existing Emacs or Termux apps.
Ensure you have enabled the setting that allows you to install third-party apps (i.e., non-Play Store apps) on your phone.
Install Termux. Don’t open Termux yet.
Select the .apk file appropriate to your phone. There are various .apk files for different versions of Emacs and devices.
Install Emacs through this .apk. (If your phone refuses to install the .apk, you might have selected the wrong type of .apk file for your device. So try different .apk files for the same Emacs version.)
In Termux, run pkg update && pkg upgrade. Say “yes” to each of the prompts.
Open Emacs.

Create a ~/.emacs.d/early-init.el and place the following inside of it:

(setenv "PATH" (format "%s:%s" "/data/data/com.termux/files/usr/bin"
                       (getenv "PATH")))
(push "/data/data/com.termux/files/usr/bin" exec-path)

And you’re done! Programs installed through Termux will be made accessible to Emacs.

Configuring an Android-specific Emacs §

Necessary reading: the manual §

Chances are that you don’t know that the Emacs manual has its own section for the Android system: (info "(emacs) Android"). Before anything, I highly recommend you peruse this section, returning to and reading more deeply specific parts as you see fit. In particular, I found the following Info nodes essential:

(info "(emacs) Android File System") (This one is particularly important if you wan to understand what the ~/ path means for Emacs.)
(info "(emacs) Android Document Providers")
(info "(emacs) Android Fonts")
(info "(emacs) Android Windowing")

A lot of the information here is found directly inside these Info pages.

Additionally, I also think reading about Emacs’ facilities for touchscreens and virtual keyboards (bet you didn’t know this was in the manual either!) is essential: (info "(emacs) Other Input").

Moments like these are truly a testament to Emacs’ dedication to an accessible editor.

How to configure your `init.el` on a mobile device? §

Later I’ll explain how you make typing code on a touchscreen device easier by installing a handy virtual keyboard. But I highly recommend that until you’ve settled on a configuration you’re willing to type out that you heavily utilize the customize interface. This means accessing the Customize interfaces via the tool-bar^[3] buttons then using your touchscreen to tap the buttons available in customize-mode buffers. (Then, if you prefer, after setting many options with Customize, you can refactor the options Customize put in your init.el into e.g. use-package forms.)

If you haven’t used Customize much before, you can check out the available Customize commands via C-h a (apropos-command), search for “customize.” The most useful commands are:

customize-group,
customize-option,
customize-face,

First step: A Better UI for touchscreens §

The very first thing I did when I opened Emacs was enable these minor modes:

modifier-bar-mode
tool-bar-mode

and set tool-bar-position to ‘bottom, placing it closer to where my fingers and the virtual keyboard are.

Desktop users might have disabled these years ago in favor of keyboard-centric workflow, but they are awesome for touchscreens in my opinion.

Android-specific Commands and Options §

There are a few built-in Android commands and options you should be aware of. (Pro tip: one can M-x Info-index or press i in the Emacs Info manual, itself accessible via C-h r, or M-x info-emacs-manual, then search for the string “android” to find all the specific mentions off “Android.”)

Commands:
- android-request-directory-access to request access to file paths of other apps^[4]
- and its inverse, android-relinquish-directory-access.
Options:
- android-pass-multimedia-buttons-to-system,
- android-intercept-control-space,
- touch-screen-display-keyboard,
- (and more not useful to me).

Also, don’t forget to let Emacs display over other apps. This is a device setting, not an Emacs one.

Use a Special virtual keyboard §

Unless you have a physical keyboard connected to your mobile device, typing will be a pain. For that, we install a virtual keyword that gives us easier access to modifier keys, function keys, arrow keys, and symbols. As far as I know, there are currently two main options:

Hacker’s Keyboard, available in F-Droid.
Unexpected Keyboard, available in the Play Store.

Having briefly tried both, I personally prefer the latter. Though the former works just fine if you like it.

Fonts §

You might want a set of fonts not already installed on your Android system. If that’s the case, you should read the (info "(emacs) Android Fonts") manual page.

That page explains that if you want to install fonts for your user (in the Emacs app container), you should place them in ~/fonts/.^[5] Getting those fonts was somewhat cumbersome for me: I had to manually download them, unzip them with Termux, place them inside a directory Emacs had access to (see Android-specific Commands and Options), then copy them to ~/fonts/.

Note: in my experience, fonts are not recursively checked inside this directory. That is, you should place your e.g. .ttf files inside that folder, not any subdirectories.

Tip: You can remap the volume buttons §

Volume buttons are un-mapped by default (see android-pass-multimedia-buttons-to-system). That’s find with me, but if you feel inclined, you can rebind them to something else after setting android-pass-multimedia-buttons-to-system appropriately. Some possibilities would be for navigation between headings, tk list more.

Conclusion §

In conclusion,

Make heavy use of the Customize interface. (At least initially—after you’re comfy in Emacs, you can refactor it into a form more familiar to a desktop init.el.)
Enable minor modes and options specific to touchscreen-driven usage.
Install a virtual keyboard to get access to modifiers, function keys, and more.

Right now I’ve achieved a set up I’m happy with. I migrated the portions of my configuration relevant to org, org-capture, and org-node, but in the future if I need more from Emacs-on-mobile, I’ll look to expand my config as necessary. (This includes version-controlling my init.el.)

And finally: YMMV on other Android devices. My current phone is the OnePlus 7 Pro running Android version 12.

Bonus: My wish list §

Touchscreen gestures: There is the built-in strokes.el, but strokes.el, as far as I can tell, does not work for touchscreens. Additionally, significant changes would be required to its code base to make it compatible for touchscreens. So, for now, we have to settle with virtual keyboards…
Automatic keyboard/IME switching: Ideally, I’d have my special virtual keyboard be automatically selected using Emacs and deselected when not using Emacs. Right now, I have to manually switch to it. As far as I know, there is no easy way to accomplish this.
Larger tool bar and menu bar: The tool bar and menu bar are useful, but they’re also small. I wish they were larger and easier to tap.

Some Notes Setting Up Syncthing in NixOS

Mon, 05 May 2025 03:19:00 GMT

The configuration
Devices
Folders
Closing remarks
Other resources
Changelog

So I recently got around to trying out NixOS. Part of that experience was setting up Syncthing, which I’ve used on the past on my machines and mobile phone to sync files related to note-taking.^[1] It was a bit confusing since I had to fill-in-the-blanks for a few steps. Here, I write about a bit of the blanks I had to fill in myself, stuff that was not clear from the existing docs and forum posts I discovered.

The configuration §

Below is the final NixOS configuration I have (with IDs elided for privacy) alongside commentary via comments:

systemd.services.syncthing.environment.STNODEFAULTFOLDER = "true"; # Don't create default ~/Sync folder.  See https://wiki.nixos.org/wiki/Syncthing
services.syncthing = {
  enable = true;
  openDefaultPorts = true;
  # I change the address SyncThing uses (which is also how you access the
  # browser UI).  This is to avoid conflicts with the other SyncThing instances
  # I have on the same machine.  Namely, from different WSL2 instances.
  guiAddress = "127.0.0.1:8385";
  user = "krisbalintona";
  group = "users";
  configDir = "/home/krisbalintona/.config/syncthing";
  # Override all settings set from the GUI.  This is necessary if I don't want
  # to have changes made from the GUI apply.
  overrideDevices = true;
  overrideFolders = true;
  # Settings: this is where you set up devices and folders
  settings = {
    devices = {
      "G14 2024 Arch" = {       # Name of SyncThing instance on other machine
        id = "OQHSZRL-L2TT7IC-7USSLNU-ST7JYML-FOO-BAR"; # Elided for privacy
      };
      "OnePlus 7 Pro" = {       # Name of SyncThing instance on mobile device
        id = "OVGYOBT-JPFQJKE-6CKRY7J-JULRCWK-FOO-BAR"; # Elided for privacy
      };
    };

    folders = {
      "k4vqh-foo" = {           # The ID of a folder you'd like to sync
        label = "Agenda";       # Optional device-specific folder name
        path = "/home/krisbalintona/Documents/org-database/agenda/";
        # Share with these devices
        devices = [
          "G14 2024 Arch WSL2"
          "OnePlus 7 Pro"
        ];
      };
      "qtuzy-foo" = {           # The ID of a folder you'd like to sync
        label = "Notes";        # Optional device-specific folder name
        path = "/home/krisbalintona/Documents/org-database/notes";
        # Share with these devices
        devices = [
          "G14 2024 Arch"
          "OnePlus 7 Pro"
        ];
      };
    };
  };
};

It was pretty straightforward to figure out the general settings for Syncthing by referencing NixOS Search. The tricky part was the “devices” and “folders” section. What should I put there? Below are the important bits.

Devices §

“Devices” are Machines/devices you’d like Syncthing to be aware of.
Each machine has an ID.
Each machine can optionally have a “label” (probably a human-readable name, like “Home computer”).

Looking at the relevant portion of my configuration:

devices = {
  "G14 2024 Arch" = {  # Name of SyncThing instance on other machine
    id = "OQHSZRL-L2TT7IC-7USSLNU-ST7JYML-FOO-BAR"; # Elided for privacy
  };
  "OnePlus 7 Pro" = {       # Name of SyncThing instance on mobile device
    id = "OVGYOBT-JPFQJKE-6CKRY7J-JULRCWK-FOO-BAR"; # Elided for privacy
  };
};

This tells Syncthing that I have two devices:

One labeled “G14 2024 Arch” with an ID of "OQHSZRL-L2TT7IC-7USSLNU-ST7JYML-FOO-BAR".
Another labeled “OnePlus 7 Pro” with an ID of "OVGYOBT-JPFQJKE-6CKRY7J-JULRCWK-FOO-BAR".

Now that Syncthing is aware of these devices, I can reference them by their label later in the folders section to specify which folders should be shared to which devices.

Folders §

Folders are the directories you’d like Syncthing to be aware of.
Each folder has an ID.^[2]
Each folder may optionally have a label (probably a human-readable name, like “Agenda”). This is basically a nickname you give to the folder specific to the current device.
Folders are only shared to devices specified for each folder.

Looking at the relevant portion of my configuration:

folders = {
  "k4vqh-foo" = {               # The ID of a folder you'd like to sync
    label = "Agenda";           # Optional device-specific folder name
    path = "/home/krisbalintona/Documents/org-database/agenda/";
    # Share with these devices
    devices = [
      "G14 2024 Arch WSL2"
      "OnePlus 7 Pro"
    ];
  };
  "qtuzy-foo" = {               # The ID of a folder you'd like to sync
    label = "Notes";            # Optional device-specific folder name
    path = "/home/krisbalintona/Documents/org-database/notes";
    # Share with these devices
    devices = [
      "G14 2024 Arch"
      "OnePlus 7 Pro"
    ];
  };
};

This tells Syncthing that I want to share two folders:

Share folder "k4vqh-foo", whose label is “Agenda,” with two devices: the one labeled “G14 2024 Arch WSL2” and another labeled “OnePlus 7 Pro.”
Share folder "qtuzy-foo", whose label is “Notes,” with two devices: the one labeled “G14 2024 Arch WSL2” and another labeled “OnePlus 7 Pro.”

It is important that the “devices” section be specified, otherwise Syncthing will not sync those folders to other devices.

Closing remarks §

And with that, I was done!

In sum:

Devices
- “Devices” are Machines/devices you’d like Syncthing to be aware of.
- Each machine has an ID.
- Each machine can optionally have a “label” (probably a human-readable name, like “Home computer”).
Folders
- Folders are the directories you’d like Syncthing to be aware of.
- Each folder has an ID.
- Each folder may optionally have a label (probably a human-readable name, like “Agenda”). This is basically a nickname you give to the folder specific to the current device.
- Folders are only shared to devices specified for each folder.

Simple, but it wasn’t obvious from the resources I encountered online, so I had to do some tinkering to figure it out myself.

For those who heavily customize Syncthing, there are other NixOS options available to tweak. You can find them in the NixOS Search for options. Additionally, if you are trying to migrate an existing Syncthing configuration to Nix, then you can check out your config file at ~/.config/syncthing/config.xml.^[3] With this, you can see the value of every Syncthing setting (although the file will, of course, be in JSON format).

Other resources §

Syncthing - NixOS Wiki: General resource; good starting point.
Vimjoyer - YouTube: A fantastic visual resource of making full use of Nix and NixOS. Has some beginner-friendly videos, but most videos are for intermediate or advanced users, ones looking to explore the ecosystem, full potential of Nix, and already having a familiarity with navigating Nix.

Changelog §

May 17, 2025
- Add link to the Syncthing configuration file documentation.

Citations in org-mode: Org-cite and Citar

Tue, 14 Jun 2022 23:52:00 GMT

Summary
Helpful sources
What are citation systems?
Org-cite
Citar
Other interesting packages
- Zotero
- Embark
- Org-roam-bibtex
- Citar-capf
- Org-ref
Changelog

Summary §

Jul 20, 2023 Readers should be aware that some package-specific information in this article may be outdated. Thus, readers are advised from outright copying code in this article without verifying (e.g. reading docstrings) the intended behavior. Nevertheless, the concepts related to org-cite and citation management should remain relevant and insightful.

First, I’ll outline the broadest components to producing files in org-mode with a citation system (e.g. org-cite, org-ref). Then I’ll introduce org-cite and the differences between its bibtex, csl, and basic export processors. Then, I will walk through my configuration for org-cite and citar (formerly bibtex-actions). You can see a gist/snippet of all the code present in this post here (alongside other additions of mine).

My goal is to plot the landscape, preparing you to understand other available sources which are more suited for a user already familiar with the landscape.

Helpful sources §

I recommend the following reading for more information regarding how org-cite works:

Citation handling (The Org Manual): The first source you should visit should almost always be the manual (available within Emacs via info, i.e. M-x info). It covers the fundamentals to understanding how to use org-cite. Isn’t well documented currently, but that will change in the future.
Org-cite guide by tecosaur: I’ll be referencing this frequently, for good reason.

What are citation systems? §

There are roughly three moving parts to citation management.

The tool that produces the bibliography file.
A bibliography file is where information regarding sources are stored. This almost always comes in the form of a .bib file; usually one is sufficient. There are various ways to create these files. Though you can manually create your own .bib files, the most common way is exporting a Zotero library (see Zotero).
The text processor.
This is the software the user (you) directly writes in. In our case, it’s Emacs!
The “layer” from text to product.
This is the code that lies in between your plain text writing and an output file (e.g. PDF). Sometimes this is identical to the text processor—in our case it isn’t. For instance, Microsoft Word is both a text editor and the producer of an output file, such as a PDF or a .docx.

org-cite lies closer to (3) because it is responsible for exporting citations, whereas citar is closer to (2) because it is an interface for inserting citations into the buffer. A software like Zotero is responsible for (1).

Org-cite §

In around July of 2021, org-cite was publicly released. org-cite a library packaged with org-mode that processes org citations (e.g. [cite:@wittgensteinTractatusLogicoPhilosophicus2021]). To those not familiar with another citation workflow (e.g. biblatex in LaTeX), it is quite daunting to leap into citations in Emacs. This was certainly the case for me: I leapt into org-mode citation integration with Zotero and LaTeX with no experience in org, Zotero, or LaTeX! Nonetheless, org-cite is quite simple once laid out. After reading this post or section, I recommend taking a look at tecosaur’s fabulous guide to using org-cite. His explanation of the citation styles of org-cite and their variants is particularly useful.

Understanding `org-cite` export processors §

The most crucial concept to org-cite are “export processors.” Take a look at the following passage from the documentation for org-cite-export-processors (as it is at the time of writing):

When non-nil, the value is an association list between export back-ends and
citation export processors:

(BACK-END . PROCESSOR)

where BACK-END is the name of an export back-end or t, and PROCESSOR is a
triplet following the pattern

(NAME BIBLIOGRAPHY-STYLE CITATION-STYLE)

There, NAME is the name of a registered citation processor providing export
functionality, as a symbol. BIBLIOGRAPHY-STYLE (respectively CITATION-STYLE)
is the desired default style to use when printing a bibliography (respectively
exporting a citation), as a string or nil. Both BIBLIOGRAPHY-STYLE and
CITATION-STYLE are optional. NAME is mandatory.

What this suggests is that different combinations of “processors,” “bibliography styles,” and “citation styles” can be configured to work with different org-export backends. Presently, there are three processors available: basic, csl, natbib, and bibtex. Though org-cite citations will always follow the same format, the output text that is exported will change depending on the processor used. I will go over these differences now, focusing primarily on the bibtex and csl backends^[1].

The bibtex processor can only be used with the latex backend. Using this processor exports citations using the BibLaTex LaTeX package. That means that [cite:@bradleyAppearanceRealityMetaphysical2011 82–5;] will export into a LaTeX command like \cite[82–5]{bradleyAppearanceRealityMetaphysical2011}. Compiling the org exported LaTeX file will in turn produce a PDF whose citations are handled by biblatex. The end citation style will be determined by the provided package options (e.g. style=mla-new). Read the biblatex documentation for more information (namely, section 3.1.1 in the February 2, 2022 version of the manual).

The natbib processor unsurprisingly uses the natbib LaTeX package. biblatex is slowly growing to replace the older natbib package, though some users may circumstantially be limited to natbib—you can read more about the differences between natbib and biblatex here. I have not personally used the natbib, but I suspect its usage is similar if not identical to the bibtex processor.

The csl processor will use CSL to export citations. Citation Style Language (CSL) is a language used to instruct the formatting of citations and bibliographies; citation styles are provided by .csl files. Most importantly, CSL is intended to be a universal standard for citation formatting. Accordingly, .csl supports essentially every output format.

In sum:

Which processor should I use? §

The most common confusion comes from realizing that CSL can also export to LaTeX. So, when exporting to LaTeX: should you use the csl or bibtex/natbib processor? The difference lies in whether or not you want to rely on the biblatex package to manage exports.

The important difference is that csl exports to rendered text. Rendered text is text whose end formatting will match that of org’s, e.g. italic text in org-mode will become wrapped in, say, \emph{} in LaTeX. So, for instance, if I export [cite:@bradleyAppearanceRealityMetaphysical2011 82–5;] into a LaTeX file using the csl processor using a CSL file for the Modern Language Association (MLA) citation style, I will see the following in-text citation in the LaTeX file as: (Bradley 82–85)—if anything needed to be bold, italicized, etc., then that would be wrapped in the appropriate LaTeX command. Contrast that with the LaTeX command in the paragraphs above.

So when it comes to exporting to LaTeX, when wouldn’t rendered text be enough? If you want the most basic functionality, i.e. “Seeing in-text citations and bibliographies in my documents is enough,” then CSL will always cover you. However, if you want access to the more complex or nuanced facilities of biblatex, use the bibtex processor instead. biblatex use cases include (i) using obscure or uncommon field and entry types and (ii) wanting “automation” in the citation variant. By (ii) I mean that biblatex handles the variant whereas you must manually list the variant in the org-cite citation when using CSL (see the above link to tecosaur’s guide).

I will give an example. Basic MLA in-text citations following a (AUTHOR PAGE) format. However, closely following MLA means that subsequent in-text citations from the same source should have a (PAGE) format. Using the csl processor, without specifying a style or variant in the org-cite citation, will always output the former formatting as rendered text; as r/bdarcus explains in his comment, CSL focuses on higher-level commands in order to be agnostic of output format. On the other hand, org-cite will, by default, leverage the \autocite command (see org-cite-biblatex-styles). This tells biblatex to change the variant when appropriate. This is an immensely powerful upside to using the bibtex processor—though it is minor in this particular case, this demonstrates the advantages of the biblatex package. You can read more about the differences between CSL and biblatex in this thorough StackExchange explanation. Of course, however, biblatex is only available when exporting to LaTeX, whereas CSL can be used to export into any format (e.g. HTML, Markdown, ODT, plain-text).

In sum, use the bibtex processor when you are exporting to LaTeX and only LaTeX and

want automatic selection of citation variants
or have rare field or entry types in your .bib file.

Otherwise, use the csl processor^[2] (assuming you have a .csl file for your desired citation style).

Finally, it should be noted that the csl and bibtex processors use different locators in citations. As explained in tecosaur’s guide, the csl processor uses locators like bk. and vol., so citations may look like [cite/noauthor:See@mollisonNietzscheContraStoicism2018 pp. 28–9;@priestWhyItIrrational2001 pp. 14;]—CSL processes these locators. On the other hand, a citation key’s suffix is directly passed as an option to BibLaTeX commands, so an equivalent to the above would be [cite/noauthor:See@mollisonNietzscheContraStoicism2018 28–9;@priestWhyItIrrational2001 14;], which doesn’t have CSL locators.

Configuration §

Luckily, the difficulty in org-cite is only conceptually: configuring it is incredibly straightforward. There are two main variables that affect functionality. The first is crucial, and the second is useful to be aware of:

org-cite-global-bibliography
org-cite-export-processors

org-cite-global-bibliography is the bare minimum to getting org-cite ready to work. This should be a list of bibliography file (.bib) paths. I have mine set to a list whose single element is a file that Zotero exports:

:custom
;; Actually, I set this value to `kb/bib-files', which is a list of file paths.
;; I set that as the value of any variable that requires bibliography files,
;; such as `citar', as you'll see below.
(org-cite-global-bibliography
 '("/home/krisbalintona/Documents/org-database/roam/references/master-lib.bib"))

Alternatively, you can use the org-mode #+BIBLIOGRAPHY: keyword to set this value per-file; it’s value should be a file path.

org-cite-export-processors is useful as a means to tweak how you’d like org-cite to export citations. You can also set a file-local value using the #+CITE_EXPORT file keyword (e.g. #+CITE_EXPORT: csl chicago-author-date.csl); see this section in tecosaur’s guide for an example of how to set the processor, bibliography style, and citation style with this keyword. For a given backend^[3], you can choose how org-cite exports it. For instance, here is mine:

:custom
(org-cite-export-processors
 '((md . (csl "chicago-fullnote-bibliography.csl"))   ; Footnote reliant
   (latex biblatex)                                   ; For humanities
   (odt . (csl "chicago-fullnote-bibliography.csl"))  ; Footnote reliant
   (t . (csl "modern-language-association.csl"))))      ; Fallback

As you can see, I have CSL be the default in every case aside from LaTeX. The styles can either be a file path or a file name in org-cite-csl-styles-dir—see Zotero for how to easily acquire CSL files.^[4] (I use LaTeX strictly for my academic papers, so I really enjoy biblatex’s features.)

I also choose to customize faces—I prefer the green faces that org-ref uses:^[5]

:custom-face
;; Have citation link faces look closer to as they were for `org-ref'
(org-cite ((t (:foreground "DarkSeaGreen4"))))
(org-cite-key ((t (:foreground "forest green" :slant italic))))

Usage §

Using org-cite is incredibly simple:

org-cite-insert to insert citations in org files, and
#+PRINT_BIBLIOGRAPHY: within a document to mark where the bibliography/references/works cited should be.^[6]

Citar §

Using org-cite is really simple. But many users will find the interface… too bare. Citar is, roughly, the foremost attempt to provide a pleasing frontend to org-cite. It adds the citar citation-insert processor. The following is the minimum to start using citar:

(use-package citar
  ;; The `:straight' keyword is not necessary. However, I do this to set a value
  ;; for the `:includes' keyword. This keyword tells use-package that those
  ;; package(s) are provided by this package, and not to search for them on
  ;; Melpa for download. Alternatively, you can set the `:straight' keyword to
  ;; nil in those package(s) use-package declaration.
  :straight (citar :type git :host github :repo "emacs-citar/citar" :includes (citar-org))
  :custom
  ;; A list of bib files. A good idea would be having its value be identical to
  ;; that of `org-cite-global-bibliography'. For me, I have all my bib file(s)
  ;; as a list of strings in `kb/bib-files'.
  (citar-bibliography kb/bib-files))

;; Use `citar' with `org-cite'
(use-package citar-org
  :after oc
  :custom
  (org-cite-insert-processor 'citar)
  (org-cite-follow-processor 'citar)
  (org-cite-activate-processor 'citar))

You can then set keybinds for common citar commands. For example, in the :general use-package keyword:^[7]

:general
(:keymaps 'org-mode-map
          :prefix "C-c b"
          "b" '(citar-insert-citation :wk "Insert citation")
          "r" '(citar-insert-reference :wk "Insert reference")
          "o" '(citar-open-notes :wk "Open note"))

If you use embark and org-roam you can also set these variables:

:custom
(citar-notes-paths (list kb/roam-dir)) ; List of directories for reference nodes
(citar-open-note-function 'orb-citar-edit-note) ; Open notes in `org-roam'
(citar-at-point-function 'embark-act)           ; Use `embark'

Capturing (Outdated) §

Aug 19, 2023 The citar-org-roam package provides all that is mentioned in this section and more. That package should be used instead in any instance of a desired integration between org-roam and citar.

If you use org-roam, then the following is how you select bibliographic source and create an org-roam node from it. All credit goes to Jethro Kuan, the creator of org-roam, though I’ve made a few of my own customizations:^[8]

;; Create a new node from a bibliographic source. taken from
;; https://jethrokuan.github.io/org-roam-guide/
(defun kb/org-roam-node-from-cite (keys-entries)
  (interactive (list (citar-select-ref :multiple nil :rebuild-cache t)))
  (let ((title (citar--format-entry-no-widths (cdr keys-entries)
                                              "${author editor}${date urldate} :: ${title}")))
    (org-roam-capture- :templates
                       '(("r" "reference" plain
                          "%?"
                          :if-new (file+head "references/${citekey}.org"
                                             ":properties:
:roam_refs: [cite:@${citekey}]
:end:
#+title: ${title}
#+filetags: %(kb/insert-lit-category)\n")
                          :immediate-finish t
                          :unnarrowed t))
                       :info (list :citekey (car keys-entries))
                       :node (org-roam-node-create :title title)
                       :props '(:finalize find-file))))

I add it to an accessible keybinding:^[9]

:general
(kb/note-keys                           ; global-map
 "C" '(kb/org-roam-node-from-cite :wk "Citar-capture"))

Advising `citar-org-update-pre-suffix` (Outdated) §

Jul 20, 2023 Upstream has recently merged changes to citar-org-update-pre-suffix, renaming it to citar-org-update-prefix-suffix and ensuring that a single space is left between citekeys and their suffixes. Therefore, the code directly below is now unnecessary.

A useful command is citar-org-update-pre-suffix. This command sets the prefix and suffix of a citation key (a single citation can have multiple keys). This is notable since a citation’s suffix is where you provide a locator (e.g. a page number). The command is bound to M-p when the point is on a citation key.

Before advising citar-org-update-pre-suffix, I first advise org-cite-insert such that citar-org-update-pre-suffix is run immediately after inserting a citation:

;; Run `citar-org-update-pre-suffix' after inserting a citation to immediately
;; set its prefix and suffix
(advice-add 'org-cite-insert :after #'(lambda (args)
                                        (save-excursion
                                          (left-char) ; First move point inside citation
                                          (citar-org-update-pre-suffix))))

A limitation with this code is that this only calls citar-org-update-pre-suffix on the last citation key, which is fine when only one key is inserted at once, and not when multiple are inserted. (Though, citar-org-update-pre-suffix can still be called manually on the other citation keys afterward.)

Additionally, I override citar-org-update-pre-suffix with my own version which adds the following functionality:

Temporarily enable typo-mode.^[10]
Avoid manually inserting a separating space in the suffix.

(defun kb/citar-org-update-pre-suffix ()
  "Change the pre/suffix text of the reference at point.

My version also adds a space in the suffix so I don't always have
to manually add one myself."
  (interactive)

  ;; Enable `typo' typographic character cycling in minibuffer. Particularly
  ;; useful in adding en- and em-dashes in citation suffixes (e.g. for page
  ;; ranges)
  (when (featurep 'typo)
    (add-hook 'minibuffer-mode-hook 'typo-mode)) ; Enable dashes

  (let* ((datum (org-element-context))
         (datum-type (org-element-type datum))
         (ref (if (eq datum-type 'citation-reference) datum
                (error "Not on a citation reference")))
         (key (org-element-property :key ref))
         ;; TODO handle space delimiter elegantly.
         (pre (read-string "Prefix text: " (org-element-property :prefix ref)))
         (post (read-string "Suffix text: " (org-element-property :suffix ref))))

    ;; Change post to automatically have one space prior to any user-inputted
    ;; suffix
    (setq post
          (if (string= (replace-regexp-in-string "\s-*" "" post) "")
              ""         ; If there is nothing of substance (e.g. an empty string)
            (replace-regexp-in-string "^[\s-]*" " " post))) ; Only begin with one space

    (setf (buffer-substring (org-element-property :begin ref)
                            (org-element-property :end ref))
          (org-element-interpret-data
           `(citation-reference
             (:key ,key :prefix ,pre :suffix ,post)))))

  ;; Remove hook if it was added earlier
  (remove-hook 'minibuffer-mode-hook 'typo-mode))
(advice-add 'citar-org-update-pre-suffix :override #'kb/citar-org-update-pre-suffix)

One can also add this command to citar-citation-map.^[11]

Aesthetics §

Finally, we can change the way the citar interface appears. The most relevant variables are citar-templates and citar-symbols. Below is my configuration for these variables. Notably, my definition for citar-symbols utilizes all-the-icons icons to fancify the candidates (all-the-icons must be installed in order to have the faces below available):

:custom
(citar-templates
 '((main . "${author editor:30}   ${date year issued:4}    ${title:110}")
   (suffix . "     ${=type=:20}    ${tags keywords keywords:*}")
   (preview . "${author editor} (${year issued date}) ${title}, ${journal journaltitle publisher container-title collection-title}.\n")
   (note . "#+title: Notes on ${author editor}, ${title}") ; For new notes
   ))
;; Configuring all-the-icons. From
;; https://github.com/bdarcus/citar#rich-ui
(citar-symbols
 `((file ,(all-the-icons-faicon "file-o" :face 'all-the-icons-green :v-adjust -0.1) .
         ,(all-the-icons-faicon "file-o" :face 'kb/citar-icon-dim :v-adjust -0.1) )
   (note ,(all-the-icons-material "speaker_notes" :face 'all-the-icons-blue :v-adjust -0.3) .
         ,(all-the-icons-material "speaker_notes" :face 'kb/citar-icon-dim :v-adjust -0.3))
   (link ,(all-the-icons-octicon "link" :face 'all-the-icons-orange :v-adjust 0.01) .
         ,(all-the-icons-octicon "link" :face 'kb/citar-icon-dim :v-adjust 0.01))))
(citar-symbol-separator "  ")
:init
;; Here we define a face to dim non 'active' icons, but preserve alignment.
;; Change to your own theme's background(s)
(defface kb/citar-icon-dim
  ;; Change these colors to match your theme. Using something like
  ;; `face-attribute' to get the value of a particular attribute of a face might
  ;; be more convenient.
  '((((background dark)) :foreground "#212428")
    (((background light)) :foreground "#f0f0f0"))
  "Face for having icons' color be identical to the theme
  background when \"not shown\".")

Here’s the end-result:

Visual improvements to citar’s minibuffer interface.

Other interesting packages §

Zotero §

Zotero isn’t an Emacs package, but it is crucial to most users’ workflow, so it deserves attention. Zotero makes gathering, storing, and exporting bibliographic data infinitely easier. For instance, an ISBN or DOI of a source is all that is necessary for an entry’s fields to be populated. There are two things to note about my setup:

I install the BetterBibLaTex add-on (see its features in the official documentation page. Its main benefits include unique citation key generation and exporting facilities),
and export my library using the BetterBibLaTeX format. I also tick the “Keep Updated” option; this continually updates the .bib file as I make changes to my library. I then point org-cite-global-bibliography and citar-bibliography to this file.

Additionally, for over a year now, I’ve been using Zotero’s own PDF viewer and annotator. Until recently, this feature had only been available in Zotero Beta, but it is now merged onto the main branch. Though it isn’t powerful, it gets the job done for me, and the convenience is what sells it.

Finally, a very handy tip is to use the CSL files that Zotero already provides (credit to this section of tecosaur’s guide). The CSL files (which provide citation styles) are located in ZOTERO_DIR/styles/. You can set org-cite-csl-styles-dir to this path:

:custom
(org-cite-csl-styles-dir
 (expand-file-name "~/Documents/Zotero/styles/"))

Embark §

Embark provides menus (essentially keymaps) based on “context,” that is, the type of thing the point is on. As a result, embark has immense potential. Citar is built to exploit embark without requiring it—for instance, see citar-citation-map.

Org-roam-bibtex §

Org-roam-bibtex integrates org-roam with citation systems, such as org-cite. This packages allows org-roam to recognize particular nodes as bibliographic (i.e. associated with a particular .bib entry).

Additionally, as as citar’s author, u/bdarcus, shares here, there is work being done on citar’s end to more tightly integrate org-roam with citar, in the form of citar-org-roam.

Citar-capf §

Citar-capf provides a complation-at-point-function^[12] for citations. However, if you’re reading this in the future, there’s a likely chance that this commit would have been merged. The commit merges citar-capf with citar.

Org-ref §

Org-ref has historically been the dominant citation system for org-mode. I elect to use org-cite instead because (i) it comes with org-mode, meaning there is one less conceptual- and configuration-layer to navigate, (ii) Moreover, org-ref uses a format that follows org conventions less closely, and (iii) I have read that is arguably more robust and future-proof. Nevertheless, some users still prefer it.

Changelog §

Jun 15, 2022
- Better clarity in Advising citar-org-update-pre-suffix (Outdated).
- Mention the merging of citar-capf into citar (see Citar-capf).
- Added Embark.
- Mention citar-org-roam in Org-roam-bibtex.
- Made comments clarifying kb/bib-files.
- Add screenshot that showcases visually improved citar interface (see Aesthetics).
Jun 19, 2022
- Added Helpful sources.
- Change processor explanations to include the natbib processor.
- Change processor explanations to recognize the difference between plain-text and rendered text.
Jul 20, 2023
- Noted that some package-specific information in this article may be outdated.
- Noted update to citar-org-update-pre-suffix
Aug 19, 2023
- Mentioned citar-org-roam as preferable to any desired integration between org-roam and citar.
Nov 20, 2023
- Updated GitLab Gist.

True Emacs Transparency

Tue, 07 Jun 2022 15:00:00 GMT

Transparency in Emacs isn’t that great. Every source I find regarding transparency of Emacs (as of writing this) points to setting the alpha frame parameter. For instance:

The issue with alpha is that it sets the transparency of the entire window; what this means is that text and background become transparent together. Clearly this is undesirable for some: the alpha parameter needs to be near 100, otherwise the text becomes illegible. Ideally, the text remains opaque while the background becomes transparent.^[1]

The solution came from a patched version of Emacs made by Håkon Flatval back in November 2021—his announcement that month on Reddit received some attention. The patch adds the alpha-background frame parameter which makes only the background of a frame transparent:

alpha-background set to 75.

You can set the alpha-background of a particular frame with the set-frame-parameter function, and the default value for frames by adding to default-frame-alist.^[2] For example:

(set-frame-parameter nil 'alpha-background 100) ; For current frame
(add-to-list 'default-frame-alist '(alpha-background . 100)) ; For all new frames henceforth

I’ve also defined my own command for toggling between a frame having alpha-background values of 100 and 72:^[3]

(defun kb/toggle-window-transparency ()
  "Toggle the value of `alpha-background'.

Toggles between 100 and 72 by default.  Can choose which value to change
to if called with ARG, or any prefix argument."
  (interactive "P")
  (let ((transparency (pcase arg
                        ((pred numberp) arg)
                        ((pred car) (read-number "Change the transparency to which value (0-100)? "))
                        (_
                         (pcase (frame-parameter nil 'alpha-background)
                           (72 100)
                           (100 72)
                           (t 100))))))
    (set-frame-parameter nil 'alpha-background transparency)))

Mar 8, 2025 Readers should be aware that the above code snippet may have potential incompatibilities with other versions of Emacs. Small modifications may be necessary in such cases.

In practice, this is what toggling transparency looks like:

Live-toggling of the alpha-background parameter.

I had been using Håkon’s patched version since becoming aware of it, and it’s been perfect for me. My only gripe was that without the expertise of patching future releases of Emacs (Håkon wasn’t updating his repository), I would inevitably be using an increasingly out-of-date version of Emacs.

However, I recently returned to check if there had been any updates to the repo. Though there were no new commits to the repository, I decided to check if there was work on mainline Emacs yet. I searched the repo for matches of alpha-background, and sure enough, I found a hit! On January 30, 2022, Po Lu silently announced the merging of the patch. Accordingly, this means that the alpha-background frame parameter is available to all builds after January 30, 2022. I’ll also note that do not know what went on behind-the-scenes to get this merged, so I’ll make it clear that I am not attributing the development of this feature to only Håkon and Po Lu.

Of course, transparency in Emacs (alongside any other application on your system) is only possible if you are using a compositor (e.g. Picom). Regarding build flags, Håkon’s patch supported transparency only with Emacs compiled with GTK3 and cairo support. I do not know for certain if this is still the case. If it is, then an Emacs built with the --with-cairo and --with-x-toolkit=gtk3 flags is necessary (meaning this feature is only available on machines using X Window). However, according to this Reddit comment thread, it seems like only cairo is necessary, while GTK3 is not necessary. That is, --with-x-toolkit=no works as well.

Changelog §

Jun 8, 2022
- Note that a compositor is necessary for transparency.
- Added statement about GTK3 perhaps not being necessary that links to a corresponding Reddit comment thread.
Mar 8, 2025
- Update code snippet for kb/toggle-window-transparency. Also add note about potential incompatibilities between this code snippet and other versions of Emacs.

Cape

Sun, 13 Mar 2022 07:02:00 GMT

What is cape?
Basic usage: keybinds
Adding backends to completion-at-point-functions
Cape-company-to-capf and cape-super-capf
pcomplete nicety
My completion-at-point-functions
Changelog

What is `cape`? §

I will be going over the basic usages of Cape, namely how to add completion functions to completion-at-point-functions and how to use cape's built-in completion utilities (e.g. cape-company-to-capf and cape-capf-buster) to create backends with desired behavior. (Also see u/JDRiverRun’s informative comment about the advantages of using completion-at-point-functions over company.)

Cape is to corfu as company-backends are to company:

Cape provides a bunch of Completion At Point Extensions which can be used in combination with my Corfu completion UI or the default completion UI. The completion backends used by completion-at-point are so called completion-at-point-functions (Capfs). In principle, the Capfs provided by Cape can also be used by Company.

Consequently, cape is only used if you utilize the built-in completion-at-point, which is best complemented by corfu text-completion ^[1].

You can also see the list of built-in completion-at-point-functions in the README. Several of these completion-at-point-functions are quite niche but others, such as cape-file and cape-symbol have common use cases.

Note: I use straight.el for package management and general.el to set my keybindings. Both of these packages have integration with use-package which come in the form of the :straight and :general keywords, respectively.

Basic usage: keybinds §

The most basic way to use cape is to bind its built-in completion-at-point-functions to their own keys. For instance:

(use-package cape
  :general (:prefix "M-c"              ; Choose a particular completion function
                    "p" 'completion-at-point
                    "t" 'complete-tag   ; etags
                    "d" 'cape-dabbrev   ; basically `dabbrev-completion'
                    "f" 'cape-file
                    "k" 'cape-keyword
                    "s" 'cape-symbol
                    "a" 'cape-abbrev
                    "i" 'cape-ispell
                    "l" 'cape-line
                    "w" 'cape-dict
                    "\\" 'cape-tex
                    "_" 'cape-tex
                    "^" 'cape-tex
                    "&" 'cape-sgml
                    "r" 'cape-rfc1345))

Additionally, if having completion-at-point-functions readily available through keybinds is desirable, then one can use cape-interactive-capf to turn an already existing completion-at-point-function into a command (i.e. interactive function) that can be bound.

Adding backends to `completion-at-point-functions` §

However, cape is powerful because these functions can be added to completion-at-point-functions, meaning you can configure when each functions is used and where. The simplest way to accomplish this is by adding backends to completion-at-point-functions in a hook. Here is a simple example:

(defun kb/cape-capf-setup-git-commit ()
  (let ((result))
    (dolist (element '(cape-symbol cape-dabbrev) result)
      (add-to-list 'completion-at-point-functions element))))

I then add this to the appropriate hook:

:hook (git-commit-mode . kb/cape-capf-setup-git-commit)

Consequently, when making commits to git, via magit, for instance, completion-at-point-functions looks like this^[2]:

'(cape-symbol
  cape-dabbrev
  tags-completion-at-point-function)

There are a few additional things to keep in mind when adding backends to completion-function-at-point:

add-to-list prepends elements to a list, that is, place an element at the front of a list^[3].
add-to-list is almost always preferable to push because push adds an element to a list even if it already in the list, whereas add-to-list will not.
Elements earlier in dolist will be added to the list before later elements. This means that elements which should be deeper within completion-at-point-functions should be placed first. (Notice how cape-dabbrev is added after cape-symbol.)

`Cape-company-to-capf` and `cape-super-capf` §

I think the killer feature of cape is cape-company-to-capf. This function is able to convert any company backend and convert it into a completion-at-point-function which corfu can use^[4]. For this reason, I regard cape as quite an underrated package since it achieves almost full feature parity with company. Here is an example with company-yasnippet:

(defun kb/cape-capf-setup-lsp ()
  "Replace the default `lsp-completion-at-point' with its
`cape-capf-buster' version. Also add `cape-file' and
`company-yasnippet' backends."
  (setf (elt (cl-member 'lsp-completion-at-point completion-at-point-functions) 0)
        (cape-capf-buster #'lsp-completion-at-point))
  (add-to-list 'completion-at-point-functions (cape-company-to-capf #'company-yasnippet))
  (add-to-list 'completion-at-point-functions #'cape-dabbrev t))

Another useful function is cape-super-capf. This function combines multiple completion-at-point-functions into a single function. Effectively, this means candidates from multiple backends can appear jointly. For instance, one can combine cape-ispell and cape-dabbrev:

(defun kb/cape-capf-setup-org ()
  (require 'org-roam)
  (if (org-roam-file-p)
      (org-roam--register-completion-functions-h)
    (let (result)
      (dolist (element (list
                        (cape-super-capf #'cape-ispell #'cape-dabbrev)
                        (cape-company-to-capf #'company-yasnippet))
                       result)
        (add-to-list 'completion-at-point-functions element)))
    ))

For other cape transformers, see the appropriate section of the README.

`pcomplete` nicety §

Finally, I have the following advice to make usage with pcomplete, what eshell uses for completion:

:config
;; For pcomplete. For now these two advices are strongly recommended to
;; achieve a sane Eshell experience. See
;; https://github.com/minad/corfu#completing-with-corfu-in-the-shell-or-eshell

;; Silence the pcomplete capf, no errors or messages!
(advice-add 'pcomplete-completions-at-point :around #'cape-wrap-silent)
;; Ensure that pcomplete does not write to the buffer and behaves as a pure
;; `completion-at-point-function'.
(advice-add 'pcomplete-completions-at-point :around #'cape-wrap-purify)

My `completion-at-point-functions` §

I have very hesitantly included my WIP code which leverages cape and completion-at-point utilities. I have not described in detail each of the following functions. I have, however, attempted to provide useful docstrings and comments.

I hesitate to publish this code because it was very haphazardly written and highly dependent on my configuration. The reason for this is the order in which the completion-at-point-functions are added: any peculiarities in another’s configuration may lead to undesirable results. As a result, do not directly copy-and-paste this code and expect proper functionality. Rather, I put it here as a reference for what can be done.

Here they are

Warning! This code may produce undesirable effects! Copy at your own risk.

(use-package cape
  :hook ((emacs-lisp-mode .  kb/cape-capf-setup-elisp)
         (lsp-completion-mode . kb/cape-capf-setup-lsp)
         (org-mode . kb/cape-capf-setup-org)
         (eshell-mode . kb/cape-capf-setup-eshell)
         (git-commit-mode . kb/cape-capf-setup-git-commit)
         (LaTeX-mode . kb/cape-capf-setup-latex)
         (sh-mode . kb/cape-capf-setup-sh)
         )
  :general (:prefix "M-c"               ; Particular completion function
                    "p" 'completion-at-point
                    "t" 'complete-tag           ; etags
                    "d" 'cape-dabbrev           ; or dabbrev-completion
                    "f" 'cape-file
                    "k" 'cape-keyword
                    "s" 'cape-symbol
                    "a" 'cape-abbrev
                    "i" 'cape-ispell
                    "l" 'cape-line
                    "w" 'cape-dict
                    "\\"' cape-tex
                    "_" 'cape-tex
                    "^" 'cape-tex
                    "&" 'cape-sgml
                    "r" 'cape-rfc1345
                    )
  :custom
  (cape-dabbrev-min-length 3)
  :init
  ;; Elisp
  (defun kb/cape-capf-ignore-keywords-elisp (cand)
    "Ignore keywords with forms that begin with \":\" (e.g.
:history)."
    (or (not (keywordp cand))
        (eq (char-after (car completion-in-region--data)) ?:)))
  (defun kb/cape-capf-setup-elisp ()
    "Replace the default `elisp-completion-at-point'
completion-at-point-function. Doing it this way will prevent
disrupting the addition of other capfs (e.g. merely setting the
variable entirely, or adding to list).

Additionally, add `cape-file' as early as possible to the list."
    (setf (elt (cl-member 'elisp-completion-at-point completion-at-point-functions) 0)
          #'elisp-completion-at-point)
    (add-to-list 'completion-at-point-functions #'cape-symbol)
    ;; I prefer this being early/first in the list
    (add-to-list 'completion-at-point-functions #'cape-file)
    (require 'company-yasnippet)
    (add-to-list 'completion-at-point-functions (cape-company-to-capf #'company-yasnippet)))

  ;; LSP
  (defun kb/cape-capf-setup-lsp ()
    "Replace the default `lsp-completion-at-point' with its
`cape-capf-buster' version. Also add `cape-file' and
`company-yasnippet' backends."
    (setf (elt (cl-member 'lsp-completion-at-point completion-at-point-functions) 0)
          (cape-capf-buster #'lsp-completion-at-point))
    ;; TODO 2022-02-28: Maybe use `cape-wrap-predicate' to have candidates
    ;; listed when I want?
    (add-to-list 'completion-at-point-functions (cape-company-to-capf #'company-yasnippet))
    (add-to-list 'completion-at-point-functions #'cape-dabbrev t))

  ;; Org
  (defun kb/cape-capf-setup-org ()
    (require 'org-roam)
    (if (org-roam-file-p)
        (org-roam--register-completion-functions-h)
      (let (result)
        (dolist (element (list
                          (cape-super-capf #'cape-ispell #'cape-dabbrev)
                          (cape-company-to-capf #'company-yasnippet))
                         result)
          (add-to-list 'completion-at-point-functions element)))
      ))

  ;; Eshell
  (defun kb/cape-capf-setup-eshell ()
    (let ((result))
      (dolist (element '(pcomplete-completions-at-point cape-file) result)
        (add-to-list 'completion-at-point-functions element))
      ))

  ;; Git-commit
  (defun kb/cape-capf-setup-git-commit ()
    (general-define-key
     :keymaps 'local
     :states 'insert
     "<tab>" 'completion-at-point)      ; Keybinding for `completion-at-point'
    (let ((result))
      (dolist (element '(cape-dabbrev cape-symbol) result)
        (add-to-list 'completion-at-point-functions element))))

  ;; LaTeX
  (defun kb/cape-capf-setup-latex ()
    (require 'company-auctex)
    (let ((result))
      (dolist (element (list
                        ;; First add `company-yasnippet'
                        (cape-company-to-capf #'company-yasnippet)
                        ;; Then add `cape-tex'
                        #'cape-tex
                        ;; Then add `company-auctex' in the order it adds its
                        ;; backends.
                        (cape-company-to-capf #'company-auctex-bibs)
                        (cape-company-to-capf #'company-auctex-labels)
                        (cape-company-to-capf
                         (apply-partially #'company--multi-backend-adapter
                                          '(company-auctex-macros company-auctex-symbols company-auctex-environments))))
                       result)
        (add-to-list 'completion-at-point-functions element))))


  ;; Sh
  (defun kb/cape-capf-setup-sh ()
    (require 'company-shell)
    (add-to-list 'completion-at-point-functions (cape-company-to-capf #'company-shell)))
  :config
  ;; For pcomplete. For now these two advices are strongly recommended to
  ;; achieve a sane Eshell experience. See
  ;; https://github.com/minad/corfu#completing-with-corfu-in-the-shell-or-eshell

  ;; Silence the pcomplete capf, no errors or messages!
  (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-silent)
  ;; Ensure that pcomplete does not write to the buffer and behaves as a pure
  ;; `completion-at-point-function'.
  (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-purify))

Changelog §

Mar 13, 2022
- Fixed typo. Added link to u/JDRiverRun’s informative Reddit comment.

Corfu, Kind-icon, and Corfu-doc

Sun, 27 Feb 2022 06:56:00 GMT

Synopsis
Corfu
Kind-icon
Corfu-doc
Changelog

Nov 28, 2022 As is noted in the corfu-doc repository, corfu-doc has been deprecated by the built-in corfu-popupinfo corfu extension. corfu-popupinfo’s functionality is roughly identical to corfu-doc’s, though its interface and code is naturally more idiomatic to corfu.

Synopsis §

I will be going over my personal Emacs’ text completion (e.g. company-mode and its accessories) configuration, which includes the following packages:

Corfu by Minad — simpler alternative to company-mode
Kind-icon by jdtsmith (u/JDRiverRun)— add icons to corfu popup (analog to company-box-icons)
Corfu-doc by Galeo — add documentation popup for corfu candidates (analog to company-box-doc)

Corfu §

What is `corfu`? How does it differ from `company`? §

The default corfu popup window. The GIF’s framerate is low, which makes corfu appear less performant here than in actuality.

Corfu is a text completion (e.g. completion-at-point, company-mode) package. In my opinion, since its release, corfu has not gotten the attention that it deserves. I prefer it to company for the following reasons:

It is easier to configure since corfu’s internals rely on the built-in completion-at-point. This also means that, unlike company,^[1]…
- any built-in invocation of completion-at-point or completion-in-region leverages corfu,
- and any completion-style (e.g. orderless) can be used for filtering candidates.
Corfu has been more performant (i.e. fewer stutters, smoother cycling of candidates) in my experience.
Corfu can support any company backend via cape-company-to-capf, provided by the complementary cape package. Thus, packages like company-yasnippet can be used with corfu easily (see the next post in my Text completion and minibuffer UI series for more details and examples.)

Basic §

The following is a basic corfu configuration with my preferred keybinds:

(use-package corfu
  :general
  (:keymaps 'corfu-map
            :states 'insert
            "C-n" #'corfu-next
            "C-p" #'corfu-previous
            "<escape>" #'corfu-quit
            "<return>" #'corfu-insert
            "M-d" #'corfu-show-documentation
            "M-l" #'corfu-show-location)
  :config
  (corfu-global-mode))

These keybinds have C-n and C-p move through the candidates popup, <return> choose the current candidate, and <escape> close the corfu popup. Moreover, I have corfu’s documentation command (corfu-show-documentation; shows the available documentation for the current candidate, if any) bound to M-d, and corfu’s location command (corfu-show-location) to go to the location of the current candidate to M-l.

Corfu offers a few variables to configure. You can take a look at each docstring to see its function. Here are my preferences:

:custom
(corfu-auto nil)        ; Only use `corfu' when calling `completion-at-point' or
                                        ; `indent-for-tab-command'
(corfu-auto-prefix 2)
(corfu-auto-delay 0.25)

(corfu-min-width 80)
(corfu-max-width corfu-min-width)       ; Always have the same width
(corfu-count 14)
(corfu-scroll-margin 4)
(corfu-cycle nil)

;; `nil' means to ignore `corfu-separator' behavior, that is, use the older
;; `corfu-quit-at-boundary' = nil behavior. Set this to separator if using
;; `corfu-auto' = `t' workflow (in that case, make sure you also set up
;; `corfu-separator' and a keybind for `corfu-insert-separator', which my
;; configuration already has pre-prepared). Necessary for manual corfu usage with
;; orderless, otherwise first component is ignored, unless `corfu-separator'
;; is inserted.
(corfu-quit-at-boundary nil)
(corfu-preselect-first t)        ; Preselect first candidate?

;; Other
;; NOTE 2022-02-05: In my actual configuration, I have this variable set to nil
;; since I use `corfu-doc', whose configuration comes later. But if you don't
;; use `corfu-doc', this might be helpful to you.
(corfu-echo-documentation t)            ; Show documentation in echo area?

Additionally, the following two variables not under corfu but related to completion-at-point will be useful to set:

;; Works with `indent-for-tab-command'. Make sure tab doesn't indent when you
;; want to perform completion
(tab-always-indent 'complete)
(completion-cycle-threshold nil)      ; Always show all candidates in popup menu

Working with the recent changes to `corfu` §

On February 7, 2022, corfu introduced an important change^[2], particularly the interaction between corfu and orderless. You can read more on their README, but, essentially, orderless now introduces the corfu-insert-separator command that inserts the corfu-separator character into the buffer. This character is what delimits orderless components (see this Reddit comment for a more lengthy description of this behavior.) A corfu workflow in which corfu-auto is set to t leverages this change, for without it users could not realistically use corfu with a multi-component completion-style like orderless.

I do not use this workflow^[3], but if this behavior is desirable, you can set corfu-separator to your orderless separator character to properly delimit orderless components. I personally use the regular space character. You can make the following modifications to your configuration:

:general
;; NOTE 2022-02-28: `general-override-mode-map' is necessary to override local
;; binds to SPC in evil-mode's insert mode. May not be necessary if you don't use `evil'
(:keymaps 'corfu-map
          :states 'insert
          "H-SPC" #'corfu-insert-separator ; I have a hyper key so this is an alternative keybind I use sometimes
          "SPC" #'corfu-insert-separator)
:custom
(corfu-quit-at-boundary 'separator)     ; a non-nil value is necessary
(corfu-separator ?\s)                   ; Use space
(corfu-quit-no-match 'separator) ; Don't quit if there is `corfu-separator' inserted
(corfu-preview-current 'insert)  ; Preview current candidate?
:config
;; NOTE 2022-03-01: This allows for a more evil-esque way to have
;; `corfu-insert-separator' work with space in insert mode without resorting to
;; overriding keybindings with `general-override-mode-map'. See
;; https://github.com/minad/corfu/issues/12#issuecomment-869037519
;; Alternatively, add advice without `general.el':
;; (advice-add 'corfu--setup :after 'evil-normalize-keymaps)
;; (advice-add 'corfu--teardown :after 'evil-normalize-keymaps)
(general-add-advice '(corfu--setup corfu--teardown) :after 'evil-normalize-keymaps)
(evil-make-overriding-map corfu-map)

Further configuration in minibuffers and with `lsp` §

Corfu’s README provides a way to be able to use corfu completion in the minibuffer:

;; Enable Corfu more generally for every minibuffer, as long as no other
;; completion UI is active. If you use Mct or Vertico as your main minibuffer
;; completion UI. From
;; https://github.com/minad/corfu#completing-with-corfu-in-the-minibuffer
(defun corfu-enable-always-in-minibuffer ()
  "Enable Corfu in the minibuffer if Vertico/Mct are not active."
  (unless (or (bound-and-true-p mct--active) ; Useful if I ever use MCT
              (bound-and-true-p vertico--input))
    (setq-local corfu-auto nil)       ; Ensure auto completion is disabled
    (corfu-mode 1)))
(add-hook 'minibuffer-setup-hook #'corfu-enable-always-in-minibuffer 1)

This means that in commands like eval-expression, corfu is able to be used (via <tab>) and provide completion.

Using corfu in the minibuffer prompt for eval-expression.

Additionally, for lsp-mode buffers, I have the following lines (this is entirely optional and preferential):

:hook (lsp-completion-mode . kb/corfu-setup-lsp) ; Use corfu for lsp completion
:custom
(lsp-completion-provider :none) ; Use corfu instead the default for lsp completions
:config
;; Setup lsp to use corfu for lsp completion
(defun kb/corfu-setup-lsp ()
  "Use orderless completion style with lsp-capf instead of the
  default lsp-passthrough."
  (setf (alist-get 'styles (alist-get 'lsp-capf completion-category-defaults))
        '(orderless)))

End product §

Putting it together, we end with my actual configuration:

(use-package corfu
  :hook (lsp-completion-mode . kb/corfu-setup-lsp) ; Use corfu for lsp completion
  :general
  (:keymaps 'corfu-map
            :states 'insert
            "C-n" #'corfu-next
            "C-p" #'corfu-previous
            "<escape>" #'corfu-quit
            "<return>" #'corfu-insert
            "H-SPC" #'corfu-insert-separator
            ;; "SPC" #'corfu-insert-separator ; Use when `corfu-quit-at-boundary' is non-nil
            "M-d" #'corfu-show-documentation
            "C-g" #'corfu-quit
            "M-l" #'corfu-show-location)
  :custom
  ;; Works with `indent-for-tab-command'. Make sure tab doesn't indent when you
  ;; want to perform completion
  (tab-always-indent 'complete)
  (completion-cycle-threshold nil)      ; Always show candidates in menu

  (corfu-auto nil)
  (corfu-auto-prefix 2)
  (corfu-auto-delay 0.25)

  (corfu-min-width 80)
  (corfu-max-width corfu-min-width)     ; Always have the same width
  (corfu-count 14)
  (corfu-scroll-margin 4)
  (corfu-cycle nil)

  ;; `nil' means to ignore `corfu-separator' behavior, that is, use the older
  ;; `corfu-quit-at-boundary' = nil behavior. Set this to separator if using
  ;; `corfu-auto' = `t' workflow (in that case, make sure you also set up
  ;; `corfu-separator' and a keybind for `corfu-insert-separator', which my
  ;; configuration already has pre-prepared). Necessary for manual corfu usage with
  ;; orderless, otherwise first component is ignored, unless `corfu-separator'
  ;; is inserted.
  (corfu-quit-at-boundary nil)
  (corfu-separator ?\s)            ; Use space
  (corfu-quit-no-match 'separator) ; Don't quit if there is `corfu-separator' inserted
  (corfu-preview-current 'insert)  ; Preview first candidate. Insert on input if only one
  (corfu-preselect-first t)        ; Preselect first candidate?

  ;; Other
  (corfu-echo-documentation nil)        ; Already use corfu-doc
  (lsp-completion-provider :none)       ; Use corfu instead for lsp completions
  :init
  (corfu-global-mode)
  :config
  ;; NOTE 2022-03-01: This allows for a more evil-esque way to have
  ;; `corfu-insert-separator' work with space in insert mode without resorting to
  ;; overriding keybindings with `general-override-mode-map'. See
  ;; https://github.com/minad/corfu/issues/12#issuecomment-869037519
  ;; Alternatively, add advice without `general.el':
  ;; (advice-add 'corfu--setup :after 'evil-normalize-keymaps)
  ;; (advice-add 'corfu--teardown :after 'evil-normalize-keymaps)
  (general-add-advice '(corfu--setup corfu--teardown) :after 'evil-normalize-keymaps)
  (evil-make-overriding-map corfu-map)

  ;; Enable Corfu more generally for every minibuffer, as long as no other
  ;; completion UI is active. If you use Mct or Vertico as your main minibuffer
  ;; completion UI. From
  ;; https://github.com/minad/corfu#completing-with-corfu-in-the-minibuffer
  (defun corfu-enable-always-in-minibuffer ()
    "Enable Corfu in the minibuffer if Vertico/Mct are not active."
    (unless (or (bound-and-true-p mct--active) ; Useful if I ever use MCT
                (bound-and-true-p vertico--input))
      (setq-local corfu-auto nil)       ; Ensure auto completion is disabled
      (corfu-mode 1)))
  (add-hook 'minibuffer-setup-hook #'corfu-enable-always-in-minibuffer 1)

  ;; Setup lsp to use corfu for lsp completion
  (defun kb/corfu-setup-lsp ()
    "Use orderless completion style with lsp-capf instead of the
default lsp-passthrough."
    (setf (alist-get 'styles (alist-get 'lsp-capf completion-category-defaults))
          '(orderless))))

Kind-icon §

Kind-icon is essentially company-box-icons for corfu. It adds icons to the left margin of the corfu popup that represent the ‘function’ (e.g. variable, method, file) of that candidate.

Using corfu-doc in java-mode with completion candidates provided by lsp-mode.

The following is my configuration:

(use-package kind-icon
  :after corfu
  :custom
  (kind-icon-use-icons t)
  (kind-icon-default-face 'corfu-default) ; Have background color be the same as `corfu' face background
  (kind-icon-blend-background nil)  ; Use midpoint color between foreground and background colors ("blended")?
  (kind-icon-blend-frac 0.08)

  ;; NOTE 2022-02-05: `kind-icon' depends `svg-lib' which creates a cache
  ;; directory that defaults to the `user-emacs-directory'. Here, I change that
  ;; directory to a location appropriate to `no-littering' conventions, a
  ;; package which moves directories of other packages to sane locations.
  (svg-lib-icons-dir (no-littering-expand-var-file-name "svg-lib/cache/")) ; Change cache dir
  :config
  (add-to-list 'corfu-margin-formatters #'kind-icon-margin-formatter) ; Enable `kind-icon'

  ;; Add hook to reset cache so the icon colors match my theme
  ;; NOTE 2022-02-05: This is a hook which resets the cache whenever I switch
  ;; the theme using my custom defined command for switching themes. If I don't
  ;; do this, then the backgound color will remain the same, meaning it will not
  ;; match the background color corresponding to the current theme. Important
  ;; since I have a light theme and dark theme I switch between. This has no
  ;; function unless you use something similar
  (add-hook 'kb/themes-hooks #'(lambda () (interactive) (kind-icon-reset-cache))))

Corfu-doc §

Corfu-doc is basically company-quickhelp for corfu. It shows the documentation of the selected candidate in an adjacent popup window.

Using corfu-doc in a corfu popup. Called from a java file with completion candidates provided by lsp-mode.

Here is a sample configuration^[4]:

(use-package corfu-doc
  ;; NOTE 2022-02-05: At the time of writing, `corfu-doc' is not yet on melpa
  :straight (corfu-doc :type git :host github :repo "galeo/corfu-doc")
  :after corfu
  :hook (corfu-mode . corfu-doc-mode)
  :general (:keymaps 'corfu-map
                     ;; This is a manual toggle for the documentation popup.
                     [remap corfu-show-documentation] #'corfu-doc-toggle ; Remap the default doc command
                     ;; Scroll in the documentation window
                     "M-n" #'corfu-doc-scroll-up
                     "M-p" #'corfu-doc-scroll-down)
  :custom
  (corfu-doc-delay 0.5)
  (corfu-doc-max-width 70)
  (corfu-doc-max-height 20)

  ;; NOTE 2022-02-05: I've also set this in the `corfu' use-package to be
  ;; extra-safe that this is set when corfu-doc is loaded. I do not want
  ;; documentation shown in both the echo area and in the `corfu-doc' popup.
  (corfu-echo-documentation nil))

From my experience, corfu-doc is perfect for most. However, it should be noted that for those who have a high repeat rate^[5], rapidly scrolling through candidates causes stuttering and/or lag. This is why I find setting a keybind for corfu-doc-toggle to be useful.

Changelog §

Feb 28, 2022
- Added link to Reddit comment in Working with the recent changes to corfu section. Also update description of new corfu behavior.
- Added configuration for using corfu in the minibuffer.
- Listed more benefits to corfu, provided by u/JDRiverRun.
Mar 1, 2022
- Added link to relevant corfu GitHub Issue.
- Changed corfu configuration to avoid setting keybinds in general-override-mode-map, suggested by a comment to this point.
- Added a note and GIF to corfu-doc section.
Mar 11, 2022
- Update to include new compatibility with corfu-insert-separator and corfu-quit-at-boundary functionality.

Vertico, Marginalia, All-the-icons-completion, and Orderless

Mon, 21 Feb 2022 21:46:00 GMT

Synopsis
Marginalia
All-the-icons-completion
Vertico
Orderless
Changelog

Synopsis §

Apr 5, 2025 Readers should be aware that some of the package-specific information in this article, including configuration options and lines of code, may be outdated. Since publication, those packages have developed significantly. Additionally, my tastes and recommendations as an Emacs user have changed–if I were to rewrite this package today, I would do so different. For those curious about my current in-line and minibuffer completion configuration, you can the relevant sections in my Emacs configuration.

I will be walking through my personal Emacs’ minibuffer UI (which means packages like Selectrum, Ido, Helm, Vertico, and Ivy) configuration, which includes the following packages:

Marginalia — minibuffer annotations, i.e., auxiliary candidate information
All-the-icons-completion — all-the-icons icons for minibuffer candidates
Vertico — vertical minibuffer interface
Orderless — a flexible completion-style with multi-component matching

Marginalia §

The following is vertico with marginalia annotations right-aligned in the minibuffer.

Using helpful-variable

Using find-file

Marginalia is painless to set up. Remember, I use general.el to set keybindings:

(use-package marginalia
  :general
  (:keymaps 'minibuffer-local-map
            "M-A" 'marginalia-cycle)
  :custom
  (marginalia-max-relative-age 0)
  (marginalia-align 'right)
  :init
  (marginalia-mode))

All-the-icons-completion §

Marginalia, Vertico, and Orderless have already received considerable exposure, but all-the-icons-completion has not.

Using find-file in a directory with subdirectories, python files, a .txt file, and an org file. You can see the icons in the far left.

All-the-icons-completion is also dead-simple to set up:

(use-package all-the-icons-completion
  :after (marginalia all-the-icons)
  :hook (marginalia-mode . all-the-icons-completion-marginalia-setup)
  :init
  (all-the-icons-completion-mode))

Note: All-the-icons-completion depends on an already installed all-the-icons.

Vertico §

Vertico is a minibuffer interface, that is, it changes the minibuffer looks and how you interact with it.

Basic §

This is a very basic Vertico configuration.

(use-package vertico
  :custom
  (vertico-count 13)                    ; Number of candidates to display
  (vertico-resize t)
  (vertico-cycle nil) ; Go from last to first candidate and first to last (cycle)?
  :config
  (vertico-mode))

Now we can add a few changes to the default keybindings (again, I use general.el to set keybindings):

(use-package vertico
  :custom
  (vertico-count 13)                    ; Number of candidates to display
  (vertico-resize t)
  (vertico-cycle nil) ; Go from last to first candidate and first to last (cycle)?
  :general
  (:keymaps 'vertico-map
            "<tab>" #'vertico-insert  ; Insert selected candidate into text area
            "<escape>" #'minibuffer-keyboard-quit ; Close minibuffer
            ;; NOTE 2022-02-05: Cycle through candidate groups
            "C-M-n" #'vertico-next-group
            "C-M-p" #'vertico-previous-group)
  :config
  (vertico-mode))

Extensions §

Vertico becomes much more interesting with its extensions. These extensions have to manually be cloned from the repo with a corresponding require invocation. However, with straight.el, we can do something like this to install and load them:

(use-package vertico
  ;; Special recipe to load extensions conveniently
  :straight (vertico :files (:defaults "extensions/*")
                     :includes (vertico-indexed
                                vertico-flat
                                vertico-grid
                                vertico-mouse
                                vertico-quick
                                vertico-buffer
                                vertico-repeat
                                vertico-reverse
                                vertico-directory
                                vertico-multiform
                                vertico-unobtrusive
                                ))
  :general
  (:keymaps 'vertico-map
            "<tab>" #'vertico-insert    ; Choose selected candidate
            "<escape>" #'minibuffer-keyboard-quit ; Close minibuffer
            ;; NOTE 2022-02-05: Cycle through candidate groups
            "C-M-n" #'vertico-next-group
            "C-M-p" #'vertico-previous-group)
  :custom
  (vertico-count 13)                    ; Number of candidates to display
  (vertico-resize t)
  (vertico-cycle nil) ; Go from last to first candidate and first to last (cycle)?
  :config
  (vertico-mode))

With the extensions installed, we have a lot of room to set their variables to our liking. In particular, vertico-multiform is the most interesting and, in my opinion, useful. You can choose how the minibuffer appears, which is provided by Vertico’s extensions (see more here). The current options are

buffer — minibuffer treated as a normal, separate buffer,

Vertico-buffer UI (minibuffer now a separate window)
flat — a flat format (like ido),

Vertico-flat minibuffer UI
grid — a grid format,

Vertico-grid UI
reverse — moves the area in which you type above the candidates, like selectrum,

Vertico-reverse UI. Notice the text area is below the candidates. Moreover, the candidates are in reverse order.
unobtrusive — like the vertico-flat format, but only showing the selected candidate,

Vertico-unobtrusive UI (there are multiple files in this directory, only the current candidate is shown)
indexed — allows you “to select indexed candidates with prefix arguments”

Vertico-indexed UI

These formats each have a separate minor-mode which can be activated if you want to use that format singly. However, with vertico-multiform-mode as well as configuration of vertico-multiform-categories, vertico-multiform-commands, and keybinds, you can enable/disable multiple of these formats simultaneously:

(vertico-multiform-mode)

Here are the extension variables I set in the :custom block of my use-package:

(vertico-grid-separator "       ")
(vertico-grid-lookahead 50)
(vertico-buffer-display-action '(display-buffer-reuse-window)) ; Default
(vertico-multiform-categories                                  ; Choose a multiform
 '((file reverse)
   (consult-grep buffer)
   (consult-location)
   (imenu buffer)
   (library reverse indexed)
   (org-roam-node reverse indexed)
   (t reverse)))
(vertico-multiform-commands
 '(("flyspell-correct-*" grid reverse)
   (org-refile grid reverse indexed)
   (consult-yank-pop indexed)
   (consult-flycheck)
   (consult-lsp-diagnostics)))

Here are the vertico-multiform related keybinds I have in my :general block:

(:keymaps 'vertico-map
          ;; Toggle Vertico multiforms in active minibuffer
          "C-i" #'vertico-quick-insert
          "C-o" #'vertico-quick-exit
          "M-G" #'vertico-multiform-grid
          "M-F" #'vertico-multiform-flat
          "M-R" #'vertico-multiform-reverse
          "M-U" #'vertico-multiform-unobtrusive)

These are rarely used, but can be handy.

Finally, the other Vertico extensions I configure are vertico-repeat and vertico-directory. I add the following keybinds:

(:keymaps '(normal insert visual motion)
          "M-." #'vertico-repeat) ; Perfectly return to the state of the last Vertico minibuffer usage
(:keymaps 'vertico-map
          ;; Vertico-directory which makes typing file paths in the minibuffer
          ;; more convenient. Use it to get a sense of what these do
          "<backspace>" #'vertico-directory-delete-char
          "C-w" #'vertico-directory-delete-word
          "C-<backspace>" #'vertico-directory-delete-word
          "RET" #'vertico-directory-enter)

Additionally, we need to add the following hook for vertico-repeat:

:hook (minibuffer-setup . vertico-repeat-save) ; Make sure vertico state is saved for `vertico-repeat'

Vertico extension commands §

If you’d like, you can set up a toggle between two multiforms in the minibuffer. For instance, the following function definition with a corresponding keybind in vertico-map toggles between vertico-flat-mode and vertico-reverse-mode:

(defun kb/vertico-multiform-flat-toggle ()
  "Toggle between flat and reverse."
  (interactive)
  (vertico-multiform--display-toggle 'vertico-flat-mode)
  (if vertico-flat-mode
      (vertico-multiform--temporary-mode 'vertico-reverse-mode -1)
    (vertico-multiform--temporary-mode 'vertico-reverse-mode 1)))

The following function uses vertico-quick-jump (like avy but for minibuffer candidates) to embark-act on a candidate without having to first hover over the candidate:

(defun kb/vertico-quick-embark (&optional arg)
  "Embark on candidate using quick keys."
  (interactive)
  (when (vertico-quick-jump)
    (embark-act arg)))

Niceties §

Finally, I add a few niceties.

The following prefixes (i.e. in the left fringe) and arrow character on the currently selected candidate^[1]:

;; Prefix the current candidate with “» ”. From
;; https://github.com/minad/vertico/wiki#prefix-current-candidate-with-arrow
(advice-add #'vertico--format-candidate :around
            (lambda (orig cand prefix suffix index _start)
              (setq cand (funcall orig cand prefix suffix index _start))
              (concat
               (if (= vertico--index index)
                   (propertize "» " 'face 'vertico-current)
                 "  ")
               cand)))

When using a command for selecting a file in the minibuffer, the following fixes the path so the path you select doesn’t have prepended junk left behind^[2]:

:hook (rfn-eshadow-update-overlay . vertico-directory-tidy) ; Correct file path when changed

Using find-file and going from a subdirectory in $HOME to the distant /tmp/ directory. Notice that the file-path is “cleaned up.”

Finally, the following makes working with remote files via tramp easier.

;; Workaround for problem with `tramp' hostname completions. This overrides
;; the completion style specifically for remote files! See
;; https://github.com/minad/vertico#tramp-hostname-completion
(defun kb/basic-remote-try-completion (string table pred point)
  (and (vertico--remote-p string)
       (completion-basic-try-completion string table pred point)))
(defun kb/basic-remote-all-completions (string table pred point)
  (and (vertico--remote-p string)
       (completion-basic-all-completions string table pred point)))
(add-to-list 'completion-styles-alist
             '(basic-remote           ; Name of `completion-style'
               kb/basic-remote-try-completion kb/basic-remote-all-completions nil))

End product §

In the end, we have this^[3]:

(use-package vertico
  :demand t                             ; Otherwise won't get loaded immediately
  :straight (vertico :files (:defaults "extensions/*") ; Special recipe to load extensions conveniently
                     :includes (vertico-indexed
                                vertico-flat
                                vertico-grid
                                vertico-mouse
                                vertico-quick
                                vertico-buffer
                                vertico-repeat
                                vertico-reverse
                                vertico-directory
                                vertico-multiform
                                vertico-unobtrusive))
  :general
  (:keymaps '(normal insert visual motion)
            "M-." #'vertico-repeat)
  (:keymaps 'vertico-map
            "<tab>" #'vertico-insert ; Set manually otherwise setting `vertico-quick-insert' overrides this
            "<escape>" #'minibuffer-keyboard-quit
            "?" #'minibuffer-completion-help
            "C-M-n" #'vertico-next-group
            "C-M-p" #'vertico-previous-group
            ;; Multiform toggles
            "<backspace>" #'vertico-directory-delete-char
            "C-w" #'vertico-directory-delete-word
            "C-<backspace>" #'vertico-directory-delete-word
            "RET" #'vertico-directory-enter
            "C-i" #'vertico-quick-insert
            "C-o" #'vertico-quick-exit
            "M-o" #'kb/vertico-quick-embark
            "M-G" #'vertico-multiform-grid
            "M-F" #'vertico-multiform-flat
            "M-R" #'vertico-multiform-reverse
            "M-U" #'vertico-multiform-unobtrusive
            "C-l" #'kb/vertico-multiform-flat-toggle)
  :hook ((rfn-eshadow-update-overlay . vertico-directory-tidy) ; Clean up file path when typing
         (minibuffer-setup . vertico-repeat-save)) ; Make sure vertico state is saved
  :custom
  (vertico-count 13)
  (vertico-resize t)
  (vertico-cycle nil)
  ;; Extensions
  (vertico-grid-separator "       ")
  (vertico-grid-lookahead 50)
  (vertico-buffer-display-action '(display-buffer-reuse-window))
  (vertico-multiform-categories
   '((file reverse)
     (consult-grep buffer)
     (consult-location)
     (imenu buffer)
     (library reverse indexed)
     (org-roam-node reverse indexed)
     (t reverse)))
  (vertico-multiform-commands
   '(("flyspell-correct-*" grid reverse)
     (org-refile grid reverse indexed)
     (consult-yank-pop indexed)
     (consult-flycheck)
     (consult-lsp-diagnostics)))
  :init
  (defun kb/vertico-multiform-flat-toggle ()
    "Toggle between flat and reverse."
    (interactive)
    (vertico-multiform--display-toggle 'vertico-flat-mode)
    (if vertico-flat-mode
        (vertico-multiform--temporary-mode 'vertico-reverse-mode -1)
      (vertico-multiform--temporary-mode 'vertico-reverse-mode 1)))
  (defun kb/vertico-quick-embark (&optional arg)
    "Embark on candidate using quick keys."
    (interactive)
    (when (vertico-quick-jump)
      (embark-act arg)))

  ;; Workaround for problem with `tramp' hostname completions. This overrides
  ;; the completion style specifically for remote files! See
  ;; https://github.com/minad/vertico#tramp-hostname-completion
  (defun kb/basic-remote-try-completion (string table pred point)
    (and (vertico--remote-p string)
         (completion-basic-try-completion string table pred point)))
  (defun kb/basic-remote-all-completions (string table pred point)
    (and (vertico--remote-p string)
         (completion-basic-all-completions string table pred point)))
  (add-to-list 'completion-styles-alist
               '(basic-remote           ; Name of `completion-style'
                 kb/basic-remote-try-completion kb/basic-remote-all-completions nil))
  :config
  (vertico-mode)
  ;; Extensions
  (vertico-multiform-mode)

  ;; Prefix the current candidate with “» ”. From
  ;; https://github.com/minad/vertico/wiki#prefix-current-candidate-with-arrow
  (advice-add #'vertico--format-candidate :around
              (lambda (orig cand prefix suffix index _start)
                (setq cand (funcall orig cand prefix suffix index _start))
                (concat
                 (if (= vertico--index index)
                     (propertize "» " 'face 'vertico-current)
                   "  ")
                 cand))))

Orderless §

Orderless is an alternative and powerful completion style, that is, it is an alternative to Emacs’s basic candidate-filtering capacities.

Basic §

To use orderless you simply need the following.

(use-package orderless
  :custom
  (completion-styles '(orderless))      ; Use orderless
  (completion-category-defaults nil)    ; I want to be in control!
  (completion-category-overrides
   '((file (styles basic-remote ; For `tramp' hostname completion with `vertico'
                   orderless)))))

However, we want to be more interesting! The following configures the matching styles that orderless uses. A matching style is a criterion for what is a valid candidate (a description of what each matching style does can be found in Orderless’s readme):

:custom
(orderless-matching-styles
 '(orderless-literal
   orderless-prefixes
   orderless-initialism
   orderless-regexp
   ;; orderless-flex                       ; Basically fuzzy finding
   ;; orderless-strict-leading-initialism
   ;; orderless-strict-initialism
   ;; orderless-strict-full-initialism
   ;; orderless-without-literal          ; Recommended for dispatches instead
   ))

Style dispatchers §

A first component of “lm” using the prot-orderless-strict-initialism-dispatcher style dispatcher, and a second component of “map” using the prot-orderless-literal-dispatcher.

Orderless becomes much more powerful when using its style dispatchers. A description of style dispatches can be found here. Essentially, you can choose which matching style is used for a particular orderless component. Thus, one component can use the orderless-initialism matching style while the next can use the orderless-literal matching style, and the result will be candidates which match both styles:

;; The following is taken directly from Protesilaos's Emacs configuration, with
;; very minor changes. See
;; https://gitlab.com/protesilaos/dotfiles/-/blob/master/emacs/.emacs.d/prot-emacs.el
:custom
(orderless-style-dispatchers
 '(prot-orderless-literal-dispatcher           ; = suffix for literal
   prot-orderless-strict-initialism-dispatcher ; , suffix for initialism
   prot-orderless-flex-dispatcher              ; . suffix for flex
   ))
:init
(defun orderless--strict-*-initialism (component &optional anchored)
  "Match a COMPONENT as a strict initialism, optionally ANCHORED.
The characters in COMPONENT must occur in the candidate in that
order at the beginning of subsequent words comprised of letters.
Only non-letters can be in between the words that start with the
initials.

If ANCHORED is `start' require that the first initial appear in
the first word of the candidate.  If ANCHORED is `both' require
that the first and last initials appear in the first and last
words of the candidate, respectively."
  (orderless--separated-by
      '(seq (zero-or-more alpha) word-end (zero-or-more (not alpha)))
    (cl-loop for char across component collect `(seq word-start ,char))
    (when anchored '(seq (group buffer-start) (zero-or-more (not alpha))))
    (when (eq anchored 'both)
      '(seq (zero-or-more alpha) word-end (zero-or-more (not alpha)) eol))))

(defun orderless-strict-initialism (component)
  "Match a COMPONENT as a strict initialism.
This means the characters in COMPONENT must occur in the
candidate in that order at the beginning of subsequent words
comprised of letters.  Only non-letters can be in between the
words that start with the initials."
  (orderless--strict-*-initialism component))

(defun prot-orderless-literal-dispatcher (pattern _index _total)
  "Literal style dispatcher using the equals sign as a suffix.
It matches PATTERN _INDEX and _TOTAL according to how Orderless
parses its input."
  (when (string-suffix-p "=" pattern)
    `(orderless-literal . ,(substring pattern 0 -1))))

(defun prot-orderless-strict-initialism-dispatcher (pattern _index _total)
  "Leading initialism  dispatcher using the comma suffix.
It matches PATTERN _INDEX and _TOTAL according to how Orderless
parses its input."
  (when (string-suffix-p "," pattern)
    `(orderless-strict-initialism . ,(substring pattern 0 -1))))

(defun prot-orderless-flex-dispatcher (pattern _index _total)
  "Flex  dispatcher using the tilde suffix.
It matches PATTERN _INDEX and _TOTAL according to how Orderless
parses its input."
  (when (string-suffix-p "." pattern)
    `(orderless-flex . ,(substring pattern 0 -1))))

Finally, rather than using the default “+ “ to separate components, I use a space instead:

:custom
(orderless-component-separator 'orderless-escapable-split-on-space) ; Use backslash for literal space

End product §

The end result is this^[4]:

(use-package orderless
  :custom
  (completion-styles '(orderless))
  (completion-category-defaults nil)    ; I want to be in control!
  (completion-category-overrides
   '((file (styles basic-remote ; For `tramp' hostname completion with `vertico'
                   orderless
                   ))
     ))

  (orderless-component-separator 'orderless-escapable-split-on-space)
  (orderless-matching-styles
   '(orderless-literal
     orderless-prefixes
     orderless-initialism
     orderless-regexp
     ;; orderless-flex
     ;; orderless-strict-leading-initialism
     ;; orderless-strict-initialism
     ;; orderless-strict-full-initialism
     ;; orderless-without-literal          ; Recommended for dispatches instead
     ))
  (orderless-style-dispatchers
   '(prot-orderless-literal-dispatcher
     prot-orderless-strict-initialism-dispatcher
     prot-orderless-flex-dispatcher))
  :init
  (defun orderless--strict-*-initialism (component &optional anchored)
    "Match a COMPONENT as a strict initialism, optionally ANCHORED.
The characters in COMPONENT must occur in the candidate in that
order at the beginning of subsequent words comprised of letters.
Only non-letters can be in between the words that start with the
initials.

If ANCHORED is `start' require that the first initial appear in
the first word of the candidate.  If ANCHORED is `both' require
that the first and last initials appear in the first and last
words of the candidate, respectively."
    (orderless--separated-by
        '(seq (zero-or-more alpha) word-end (zero-or-more (not alpha)))
      (cl-loop for char across component collect `(seq word-start ,char))
      (when anchored '(seq (group buffer-start) (zero-or-more (not alpha))))
      (when (eq anchored 'both)
        '(seq (zero-or-more alpha) word-end (zero-or-more (not alpha)) eol))))

  (defun orderless-strict-initialism (component)
    "Match a COMPONENT as a strict initialism.
This means the characters in COMPONENT must occur in the
candidate in that order at the beginning of subsequent words
comprised of letters.  Only non-letters can be in between the
words that start with the initials."
    (orderless--strict-*-initialism component))

  (defun prot-orderless-literal-dispatcher (pattern _index _total)
    "Literal style dispatcher using the equals sign as a suffix.
It matches PATTERN _INDEX and _TOTAL according to how Orderless
parses its input."
    (when (string-suffix-p "=" pattern)
      `(orderless-literal . ,(substring pattern 0 -1))))

  (defun prot-orderless-strict-initialism-dispatcher (pattern _index _total)
    "Leading initialism  dispatcher using the comma suffix.
It matches PATTERN _INDEX and _TOTAL according to how Orderless
parses its input."
    (when (string-suffix-p "," pattern)
      `(orderless-strict-initialism . ,(substring pattern 0 -1))))

  (defun prot-orderless-flex-dispatcher (pattern _index _total)
    "Flex  dispatcher using the tilde suffix.
It matches PATTERN _INDEX and _TOTAL according to how Orderless
parses its input."
    (when (string-suffix-p "." pattern)
      `(orderless-flex . ,(substring pattern 0 -1)))))

Changelog §

Apr 5, 2025
- Add a note at the beginning of the post alerting users of potentially outdated information as well as referencing my personal Emacs configuration.
- Minor updates to code formatting.
Feb 22, 2022 Added demonstrative images and a GIF. Added section on all-the-icons-completion.

An Amazing Marvin Starter Pack

Thu, 24 Jun 2021 22:37:00 GMT

TL;DR
Core concepts
- The Master List
- The Main View
What good is Amazing Marvin’s system?
The beauty of Strategies
A list of must-look-at Strategies
Author’s Note

TL;DR §

Read this if you are either 1) interested in and want to try out Amazing Marvin, 2) just started using Amazing Marvin but feel overwhelmed, or 3) don’t know what Amazing Marvin is but want to read about a few of its features.

This post goes over the peculiarities of Amazing Marvin — namely the Master List, Main View, and Strategies. Understanding these concepts is the first step to leveraging the strengths of Amazing Marvin to create your own workflow.

I’ve also added a list of the first Strategies a new Mavinaut (users of Amazing Marvin) should check out.

By the end you’ll have a grasp of Amazing Marvin’s foundational components and ready to start building your own workflow.

Core concepts §

The Master List §

You open Marvin. You’re greeted with a friendly UI — you notice buttons and a sidebar. Press “M” and you’ll be taken to the Master List. This is the place where you can see all your tasks. Think of it as the closest thing to a generic todo list application, like Microsoft Todo. You can view your tasks and projects (which can be further separated into categories) in either a column or list view (try it out!).

You may also notice a sidebar on the left which also lists tasks and projects — this can be toggled using “X”. This will be handy in the future, but isn’t necessary to worry about for now.

In the Master List, I sometimes add tasks in bulk, which will often be when I want to flesh out tasks for a project. Though you can easily access all your projects and tasks using the Master List, you will likely not spend much time here.

The Main View §

The place where you will most interact with your todos and get things done is the Main View. The Main View is where you decide which tasks are shown, when they are shown, and how they are shown to you by taking advantage of Amazing Marvin’s customizability.

The Main View is centralized around being able to show you what you want to do today. This doesn’t, however, necessarily mean that Marvin is limited to showing you tasks which are due today. Amazing Marvin is more powerful than that and has the flexibility to accommodate so many workflows.

What good is Amazing Marvin’s system? §

Those are the two most important pieces to wrap your head around using Amazing Marvin. But why depart from the typical todo list format?

The strength of this system is that you have access to all your tasks in your Master List but don’t have to look through these long task lists — even sorted or filtered, they are overwhelming and dissuasive to productivity — in order to get things done. The Main View creates a divide between working on your tasks and viewing them. This is a surprisingly powerful feature of Marvin, which removes much of the difficulty of trying to juggle tasks within folders or across tags. You choose when to see the subset of tasks you want to work on, and go to the Master List when you choose to see all of your tasks.

The beauty of Strategies §

On top of that, Marvin is still feature-rich yet manages to limit that complexity for an easier learning curve. How Marvin accomplishes this is through its clever Strategies system. Strategies allow you to only enable the features which are useful to you. They can be thought of as togglable features.

Strategies are one of the aspects that make Amazing Marvin shine. It gives you the flexibility to implement as many strategies as you want (again, think of them as features) into your workflow or be as minimalist as possible and use only a select few. In the end, Amazing Marvin can be customized to how you think and work.

This is different from other task management apps, which follows the “you-get-what-you-see model.” In other task management apps, users have to use a space in which every feature, whether useful to them or not, coexists. This is especially the case with bloated or other feature-rich task management apps. In this way, Marvin can be feature-rich but much less overwhelming than other task management solutions.

Amazing Marvin goes a step further by providing brief yet useful descriptions for every Strategy on how to use it. Additionally, there is often an accompanying short video (made by Christina, one of the founders, herself) demonstrating what the Strategy looks like in action. Finally, most strategies have a list of settings which allow you to further fine tune your experience.

A list of must-look-at Strategies §

To conclude, I’ve included several lists of Strategies that should be taken a look at as soon as possible as a new user. In addition to checking these Strategies out, Workflow Templates are curated sets of settings and strategies which have been pre-made for you. They range from small snippets to full workflows. I’d highly recommend looking through these templates as a starting point for your workflow.

Standalone, non-intrusive, must-use Strategies

Subtasks
Mobile sidebar
Check off Behavior
Right-click menu
Hover button actions

Other common Strategies which are easy to set up

Quick add
Task notes
Category context
Skinny sidebar
Sidebar

Strategies you will likely be looking for if you’ve used other task management applications

Labels (tags)
Task reminders
Duration estimates
Full-calendar functionality
1. Calendar
2. Agenda
3. All-day items
4. Events
Smart lists (?)
Priority levels
Sequential projects

Useful Strategies which are standalone, easy to understand, yet aren’t found in almost any other task management app (Experiment with them!)

Work session scheduler
Eat that Frog
Procrastination count
Backburner
Time tracking
Missing Next Step warning
Timers

Author’s Note §

I have not been told to write about Amazing Marvin. I receive no compensation from Amazing Marvin for this post. I only want to share this amazing piece of software with others.

Kristoffer Balintona — #Guide

Surprisingly, Emacs on Android is pretty good

Table of Contents

The good and bad: what to expect on Android §

Installation §

Option 1 §

Option 2 (recommended) §

Configuring an Android-specific Emacs §

Necessary reading: the manual §

How to configure your init.el on a mobile device? §

First step: A Better UI for touchscreens §

Android-specific Commands and Options §

Use a Special virtual keyboard §

Fonts §

Tip: You can remap the volume buttons §

Conclusion §

Bonus: My wish list §

Some Notes Setting Up Syncthing in NixOS

Table of Contents

The configuration §

Devices §

Folders §

Closing remarks §

Other resources §

Changelog §

Citations in org-mode: Org-cite and Citar

Table of Contents

Summary §

Helpful sources §

What are citation systems? §

Org-cite §

Understanding org-cite export processors §

Which processor should I use? §

Configuration §

Usage §

Citar §

Capturing (Outdated) §

Advising citar-org-update-pre-suffix (Outdated) §

Aesthetics §

Other interesting packages §

Zotero §

Embark §

Org-roam-bibtex §

Citar-capf §

Org-ref §

Changelog §

True Emacs Transparency

Changelog §

Cape

Table of Contents

What is cape? §

Basic usage: keybinds §

Adding backends to completion-at-point-functions §

Cape-company-to-capf and cape-super-capf §

pcomplete nicety §

My completion-at-point-functions §

Changelog §

Corfu, Kind-icon, and Corfu-doc

Table of Contents

Synopsis §

Corfu §

What is corfu? How does it differ from company? §

Basic §

Working with the recent changes to corfu §

Further configuration in minibuffers and with lsp §

End product §

Kind-icon §

Corfu-doc §

Changelog §

Vertico, Marginalia, All-the-icons-completion, and Orderless

Table of Contents

Synopsis §

Marginalia §

All-the-icons-completion §

Vertico §

Basic §

Extensions §

Vertico extension commands §

Niceties §

End product §

How to configure your `init.el` on a mobile device? §

Understanding `org-cite` export processors §

Advising `citar-org-update-pre-suffix` (Outdated) §

What is `cape`? §

Adding backends to `completion-at-point-functions` §

`Cape-company-to-capf` and `cape-super-capf` §

`pcomplete` nicety §

My `completion-at-point-functions` §

What is `corfu`? How does it differ from `company`? §

Working with the recent changes to `corfu` §

Further configuration in minibuffers and with `lsp` §