~/.emacs.d

Instead of using the stable Emacs from Nixpkgs, this configuration uses emacs-overlay to build Emacs from its master branch. The overlay updates daily, but this configuration only updates sporadically, when there’s reason to do so, to keep everything as stable as possible.

I’m inclined to use a stable version of Emacs instead of building from Git, as I’m not specifically looking to be on the bleeding edge. However, newly added features tend to pull me in.

Currently, there are two reasons I’m currently running on a prerelease version:

1. Emacs master updated its included version of the modus-themes, including the tinted variants of modus-vivendi and modus-operandi, which are my preferred themes. Running Emacs master therefor requires one less dependency.
2. Completion-preview.el, a fish-like completion-at-point package, was merged into master in e82d807a2845673e2d55a27915661b2f1374b89a.

To build a Nix derivation that intalls Emacs from Git using Emacs-overlay, import nixpkgs, and then apply the overlay from a tarball. Then, return pkgs.emacs-git:

{ pkgs ? import <nixpkgs> {
  overlays = [
    (import (builtins.fetchTarball {
      url = https://github.com/nix-community/emacs-overlay/archive/f7fcac1403356fd09e2320bc3d61ccefe36c1b91.tar.gz;
    }))
  ];
} }:

pkgs.emacs-git

In this example, the version of emacs-overlay (and thus Emacs itself) is locked to a specific version. To use the latest version, replace the revision hash with a branch name like master.

Assuming the derivation is saved to a file named emacs-git.nix, it can be built through nix build:

Nix disables the withXwidgets option for Emacs on macOS, so simply enabling it won’t work yet:

{ pkgs ? import <nixpkgs> {
  overlays = [
    (import (builtins.fetchTarball {
      url = https://github.com/nix-community/emacs-overlay/archive/f7fcac1403356fd09e2320bc3d61ccefe36c1b91.tar.gz;
    }))
  ];
} }:

pkgs.emacs-git.overrideAttrs(old: {
  withXwidgets = true;
})

In the meantime, circumvent Nix’s option by manually adding the build flag. As expected, enabling XWidgets also requires the WebKit framework as a build input:

{ pkgs ? import <nixpkgs> {
  overlays = [
    (import (builtins.fetchTarball {
      url = https://github.com/nix-community/emacs-overlay/archive/f7fcac1403356fd09e2320bc3d61ccefe36c1b91.tar.gz;
    }))
  ];
} }:

pkgs.emacs-git.overrideAttrs(old: {
  buildInputs = old.buildInputs ++ [
    pkgs.darwin.apple_sdk.frameworks.WebKit
  ];

  configureFlags = old.configureFlags ++ ["--with-xwidgets"];
})

Emacs Plus is a Homebrew formula to build Emacs on macOS, which applies a couple of patches while building. First, download the patches for the correct Emacs version. In this case, get the patches for Emacs 30:

curl https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-30/system-appearance.patch -o patches/system-appearance.patch
curl https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-30/round-undecorated-frame.patch -o patches/round-undecorated-frame.patch
curl https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-30/poll.patch -o patches/poll.patch
curl https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-28/fix-window-role.patch -o patches/fix-window-role.patch

Then, override the attributes in pkgs.emacs-git when using emacs-overlay—or pkgs.emacs when building Emacs from Nixpkgs—to add all path files to the package’s patches list:

{ pkgs ? import <nixpkgs> {
  overlays = [
    (import (builtins.fetchTarball {
      url = https://github.com/nix-community/emacs-overlay/archive/f7fcac1403356fd09e2320bc3d61ccefe36c1b91.tar.gz;
    }))
  ];
} }:

pkgs.emacs-git.overrideAttrs(old: {
  patches = old.patches ++ [
    ./patches/system-appearance.patch
    ./patches/round-undecorated-frame.patch
    ./patches/poll.patch
    ./patches/fix-window-role.patch
  ];
})

Assuming the derivation is saved to a file named emacs-patched.nix, it can be built through nix build:

nix build --file emacs-patched.nix
open /result/Applications/Emacs.app

The emacsWithPackagesFromUsePackage function parses configuration files in search of packages to bundle with Emacs. For example, to package Emacs with Evil and enable evil-mode on startup, add a use-package statement as the emacs configuration:

{ pkgs ? import <nixpkgs> {
  overlays = [
    (import (builtins.fetchTarball {
      url = https://github.com/nix-community/emacs-overlay/archive/f7fcac1403356fd09e2320bc3d61ccefe36c1b91.tar.gz;
    }))
  ];
} }:

pkgs.emacsWithPackagesFromUsePackage {
  package = pkgs.emacs-git;
  config = ''
  (use-package evil
    :ensure t
    :init
    (evil-mode 1))
  '';
  defaultInitFile = true;
}

Assuming the derivation is saved to a file named emacs-enil.nix, it can be built through nix build:

nix build --file emacs-evil.nix
open /result/Applications/Emacs.app

By combining the features in Emacs overlay, this configuration produces configured Emacs, a version of Emacs with macOS-specific patches applied, XWidgets enabled, packages installed and a full configuration loaded. The included configuration file is default.el, which is generated from the rest of this configuration.

{ pkgs ? import <nixpkgs> {
  overlays = [
    (import (builtins.fetchTarball {
      url = https://github.com/nix-community/emacs-overlay/archive/f7fcac1403356fd09e2320bc3d61ccefe36c1b91.tar.gz;
    }))
  ];
} }:

pkgs.emacsWithPackagesFromUsePackage {
  package = (
    pkgs.emacs-git.overrideAttrs(old: {
      patches = old.patches ++ [
        ./patches/system-appearance.patch
        ./patches/round-undecorated-frame.patch
        ./patches/poll.patch
        ./patches/fix-window-role.patch
      ];

      buildInputs = old.buildInputs ++ [
        pkgs.darwin.apple_sdk.frameworks.WebKit
      ];

      configureFlags = old.configureFlags ++ ["--with-xwidgets"];
    })
  );

  config = ./default.el;
  defaultInitFile = true;
}

Disable the scroll bar, the tool bar, and the menu bar:

(scroll-bar-mode -1)
(tool-bar-mode -1)
(menu-bar-mode -1)

Use Iosevka as a monospace font (fixed in Emacs lingo), and Iosevka’s “Aile” variant as a (quasi-)proportional font (variable-pitch in Emacs lingo).

Both variants are used with their regular weights, expanded widths, and a height of 150 (15 points × 10):

(defun jk/set-face-font (face family)
  (set-face-attribute
   face nil
   :family family :weight 'regular :width 'expanded :height 150))

(jk/set-face-font 'default "Iosevka")
(jk/set-face-font 'fixed-pitch "Iosevka")
(jk/set-face-font 'variable-pitch "Iosevka Aile")

The face-font-family-alternatives variable provides fallback fonts if the preferred fonts aren’t available. This produces a font list akin to CSS font-families, starting with the preferred font and falling back to an option that is most likely to be available on any system. Having a list of fallback fonts like this removes the need to explicitly depend on fonts being available.

This configuration falls back to Apple’s SF Mono and SF Pro if the Iosevka fonts aren’t available. Since the Apple fonts need to be downloaded explicitly, they aren’t more likely to be there than the Iosevka ones, but they’re included as they were the previous favorite.

If the SF fonts aren’t available, the fixed font falls back to Menlo before the default monospace font (which is most likely Courier). The variable pitch font falls back to SF Pro, Helvetica, and finally Arial:

(custom-set-variables
  '(face-font-family-alternatives
  '(("Iosevka" "SF Mono" "Menlo" "monospace")
    ("Iosevka Aile" "SF Pro" "Helvetica" "Arial"))))

To use proportional fonts (as opposed to monospaced fonts) for non-code text, enable variable-pitch-mode for selected modes. While this mode is enabled, the default font face inherits from variable-pitch instead of fixed-pitch.

An often-recommended approach is to hook into text-mode, which is the major mode most text-based modes inherit from:

(add-hook 'text-mode-hook #'variable-pitch-mode))

Doing so automatically enables variable-pitch-mode thenever text-mode is enabled.

This works, but it’s a bit too eager for my liking. The above configuration enables variable-pitch-mode when editing Org files, but also when writing commit messages and editing YAML files. I consider text in the latter two as code, so I’d prefer to have those displayed in a monospace font.

Instead of hooking into text-mode, explicitly select the modes to use proportional fonts in Org and Markdown mode:

(add-hook 'org-mode-hook #'variable-pitch-mode)
(add-hook 'markdown-mode-hook #'variable-pitch-mode)

The Modus themes are a set of beautiful and customizable themes, which are shipped with Emacs since version 28.

The modus themes consist of two types: Modus Operandi is a light theme, and Modus Vivendi is its dark counterpart. The tinted variants shift the background colors from white and black to a more pleasant light ochre and dark blue.

When using the version of the Modus themes that’s included in Emacs, the themes need to be explicitly required using require-theme:

(require-theme 'modus-themes)

To select modus-operandi-tinted as the default theme, load it with the load-theme function:

(load-theme 'modus-operandi-tinted)

An interactive function named modus-themes-toggle switches between the light and dark themes. By default, the function switches between the non-tinted versions, but that can be overwritten to use the tinted versions through the modus-themes-to-toggle variable:

(setq modus-themes-to-toggle '(modus-operandi-tinted modus-vivendi-tinted))

The spacious-padding package adds spacing around windows and frames, as well as padding the mode line.

Turn on spacious-padding-mode to add spacing around windows and frames:

(spacious-padding-mode 1)

Turn on spacious-padding-subtile-mode-line for a more subtile mode line:

(setq spacious-padding-subtle-mode-line t)

Emacs is the best Vim emulator, and Evil is the best Vim mode. After installing Evil, turn on evil-mode globally:

Instead of enabling Evil’s gloval evil-mode hook, turn it on per buffer. By hooking into both prog-mode and text-mode, Evil mode is only turned on for programming and text editing buffers.

(add-hook 'prog-mode-hook 'turn-on-evil-mode)
(add-hook 'text-mode-hook 'turn-on-evil-mode)

Evil-commentary is an Evil port of vim-commentary which adds key bindings to call Emacs’ built in comment-or-uncomment-region function. Turn it on by calling evil-commentary-mode:

(evil-commentary-mode 1)

An example of an essential difference between Emacs and Vim is how they handle the location of the cursor (named point in Emacs). In Vim, the cursor is on a character, while Emacs’ point is before it. In Evil mode, the cursor changes between a box in “normal mode” to a bar in “insert mode”. Because Emacs is always in a kind of insert mode, make the cursor a bar:

(setq-default cursor-type 'bar)

Vertico is a vertical completion library, based on Emacs’ default completion system.

(vertico-mode 1)

Marginalia adds extra contextual information to minibuffer completions. For example, besides just showing command names when executing M-x, the package adds a description of the command and the key binding.

(marginalia-mode 1)

Consult provides enhancements to built-in search and navigation commands. There is a long list of available commands, but this configuration mostly uses Consult for buffer switching with previews.

1. Replace switch-to-buffer (C-x b) with consult-buffer:

   (global-set-key (kbd "C-x b") 'consult-buffer)
   

2. Replace project-switch-to-buffer (C-x p b) with consult-project-buffer:

   (global-set-key (kbd "C-x p b") 'consult-project-buffer)
   

3. Replace goto-line (M-g g and M-g M-g) with consult-goto-line:

   (global-set-key (kbd "M-g g") 'consult-goto-line)
   (global-set-key (kbd "M-g M-g") 'consult-goto-line)
   

4. Replace project-find-regexp (C-x p g) with consult-ripgrep:

   (global-set-key (kbd "C-x p g") 'consult-ripgrep)
   

Orderless is a completion style that divides the search pattern in space-separated components, and matches regardless of their order. After installing it, add it as a completion style by setting completion-styles:

(setq completion-styles '(orderless basic))

Embark adds actions to minibuffer results. For example, when switching buffers with switch-to-buffer or consult-buffer, pressing C-. opens Embark’s list of key bindings. From there, you can act on results in the minibuffer. In this exampke, pressing k kills the currently selected buffer.

(global-set-key (kbd "C-.") 'embark-act)

Emacs’ savehist feature saves minibuffer history to ~/emacs.d/history. The history is then used to order vertical completion suggestions.

(savehist-mode 1)

Emacs 30 includes completion-preview.el, since e82d807a2845673e2d55a27915661b2f1374b89a, which adds grayed-out completion previews while typing, akin to the autocomplete in the Fish shell.

(global-completion-preview-mode 1)

Programming environments set up with Nix and direnv alter the environment and available programs based on the current directory. To provide access to programs on a per-directory level, use the Emacs direnv package:

(direnv-mode 1)

Eglot is Emacs’ built-in Language Server Protocol client. Language servers are added through the eglot-server-programs variable:

(add-to-list 'eglot-server-programs '((rust-ts-mode rust-mode) "rust-analyzer"))
(add-to-list 'eglot-server-programs '((elixir-ts-mode elixir-mode) "elixir-ls"))
(add-to-list 'eglot-server-programs '((nix-mode) "nixd"))

Start eglot automatically for Nix an Rust files:

(add-hook 'nix-mode #'eglot-ensure)
(add-hook 'rust-mode #'eglot-ensure)
(add-hook 'rust-ts-mode #'eglot-ensure)

Use Eat (Emulate A Terminal) as a terminal emulator. If Eat prints “garbled” text, run M-x eat-compile-terminfo, then restart the Eat buffer.

Aside from starting the terminal emulator with M-x eat and M-x eat-project, Eat adds terminal emulation to Eshell with eat-eshell-mode. This allows Eshell to run full screen terminal applications.

(eat-eshell-mode 1)

Because Eat now handles full screen terminal applications, Eshell no longer has to run programs in a term buffer. Therefor, the eshell-visual-commands list can be unset.

(setq eshell-visual-commands nil)

Now, an application like top will run in the Eshell buffer without a separate term buffer having to be opened.

Atuin is a cross-shell utility that stores shell history in a SQLite database. The eshell-atuin package adds support for both reading from and writing to the history from Eshell.

(eshell-atuin-mode)

To read the history in Eshell, bind the <up> key to eshell-atuin-history, which opens the shell history in the minibuffer. Also unset the <down> key, which was bound to eshell-next-input for cycling through history in reverse:

(keymap-set eshell-hist-mode-map "<up>" 'eshell-atuin-history)
(keymap-unset eshell-hist-mode-map "<down>")

By default, eshell-atuin only shows commands that completed succesfully. To show all commands, change the eshell-atuin-search-options variable from ("--exit" "0") to nil:

(setq eshell-atuin-search-options nil)

Shell history completion is different from other kinds of completion for two reasons:

1. Other completion options are presented in a list from top to bottom, with the search prompt at the top. Because eshell-atuin-history is opened by pressing the <up> key and history is searched backward, the list is reversed by using vertico-reverse.
2. The command history shouldn’t be ordered, as that’s already handled by Atuin. Instead of ordering the list again, pass identity as the vertico-sort-function.

Using vertico-multiform, which is enabled through vertico-multiform-mode, set the above options specifically for the eshell-atuin-history function:

(vertico-multiform-mode 1)
(setq vertico-multiform-commands
      '((eshell-atuin-history
         reverse
         (vertico-sort-function . identity))))

I’m trying out org-node, a just-released alternative to org-roam, my current note-taking solution. Currently, this configuration uses both packages.

Beorg is an iOS app that takes Org mode to iOS. It includes a list of tasks named inbox that’s synced via iCloud, meaning it can be added to the agenda through org-agenda-files.

(setq org-agenda-files '("/Users/jeff/Library/Mobile\ Documents/iCloud\~com\~appsonthemove\~beorg/Documents/org/inbox.org"))

Org files can be can be exported to other formats, like HTML. Due to backwards compatibility constraints, however, the produced documents have an xhtml-strict doctype with syntax to match. Luckily, Org’s exporters are endlessly configurable, and include support for more modern configurations.

One of Org’s most impressive features is source code evalutation through its Library of Babel. Babel can both evaluate (run a source code block from within an Org document) and extract (take a source code block from an Org document and place it in another file) code.

Emacs automatically generates backups for files not stored in version control. Instead of storing them in the files’ directories, put everything in ~/.emacs.d/backups:

(setq backup-directory-alist `(("." . "~/.emacs.d/backups")))

With which-key, Emacs shows suggestions when pausing during an incomplete keypress, which is especially useful when trying to learn Emacs’ key bindings. By default, Emacs only shows the already-typed portion of the command, which doesn’t help to find the next key to press.

(which-key-mode 1)

By default, project.el only takes projects into account that have a .git directory. Use project-x to allow for projects that are not under version control, and projects nested within other projects.

Project-x is not on any of the pacakge managers, so this configuration assumes it’s installed manually for now. Also, this configuration re-sets project-find-functions to try project-x-try-local before project-try-vc to make it work for projects nested within directories under version control.

(project-x-mode 1)
(setq project-find-functions '(project-x-try-local project-try-vc))

With project-x enabled, Emacs will recognise directories with a .project file as project directories.³

Added in Emacs 29, pixel-scroll-precision-mode enables smooth scrolling instead of scrolling line by line.

(pixel-scroll-precision-mode 1)

Don’t use tabs for indentation.

(indent-tabs-mode 0)