Emacs on jneidel

Completion of hugo links in Emacs

web@jneidel.com (Jonathan Neidel) — Fri, 13 Feb 2026 00:00:00 +0000

When writing an article in hugo I want to link to previous articles I published. In markdown I can use:

[Hugo link completions](dev/hugo-links)

Which will resolve to either:

content/dev/hugo-links.md or
content/dev/hugo-links/index.md.

As my site grew, so did I grow tired of trying to remember or copy-pasting these links. Completion to the rescue. Fully integrated in your favorite editor: Emacs.

Hugo provides the completion candidates; the content files it knows about:

#! /bin/sh

# matches NAME/index.md files, excludes _index.md and NAME.md
cd $WEB_HOME
hugo list all --noBuildLock | tail -n+2 | cut -d, -f1 | grep -v "_index" | cut -d/ -f2- |
 rev | cut -d/ -f2- | rev

Multi-language script

This script supports both English (.md) and German (.de.md) content files.

#! /bin/sh

lang=$1

list_files() {
 # excludes _index.md and NAME.md files
 cd $WEB_HOME
 case $lang in
 en)
 hugo list all --noBuildLock | tail -n+2 | cut -d, -f1 | grep -v "_index" | cut -d/ -f2- |
 grep -v ".de.md" | rev | cut -d/ -f2- | rev
 break;;
 de)
 hugo list all --noBuildLock | tail -n+2 | cut -d, -f1 | grep -v "_index" | cut -d/ -f2- |
 grep ".de.md" | rev | cut -d/ -f2- | rev
 break;;
 -|both)
 hugo list all --noBuildLock | tail -n+2 | cut -d, -f1 | grep -v "_index" | cut -d/ -f2- |
 rev | cut -d/ -f2- | rev | sort | uniq
 break;;
 *)
 echo "Invalid language"
 exit 1
 esac
}

You can find an expanded version of the script in my dotfiles.

The elisp function for this completion can be as simple as:

(defun hugo-md-web-complete ()
 "Completion for links to my website."
 (interactive)
 (let* ((articles (shell-command-to-string "pick-hugo-article")) ; the shell script from above
 (link (completing-read "link: " (split-string articles "\n" t) nil t)))
 (insert (format "[%s](%s)" (read-string "link text: ") link))))
;; inserts: [link text](link)

Now, I use multiple languages and ox-hugo (hugo org-mode content files), so my solution needed to account for that.

Local hugo links are not very useful outside of the hugo directory. Instead the script should output a complete website link: “https://jneidel.com/…”

(defun jn/org-web-complete (lang)
 "Completion for links to my website."
 (let* ((articles (shell-command-to-string (format "pick-hugo-article %s" lang)))
 (link (completing-read "web: " (split-string articles "\n" t) nil t))
 (current-file (when buffer-file-name
 (file-truename buffer-file-name)))
 (is-editing-website (and
 current-file
 (string-prefix-p (substitute-in-file-name "$WEB_HOME") current-file)))
 (website-root (if (equal lang "de")
 "https://jneidel.de/"
 "https://jneidel.com/")))
 (if is-editing-website
 link
 (concat website-root link))))

(defun jn/org-web-de-complete ()
 (jn/org-web-complete "de"))
(defun jn/org-web-en-complete ()
 (jn/org-web-complete "en"))

(with-eval-after-load 'org
 (org-link-set-parameters "de" :complete #'jn/org-web-de-complete)
 (org-link-set-parameters "en" :complete #'jn/org-web-en-complete))

(Latest version in my dotemacs.)

At the end I am registering the completions to be called through org-insert-link using de: or en:. This integration is great. No new keybinding are needed and I can use it through my full-featured org-insert-link-dwim.

That’s it :) Have a great day!

References #

See this post for an alternative approach using read-file-name

Guide to Modern Emacs Completion: vertico, corfu & friends

web@jneidel.com (Jonathan Neidel) — Wed, 04 Feb 2026 00:00:00 +0000

A good completion system can make navigating an app like walking over clouds. A terrible one is like walking barefoot over spiky stones. Every step of the way will hurt. Unfortunately Emacs’ defaults make for quite the thorny walk. Fortunately that is very fixable.

This guide will explain the necessary concepts and go through all of my configuration for the relevant packages of the “minad stack” (vertico, consult, corfu & friends) and some more. The setup is tailored toward modern sensibilities (fuzzy finding, LSP completions) and assumes you can tweak an elisp configuration to your needs.

Types of Emacs completion #

The most important thing to understand about auto-completion in Emacs is that there are two kinds:

Completing-read: this is your minibuffer (M-x), find-file, and all those other functions that prompt you at the bottom of the screen.
Completion-at-point (and completion-in-region): these complete text inside of a buffer (usually assigned to TAB.)

With that understood, suddenly those cryptic package headlines make more sense:

“🔍 consult.el - Consulting completing-read”
“🏝️ corfu.el - COmpletion in Region FUnction”

Completion styles #

completion-styles define the matching algorithms used. After years of fzf (ab)use I instinctively use spaces to separate queries for completing-read prompt (e.g. “a b”.) This is supported by orderless. Default styles plus orderless and I’m content to the point that I had not felt the need to fiddle with it.

Configuration code for completion styles + orderless

completion-styles checks for matches in order. So go from strictest to losest.

(use-package orderless
 :custom
 (orderless-matching-styles '(orderless-prefixes))
 (completion-ignore-case t)
 :config
 (set-face-attribute 'orderless-match-face-0 nil
 :foreground "#d70000")
 (set-face-attribute 'orderless-match-face-1 nil
 :foreground "#005fd7")
 (set-face-attribute 'orderless-match-face-2 nil
 :foreground "#007f3a")
 (set-face-attribute 'orderless-match-face-3 nil
 :foreground "#d700d7"))
 
(setq completion-styles '(basic substring initials orderless)
 completion-category-overrides '((file (styles basic partial-completion))))

Completing-read #

I consider the configuration of the minibuffer UI critical In my first 6 months of Emacs, the god-awful user experience of fido-mode and find-file really made me not want to use Emacs. I was used to insanely fast fuzzy finders everywhere. Emacs’ default completing-read felt like from a different century (which it is.)

Vertico + marginalia goodness.

Vertico is a great improvement. Marginalia adds context. Just that already makes for a much improved experience. Even if you don’t like the vertical list style, vertico got you covered (visual demo of the different styles by Karthink.)

Configuration code for vertico and marginalia

(use-package vertico
 :demand t
 :bind (:map minibuffer-local-map
 ("<tab>" . vertico-next)
 ("<backtab>" . vertico-previous))
 :custom
 (vertico-cycle t) ; C-n at the bottom of the list loops around to the top
 :config
 (vertico-mode t)
 (vertico-reverse-mode t)
 
 ; Verticos highlight font was clashing with my completion part, so adjust the font faces
 (set-face-attribute 'vertico-current nil
 :weight 'bold
 :inverse-video nil
 :foreground "#ffbf00"
 :background "grey20")
 (set-face-attribute 'completions-common-part nil
 :weight 'bold
 :foreground "#d70000")
 (set-face-attribute 'minibuffer-prompt nil
 :foreground "#ffbf00")
 )


(use-package marginalia
 :custom
 (marginalia-align 'right)
 :config
 (marginalia-mode t)

 (set-face-attribute 'marginalia-documentation nil
 :inherit nil
 :slant 'italic
 :foreground "grey43")
 (set-face-attribute 'marginalia-key nil
 :foreground "#00ff5f")
 )

For whatever reason my vertico has some indicators in the right fringe and this is the only way (I found) to get rid of them:

(defun jn/vertico-hide-fringe-and-truncation-indicators ()
 (when vertico-mode
 (setq-local fringe-indicator-alist
 (let ((a (copy-alist fringe-indicator-alist)))
 (setf (cdr (assq 'continuation a)) nil)
 (setf (cdr (assq 'truncation a)) nil)
 a))
 (setq-local truncation-string "")))
(add-hook 'minibuffer-setup-hook
 #'jn/vertico-hide-fringe-and-truncation-indicators)

Many functions will benefit from a nice completing-read UI setup.

Fuzzy file search #

For 98% of my file search I use a fuzzy finder. It gets me where I want to go quicker than traversing the directory tree. For this I use affe.¹

Affe search. Permissions, sizes and dates are courtesy of marginalia.

affe-find only searches the current directory (or project.) To use it for the whole system some customization is needed. There is a reason that affe-find from the home directory is not offered by the package author. Without some cleanup you will be overwhelmed by irrelevant matches. Though with ripgrep as our blazing fast file finder we can exclude matches like this:

pass a --glob flag to the command, with a pattern to ignore
create a .rgignore with a list of files in any directory root

With that, the number of matched files gets reduced to an amount where search feels instant.

I have these different bindings to invoke affe (ordered by frequency of use):

Search for a file on the system
Search for a file in the current project
Search for a directory on the system

Configuration code for affe

For one-off exclusions I use local .rgignore files (e.g. in ~ and ~/.config.) For file type or repeated directory exclusions I use ignore flags.

(defvar rg-ignore-flags
 "-g \"!*.mp3\" -g \"!*.jpg\" -g \"!*.JPG\" -g \"!*.jpeg\" -g \"!*.png\" \
 -g \"!*.mkv\" -g \"!*.mp4\" -g \"!*.avi\" -g \"!*.zip\" -g \"!*.ddl\" \
 -g \"!*.ods\" -g \"!*.xlsx\" -g \"!*.m3u\" -g \"!*.url\" -g \"!*.aac\" \
 -g \"!*.mpc\" -g \"!*.sql\" -g \"!*.ydb\" -g \"!dist/\" \
 -g \"!.git/\" -g \"!git/*\" -g \"!node_modules/\" -g \"!*cache/\" \
 -g \"!.cache\" -g \"!vendor/\" \
 -g \"!.pki/\" -g \"!.local/share/*/\" \
 -g \"!coverage\" -g \"!build/\" -g \"!var/\" -g \"!npm/\" \
 -g \"!Library/\" -g \"!.DS_Store\" -g \"!.stfolder\""
 "Exclusion flags for usage with ripgrep commands.")
(defvar rg-find-files-command
 (format "rg -L --ignore --hidden --files --color=never %s" rg-ignore-flags)
 "Command for finding files with ripgrep.")
(defvar rg-find-directories-command
 (format "rg-dir -L --ignore --hidden --color=never %s" rg-ignore-flags)
 "Command for finding directories with ripgrep.")

(defun affe-find-file (&optional dir) (interactive) ; default dir is cwd
 (setq affe-find-command rg-find-files-command)
 (affe-find dir))
(defun affe-find-directory (&optional dir) (interactive) ; default dir is cwd
 (setq affe-find-command rg-find-directories-command)
 (affe-find dir))
(defun affe-find-file-home () (interactive)
 (affe-find-file (substitute-in-file-name "$HOME")))
(defun affe-find-directory-home () (interactive)
 (affe-find-directory (substitute-in-file-name "$HOME")))

(use-package affe
 :bind (("H-f" . affe-find-file-home)
 ("H-M-f" . affe-find-file)
 ("H-s" . affe-find-directory-home))
 :custom
 (affe-count 5000))

If you want to have the H (Hyper) modifier, here is how I set it up on Linux.

Improved find-file #

I do use find-file to initiate tramp connections. find-files default TAB and RET behaviors leave a lot to be desired. Might be a skill issue, but I found myself always writing the path by hand for those deeply nested files.

vertico-directory gives me exactly the intuitive navigation I expect:

(use-package vertico-directory
 :after vertico
 :ensure nil
 :bind (:map vertico-map
 ("RET" . vertico-directory-enter)
 ("DEL" . vertico-directory-delete-char)
 ("M-DEL" . vertico-directory-delete-word))
 :hook (rfn-eshadow-update-overlay . vertico-directory-tidy))

Consult for better functions #

Consult offers a host of useful interactive functions built on completing-read. Many of them are superior replacements for built-in functions.

Fuzzy finder to select a line to jump to (with context preview.)

Configuration code for consult

(use-package consult
 :bind (;; new functionality
 ("M-g l" . consult-line)
 ("M-g m" . consult-mark)
 ("H-r" . consult-ripgrep)
 ;; replace built-in functions with superior versions
 ("M-y" . consult-yank-pop)
 ("C-x 4 b" . consult-buffer-other-window)
 ("C-x t b" . consult-buffer-other-tab)
 ([remap Info-search] . consult-info)
 ([remap list-buffers] . ibuffer)
 ))

If you want to have the H (Hyper) modifier, here is how I set it up on Linux.

The consult interface I rely on most heavily is consult-buffer. It can be modded to achieve this:

What are we looking at? We got multiple sections “Perspective Buffer”, “Special Buffer”, “File” and “Bookmark” off-screen. So, we get filtering by perspective workspace, access to recent files and bookmarks. Already great. The “Special Buffer” is where the real flexibility of this system comes in.

I use popper to relegate help buffers, compilation output and those sorts of buffers to a separate “popup stack”. Some get hidden completely and the rest don’t disturb my layout and are easily hidden. All well and good. A popup buffer, even a suppressed one, will still show up at the top of your buffer list, as the most recently accessed. Distracting clutter. Well, consult-buffer allows you to customize the sections. With this I segregated popup buffer off into their own section. Separate and not equal.

Configuration code for consult-buffer + popper + perspective

(setq jn/secondary-buffer-regexes ; alist in popper format
 '("\\*Messages\\*"
 ("\\*Warnings\\*" . hide)
 "\\*Man.*"
 "\\*Help.*"
 "\\*helpful.*"
 ("\\*Compile.*" . hide)
 ("\\*Org-Babel Error Output\\*" . hide)
 ("\\*Async Shell Command\\*" . hide)
 "\\*slime.*"
 ("\\*inferior-lisp\\*" . hide)
 ("\\*sldb.*" . hide)
 "\\*Backtrace\\*"
 "\\*org-search\\*"
 "\\* Merriam-Webster"
 "\\*Flymake diagnostics"))
 
(use-package popper
 :custom
 (popper-reference-buffers jn/secondary-buffer-regexes)
 (popper-mode-line '(:eval ""))
 (popper-window-height 12) ; default function maxes out at 33%, which seems too small to me
 :defer nil
 :config
 (popper-mode +1)
 
 (defhydra popper-hydra (:hint nil)
 "
_n_ext _p_revious promo_t_e/demo_t_e show/_u_nshow"
 ("n" popper-cycle)
 ("p" popper-cycle-backwards)
 ("t" popper-toggle-type)
 ("u" popper-toggle)
 ("q" nil nil)
 ("C-g" nil nil)
 ("ESC" nil nil))
 :bind (("H-u" . popper-toggle) ; quick show/hide popups
 ("H-U" . popper-hydra/body)))
 
(defun jn/strip-alists (buffers)
 (mapcar
 (lambda (item)
 (if (consp item)
 (car item)
 item))
 buffers))

(setq jn/secondary-buffer-pure-regexes (jn/strip-alists jn/secondary-buffer-regexes)) ; normalize into regexes

(use-package consult
 :custom
 (popper-group-function #'popper-group-by-perspective)
 :config
 (consult-customize consult-source-buffer :hidden t :default nil) ; disable
 (consult-customize persp-consult-source
 :name "Perspective Buffer"
 :default t
 :items '(lambda () (consult--buffer-query
 :sort 'visibility
 :as #'buffer-name
 :predicate (lambda (buf) (persp-is-current-buffer buf t))
 :exclude (append jn/secondary-buffer-pure-regexes '("^ \\*"))))) ; hidden buffers like minibuffer
 
 (defvar consult-special-buffer
 `( :name "Special Buffer"
 :default nil
 :face consult-buffer
 :category buffer
 :history buffer-name-history
 :state ,#'consult--buffer-state
 :items ,(lambda () (consult--buffer-query
 :sort 'visibility
 :as #'buffer-name
 :predicate (lambda (buf) (persp-is-current-buffer buf t))
 :include jn/secondary-buffer-pure-regexes
 ))))

 (add-to-list 'consult-buffer-sources consult-special-buffer)
 (add-to-list 'consult-buffer-sources persp-consult-source)
 
 (consult-customize consult-source-bookmark
 :enabled (lambda () (equal (persp-current-name) "main")))
 (consult-customize consult-source-recent-file
 :enabled (lambda () (equal (persp-current-name) "main")))
)

In your own scripts #

completing-read can be powerfully used in your own elisp scripts, as demonstrated by Álvaro Ramírez. I use it all the time. Here to pick a type from a pool of candidates:

(completing-read "What type? " '("Project" "Design" "Resource") nil t)

You can reach for gum if you want a similarly nice experience in your shell scripts.

In-buffer completion #

I use corfu as my completion-at-point UI. I would recommend it over company, because corfu uses the built-in completion API (company implements it’s own API incompatible to Emacs’.) Even if a you depend on a package that only provides a company-backend, corfu got you covered.

Since corfu enhances the built-in API, it will just work out of the box for modes that bring their own capfs (completion at point functions.) Like account completion in ledger-mode:

Completion at point with corfu. (Error overlay by flymake-hledger.)

Configuration code for corfu

;; TAB key: fix indentation if needed, otherwise perform completion
(setq tab-always-indent 'complete)

(use-package corfu
 :hook (after-init . global-corfu-mode)
 :custom
 (corfu-cycle t) ; cycle around to first entry after reaching the last
 (corfu-preview-current nil) ; don't expand text at point until I press return
 (corfu-min-width 20)
 (corfu-on-exact-match 'insert) ; complete if there is only a single candidate
 (corfu-quit-no-match t)
 (corfu-quit-at-boundary t)
 :config
 (setq corfu-popupinfo-delay '(1.25 . 0.5))
 (corfu-popupinfo-mode 1) ; shows documentation next to completions

 ;; sort by input history
 (with-eval-after-load 'savehist
 (corfu-history-mode 1)
 (add-to-list 'savehist-additional-variables 'corfu-history))
 )

Add more capfs #

With cape we can easily add further completion sources (completion at point functions) to be used by corfu. I use: words in the buffer and file system paths.

Configuration code for cape

(use-package cape
 :defer 1
 :config
 (add-hook 'completion-at-point-functions #'cape-dabbrev 20) ; words from buffer
 (add-hook 'completion-at-point-functions #'cape-file 20))

Code completion #

Thanks to language servers (see LSP explainer), nice auto-completion for code is now easy to achieve consistently.

Completion on a string in JavaScript.

The icons in the UI are added by kind-icon.

Configuration code for eglot and kind-icon

(use-package eglot
 :ensure nil
 :functions (eglot-ensure)
 :commands (eglot)
 :hook (prog-mode . eglot-ensure)
 :config
 (set-face-attribute 'eglot-highlight-symbol-face nil
 :foreground "#ffd700"
 :underline t)
 )

(use-package kind-icon
 :after corfu
 :config
 (add-to-list 'corfu-margin-formatters #'kind-icon-margin-formatter))

;; fix overly large icons (https://github.com/jdtsmith/kind-icon/issues/22)
(setq kind-icon-default-style
 '(:padding -1 :stroke 0 :margin 0 :radius 0 :height 0.4 :scale 1))

GitHub Copilot #

GitHub Copilot can be used as an evolved auto-completion. It not only completes the “word” at hand, but “finishes the whole thought.” Often it does what you want. Faster than you could ever type it.

If you got free access, it is worth to trying, to see if it fits your development style. That is if you are a are a student or your employer pays for it.

For me was not a good fit. I always turned it off and never turned it on again. I felt it constantly interrupted my thought. Imagine you get a proposal before you even had time to think about what the piece of code should do. You have no basis to evaluate it on, since you don’t know what you want. And at that point the proposal influences what you think is best. I much prefer the agentic coding loop: I think, write it down as specs/idea, pass it to the agent and only, have it work and only then see the generated code.

Conclusions #

Hopefully this guide gave you all the hints to successfully set up a feature-complete completions system that meets your needs. Most of the linked packages have great documentation, if you should run into problems.

For more from me, feel free to subscribe to one of the RSS feeds.
For corrections or suggestions on this article, please email me🙂

Have a great day!

References #

This is an entry for the Emacs Carnival. See other contributions on the topic of completion.

My complete literate config
Protesilaos literate config (completions section)

I tried fzf.el, but it does not play along well with the rest of Emacs. Affe on the other hand integrates seamlessly. ↩︎

Complete Email Setup with isync, notmuch and friends

web@jneidel.com (Jonathan Neidel) — Mon, 03 Nov 2025 00:00:00 +0000

This is a complete guide to my email setup. I wanted to provide and end-to-end experience showing everything and every step involved. That means the configuration at my hosting and DNS providers, mail sending, syncing and indexing tools and the user interface. This is not for a single mailbox, but sending and receiving from any address on multiple domains.

All of my tool/provider choices in this guide can be replaced once you understand the role that particular part fulfills.

Hosting providers #

These providers make sure mail is collectable from a mailbox and that it can be sent.

Domains #

I use namecheap. Good prices and easy enough user interface.

I have the following domains with them:

jneidel.com
jneidel.de
neidel.xyz

Mailserver #

I use uberspace. They got great docs and a flexible pricing model that, though a model of solidary, provides hosting even to those who would be otherwise unable to afford it. I have been with them for many years.

With the command uberspace mail domain add neidel.xyz I can add a mail domain:

The mailservers configuration has been adapted.
Now you can use the following records for your DNS:

neidel.xyz. IN MX 0 pizarro.uberspace.de.
neidel.xyz. IN TXT "v=spf1 include:spf.uberspace.de ~all"
uberspace._domainkey.neidel.xyz. IN TXT "v=DKIM1;t=s;n=core;p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAonmVoIli72aSHhW9LyMrnrkcYfCddeqHyQkK8aIkpBDhJObkbX+9b+p+V/+dJz86IUd3zi1Flj41Wt3TqS8/WQg2NVUKsAJMUSrO00gz+3Gqw0e0cT0BJ4YXSFr8kzwro79A9rh6ZJta6/E4xg+7DgQcIFh8Qy1XcLV2wPimQDQRWAAFMO5nXqQea9Vuvid2n2SoCTE9BXhNg4TwDRiZZTxSzTigU7iDSTBuS75wH0XtOBIMpc0OeK+2Jz3E/33/0V28rCGcPLX2FPSXvfDPY/9VmQzc0jDW8mz4SJ4/bS6Gj8qWtVlVXEEVZ3Fa2aWQ1W8vJrAelo/31dq9kcd+aQIDAQAB"

The output tell me what to add in namecheap in the domain under “Advanced DNS”:

This configuration includes DKIM signatures and SPF headers. Without a valid DKIM signature emails sent to e.g. Gmail addresses will be blocked. The validity of these records are tested later.

Mailboxes #

To gain access to mail delivered to a configured domain we need to create a mailbox:

uberspace mail user add jneidel

I want mail sent to any address of my domains to go into the same mailbox/maildir, so I set it up as a catch-all:

uberspace mail catchall set jneidel

(See the uberspace docs.)

Mail utilities #

These tools are necessary to secure, retrieve, send and index mail.

GPG #

To securely store my mail password I use pass, which encrypts the passwords with my GPG key.

You can create your own key, ideally with a secure password generated with the dice method:

gpg --full-generate-key

Install the relevant programs for the usage:

yay -S pass pinentry

Add the mail server password to pass:

pass add jneidel@jneidel.de

Configure your favorite pin entry program in ~/.config/gnupg/gpg-agent.conf:

pinentry-program /bin/pinentry-gtk
default-cache-ttl 43200 # 12h, refreshes with each use of the key
max-cache-ttl 259200  # 3d

Do restart the gpg-agent after changes (find the command in htop, kill the process and execute the command again.)

(Here is some more information about pin entry.)

Retrival and sync #

We need to configure a program to download email from the IMAP server for offline use. This program will also sync any changes we do back to the server.

I use mbsync, which is part of isync.

yay -S isync

In ~/.config/isyncrc I have:

IMAPStore jneidel@jneidel.de-remote
Host pizarro.uberspace.de
Port 993
User jneidel@jneidel.de
PassCmd "pass jneidel@jneidel.de"
AuthMechs LOGIN
TLSType IMAPS
CertificateFile /etc/ssl/certs/ca-certificates.crt

MaildirStore jneidel@jneidel.de-local
Subfolders Verbatim
Path /home/jneidel/.local/share/mail/jneidel@jneidel.de/
Inbox /home/jneidel/.local/share/mail/jneidel@jneidel.de/INBOX

Channel jneidel@jneidel.de
Expunge Both
Far :jneidel@jneidel.de-remote:
Near :jneidel@jneidel.de-local:
Patterns * !"*virtual*"
Create Both
SyncState *
MaxMessages 0
ExpireUnread no

The host is the one from the domain setup.
The port value can be found in the uberspace docs.
The password was stored in pass in the previous step.
I designated ~/.local/share/mail as my local maildir.

I use ~/scripts/mail/mailsync invoking mbsync to synchronize my mail:

#!/bin/sh

MAILSYNC_MUTE=true

if [ "$1" = "--help" ] || [ "$1" = "-h" ] || [ "$1" = "help" ]; then
 cat <<EOF
$ mailsync [ACCOUNT]
Sync mail and index it.

Run it:
- via goimapnotify (server has received new mail hook)
- via cron (timer)

Source: https://github.com/LukeSmithxyz/mutt-wizard
Changes: pop removed, notifications disabled, .config/neomvim and .config/isync as config dirs.

Parameters:
 [\$1]: account to sync, by default syncs all

Example:
 $ mailsync
 $ mailsync jneidel@jneidel.com
EOF
 exit
fi

hash mbsync notmuch || exit 127

# There are many arbitrary and ugly features in this script because it is
# inherently difficult to pass environmental variables to cronjobs and other
# issues. It also should at least be compatible with Linux (and maybe BSD) with
# Xorg and MacOS as well.

# Run only if user logged in (prevent cron errors)
pgrep -u "${USER:=$LOGNAME}" >/dev/null || { echo "$USER not logged in; sync will not run."; exit ;}
# Run only if not already running in other instance
pgrep mbsync >/dev/null && { echo "mbsync is already running."; exit ;}

# First, we have to get the right variables for the mbsync file, the pass
# archive, notmuch and the GPG home. This is done by searching common profile
# files for variable assignments. This is ugly, but there are few options that
# will work on the maximum number of machines.
eval "$(grep -h -- \
 "^\s*\(export \)\?\(MBSYNCRC\|PASSWORD_STORE_DIR\|NOTMUCH_CONFIG\|GNUPGHOME\)=" \
 "$HOME/.profile" "$HOME/.bash_profile" "$HOME/.zprofile" "$HOME/.config/zsh/.zprofile" "$HOME/.zshenv" \
 "$HOME/.config/zsh/.zshenv" "$HOME/.bashrc" "$HOME/.zshrc" "$HOME/.config/zsh/.zshrc" \
 "$HOME/.pam_environment" 2>/dev/null)"

# export GPG_TTY="$(tty)"

[ -n "$MBSYNCRC" ] && alias mbsync="mbsync -c $MBSYNCRC" || MBSYNCRC=$HOME/.config/isyncrc

lastrun="${XDG_CONFIG_HOME:-$HOME/.config}/neomutt/.mailsynclastrun"

# Settings are different for MacOS (Darwin) systems.
case "$(uname)" in
 Darwin)
 notify() { osascript -e "display notification \"$2 in $1\" with title \"You've got Mail\" subtitle \"Account: $account\"" && sleep 2 ;}
 ;;
 *)
 case "$(readlink -f /sbin/init)" in
 *systemd*|*openrc*) export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$(id -u)/bus ;;
 esac
 # remember if a display server is running since `ps` doesn't always contain a display
 pgrepoutput="$(pgrep -a X\(org\|wayland\))"
 displays="$(echo "$pgrepoutput" | grep -wo "[0-9]*:[0-9]\+" | sort -u)"
 notify() { [ -n "$pgrepoutput" ] && for x in ${displays:-0:}; do
 export DISPLAY=$x
 notify-send --app-name="mutt-wizard" "New mail!" "📬 $2 new mail(s) in \`$1\` account."
 done ;}
 ;;
esac

# Check account for new mail. Notify if there is new content.
syncandnotify() {
 acc="$(echo "$account" | sed "s/.*\///")"
 if [ -z "$opts" ]; then mbsync "$acc"; else mbsync "$opts" "$acc"; fi
 new=$(find\
 "$HOME/.local/share/mail/$acc/INBOX/new/"\
 "$HOME/.local/share/mail/$acc/Inbox/new/"\
 "$HOME/.local/share/mail/$acc/inbox/new/"\
 "$HOME/.local/share/mail/$acc/INBOX/cur/"\
 "$HOME/.local/share/mail/$acc/Inbox/cur/"\
 "$HOME/.local/share/mail/$acc/inbox/cur/"\
 -type f -newer "$lastrun" 2> /dev/null)
 newcount=$(echo "$new" | sed '/^\s*$/d' | wc -l)
 case 1 in
 $((newcount > 0)) ) [ -z "$MAILSYNC_MUTE" ] && notify "$acc" "$newcount" ;;
 esac
}

# Sync accounts passed as argument or all.
if [ "$#" -eq "0" ]; then
 accounts="$(awk '/^Channel/ {print $2}' "$MBSYNCRC")"
else
 for arg in "$@"; do
 [ "${arg%${arg#?}}" = '-' ] && opts="${opts:+${opts} }${arg}" && shift 1
 done
 accounts=$*
fi

# Parallelize multiple accounts
for account in $accounts; do
 syncandnotify &
done

wait

notmuch new
afew --tag --new
afew --move-mails --all

# Create a touch file that indicates the time of the last run of mailsync
touch "$lastrun"

This script could be simpler, but for now it just works. It was adapted from mutt-wizard.

The script could be invoke at a regular interval through cron, but we can do it even better than that.

Sync on IMAP change #

Why not let the IMAP server inform us of new mail and only sync then? goimapnotify does exactly that.

yay -S goimapnotify

In ~/.config/imapnotify/jneidel@jneidel.de we tell it what to do:

{
"host": "pizarro.uberspace.de",
"port": 993,
"tls": true,
"tlsOptions": {
"rejectUnauthorized": false
},
"username": "jneidel@jneidel.de",
"password": "",
"passwordCmd": "pass jneidel@jneidel.de",
"onNewMail": "/home/jneidel/scripts/mail/mailsync",
"onNewMailPost": "",
"boxes": [ "INBOX" ]
}

To activate run this on startup (I have it in my ~/.xinitrc):

goimapnotify -conf ~/.config/imapnotify/jneidel.de.yaml >/dev/null 2>&1 &

Sending mail #

For sending mail (SMTP) I use msmtp:

yay -S msmtp

It is configured in ~/.config/msmtp/config:

account jneidel@jneidel.de
host pizarro.uberspace.de
port 465
from jneidel@jneidel.de
user jneidel@jneidel.de
passwordeval "pass jneidel@jneidel.de"
auth on
tls on
tls_trust_file	/etc/ssl/certs/ca-certificates.crt
logfile /home/jneidel/.local/share/msmtp/jneidel.de.log
tls_starttls off

account default : jneidel@jneidel.de

The account default acts like a catch-all for sending, so I don’t have to configure each sender address individually. This way I can respond to a mail I received on “abc@jneidel.com” from “abc@jneidel.com”, not just from “jneidel@jneidel.de”.

The SMTP port was also found in the docs.

Mail indexing #

I use notmuch to index my email. It makes it very quick to search. Since I use notmuch as my mail client this is required for me, but optional otherwise.

yay -S notmuch

Configuration is handled in this redefined config location: export NOTMUCH_CONFIG=~/.config/notmuch-config:

[database]
path=/home/jneidel/.local/share/mail
[user]
name=Jonathan Neidel
primary_email=jneidel@jneidel.de
other_email=jneidel@jneidel.com;j@neidel.xyz
[new]
tags=unread;inbox;
ignore=.mbsyncstate;.uidvalidity
[search]
exclude_tags=deleted;spam;
[maildir]
synchronize_flags=true
[crypto]
gpg_path=gpg

Notmuch does not provide tagging automation or mail moving. For that I use afew.

yay -S afew

Configured in ~/.config/afew/config:

[Filter.1]
message = Remove new tag everywhere but INBOX folder
query = NOT folder:jneidel@jneidel.de/INBOX
tags = -unread;-inbox

[Filter.2]
message = Hide jobdirecto mails
query = folder:jneidel@jneidel.de/INBOX AND to:wilfredocasas100@gmail.com
tags = -unread;+spam;-inbox

[Filter.3]
message = Remove Lidl Pay confirmations
query = subject:Abbuchungsankündigung AND from:lidlpay@lidl.de
tags = +trash;-unread;-inbox

[Filter.4]
message = Hide bellicon
query = from:affiliate@bellicon.com
tags = +spam;-unread;-inbox

[Filter.5]
message = Remove IB trade confirmations
query = subject:Trade Confirmation Flex AND from:donotreply@interactivebrokers.com
tags = +trash;-unread;-inbox

[Filter.6]
message = Move Telekom invoices
query = subject:'Telekom Festnetz-Rechnung' AND from:rechnungonline@telekom.de
tags = +invoice;-unread;-inbox

[Filter.7]
message = Blutspende
query = to:spenderservice@jneidel.com
tags = +trash;-unread;-inbox

[Filter.8]
message = Tag mail in sent dir as sent
query = folder:jneidel@jneidel.com/Sent OR folder:jneidel@jneidel.de/Sent
tags = +sent;-unread;-inbox

[Filter.9]
message = Tag mail in archive dir as archieved
query = folder:jneidel@jneidel.com/archive OR folder:jneidel@jneidel.de/archive
tags = +archived;-unread;-inbox

[Filter.10]
message = Tag mail in invoices dir as invoice
query = folder:jneidel@jneidel.com/invoices OR folder:jneidel@jneidel.de/invoices
tags = +invoice;-unread;-inbox

[ArchiveSentMailsFilter]
sent_tag = sent

[MailMover]
folders = jneidel@jneidel.de/INBOX jneidel@jneidel.de/archive jneidel@jneidel.de/spam jneidel@jneidel.de/invoices
rename = True

jneidel@jneidel.de/INBOX = 'tag:spam':jneidel@jneidel.de/spam 'tag:trash':jneidel@jneidel.de/Trash 'tag:invoice':jneidel@jneidel.de/invoices 'tag:archived':jneidel@jneidel.de/archive
jneidel@jneidel.de/spam = 'tag:trash':jneidel@jneidel.de/Trash
jneidel@jneidel.de/archive = 'tag:trash':jneidel@jneidel.de/Trash
jneidel@jneidel.de/invoices = 'tag:trash':jneidel@jneidel.de/Trash

# Test queries with notmuch search

The Filters at the top are used to get mail that I don’t want to see out of my inbox. Recurring invoices (Telekom) and unsubscribable spam (jobdirecto, bellicon) also get tagged respectively.

I use the tags “spam, trash, archived, invoice” and these correspond to directories in my maildir: “spam, Trash, archive, invoices”. The MailMover at the bottom is responsible for moving mail according to the tags.

Mail client #

I use the notmuch Emacs client. The Emacs package was already installed alongside the system package:

(use-package notmuch
 :ensure nil
 :defer t
 :commands (notmuch notmuch-mua-new-mail))

In the previous section I already configured notmuch and autotagging with afew. That means all that is left to configure is the Emacs interface and a little wiring for persona and msmtp:

(setq user-mail-address "jneidel@jneidel.com"
 user-full-name "Jonathan Neidel"
 notmuch-identities '("Jonathan Neidel <jneidel@jneidel.com>"))

(setq send-mail-function 'sendmail-send-it
 message-send-mail-function 'sendmail-send-it
 sendmail-program "/bin/msmtp"

 mail-specify-envelope-from t
 message-sendmail-envelope-from 'header
 mail-envelope-from 'header)

(setq notmuch-fcc-dirs "jneidel@jneidel.de/Sent"
 notmuch-draft-folder "jneidel@jneidel.de/Drafts")
;; paths are relative to notmuch index base root aka the maildir at ~/.local/share/mail

I have replaced the default notmuch hello screen with a collection of queries easily accessible through keybindings. A lot of my this notmuch config this was inspired by Prots Emacs configuration.

The notmuch-hello screen after the below configuration

(use-package notmuch
 :defer t
 :config
 (setq notmuch-show-logo nil
 notmuch-column-control 1.0
 notmuch-hello-auto-refresh t
 notmuch-hello-thousands-separator ""
 notmuch-hello-sections '(notmuch-hello-insert-saved-searches)
 notmuch-search-oldest-first nil)

 (setq notmuch-show-empty-saved-searches t)
 (setq notmuch-saved-searches
 `(( :name "📥 inbox"
 :query "tag:inbox"
 :sort-order newest-first
 :key ,(kbd "i"))
 ( :name "👀 all unread (inbox)"
 :query "tag:unread and tag:inbox"
 :sort-order newest-first
 :key ,(kbd "u"))
 ( :name "✏️ drafts"
 :query "tag:draft and not:tag:trash"
 :sort-order newest-first
 :key ,(kbd "d"))
 ( :name "🗃️ archive"
 :query "tag:archived"
 :sort-order newest-first
 :key ,(kbd "a"))
 ( :name "🛒 invoices"
 :query "tag:invoice"
 :sort-order newest-first
 :key ,(kbd "n"))
 ( :name "📨 sent"
 :query "tag:sent"
 :sort-order newest-first
 :key ,(kbd "s"))
 ( :name "🪓 spam"
 :query "tag:spam and not:tag:trash"
 :sort-order newest-first
 :key ,(kbd "m"))
 ( :name "🗑️ trash"
 :query "tag:trash"
 :sort-order newest-first
 :key ,(kbd "t"))
 ( :name "🌍 all"
 :query "not:tag:trash and not:tag:spam"
 :sort-order newest-first
 :key ,(kbd "A"))
 ))

 (keymap-set notmuch-common-keymap (kbd "g") #'notmuch-jump-search)
 )

The interface shows each emails tags. To make these less verbose and easy to parse I turn them into emoji. This snippet configures everthing around tags.

(use-package notmuch
 :defer t
 :config
 (setq notmuch-archive-tags '("+archived")
 notmuch-message-replied-tags '("+replied")
 notmuch-message-forwarded-tags '("+forwarded")
 notmuch-show-mark-read-tags '("-unread")
 notmuch-draft-tags '("+draft")
 notmuch-draft-save-plaintext 'ask)

 (setq notmuch-tag-formats
 '(("unread" "👀")
 ("attachment" "📎")
 ("signed" "🔑")
 ("encrypted" "🔒")
 ("replied" "💬")
 ("forwarded" "⏩")
 ("sent" "📨")
 ("inbox" "📥")
 ("spam" "🪓")
 ("invoice" "🛒")
 ("archived" "🗃️")
 ("draft" "✏️")
 ("trash" "🗑️")
 ("lists" "📜lists")
 ("flag" (propertize tag 'face 'notmuch-tag-flagged)
 (concat tag "🚩")))
 notmuch-tag-deleted-formats
 '(("unread" (notmuch-apply-face bare-tag 'notmuch-tag-deleted)
 (concat "👀" tag))
 (".*" (notmuch-apply-face tag 'notmuch-tag-deleted)
 (concat "🚫" tag)))
 notmuch-tag-added-formats
 '(("del" (notmuch-apply-face tag 'notmuch-tag-added)
 (concat "💥" tag))
 (".*" (notmuch-apply-face tag 'notmuch-tag-added)
 (concat "🏷️" tag))))

 (setq notmuch-tagging-keys
 `((,(kbd "d") ("+trash" "-inbox" "-unread") "🗑️ Mark for deletion")
 (,(kbd "s") ("+spam" "-inbox" "-unread") "🪓 Mark as spam")
 (,(kbd "f") ("+flag") "🚩 Flag as important")
 (,(kbd "i") ("+invoice" "-inbox" "-unread") "🛒 Mark as invoice")
 (,(kbd "a") ("+archived" "-inbox" "-unread") "🗃️ Mark as archived")
 (,(kbd "r") ("-unread") "👀 Mark as read")
 (,(kbd "u") ("+unread") "👀 Mark as unread")))

 (keymap-set notmuch-common-keymap (kbd "u") #'notmuch-tag-undo)

 (defun notmuch-search-mode-delete-goto-next ()
 "Tag current mail as trash and move to the next."
 (interactive)
 (notmuch-search-tag '("+trash" "-unread" "-inbox"))
 (forward-line)
 )
 (defun notmuch-show-mode-delete-goto-next ()
 "Tag current mail as trash and move to the next."
 (interactive)
 (notmuch-show-tag '("+trash" "-unread" "-inbox"))
 (notmuch-show-next-message t)
 (notmuch-search-show-thread)
 )

 (keymap-set notmuch-search-mode-map (kbd "d") #'notmuch-search-mode-delete-goto-next)
 (keymap-set notmuch-show-mode-map (kbd "d") #'notmuch-show-mode-delete-goto-next)
 )

Often times I want to open a HTML email in the browser. That needs an entry in ~/.mailcap:

text/html; brave %s; nametemplate=%s.html

I added a wrapper around the native notmuch-show-view-part so it does what I want from opening email in the browser:

(defun notmuch-show-mode-open-html ()
 "Open HTML part of message in browser (via ~/.mailcap)."
 (interactive)
 (save-excursion
 (notmuch-show-previous-message)
 (condition-case nil
 (search-forward "text/html")
 (error (message "No HTML part."))
 (:success (notmuch-show-view-part)
 (shell-command "open-i3-workspace 2")
 (message "Opened HTML in browser")
 ))))
(defun notmuch-search-mode-open-html ()
 "Open HTML part of message in browser (via ~/.mailcap)."
 (interactive)
 (save-excursion
 (notmuch-search-show-thread)
 (notmuch-show-previous-message)
 (condition-case nil
 (search-forward "text/html")
 (error (message "No HTML part."))
 (:success (notmuch-show-view-part)
 (shell-command "open-i3-workspace 2")
 (message "Opened HTML in browser")
 ))))

(keymap-set notmuch-search-mode-map (kbd "o") #'notmuch-search-mode-open-html)
(keymap-set notmuch-show-mode-map (kbd "o") #'notmuch-show-mode-open-html)

Mutt has an option called reverse_name. If activated the From: line in a reply will be built using the address the message was originally sent To:. If somebody writes me an email to “hi@jneidel.com”, I want to answer from “hi@jneidel.com”, even though “jneidel@jneidel.de” is my configured as my default sender. The code below does exactly that.

(use-package notmuch
 :defer t
 :config
 (defun notmuch--get-message-to ()
 "Return the raw To: header of the message or nil."
 (let ((message-properties (cond
 ((derived-mode-p 'notmuch-show-mode)
 (notmuch-show-get-message-properties))
 ((derived-mode-p 'notmuch-search-mode)
 (notmuch-search-show-thread)
 (notmuch-show-get-message-properties))
 ((derived-mode-p 'notmuch-tree-mode)
 (notmuch-tree-get-message-properties))
 (t nil))))
 (if (eq message-properties nil)
 nil
 (plist-get (plist-get message-properties :headers) :To))))

 (defun notmuch-reply-reverse-name-advice (orig-fn &rest args)
 "Advice 'notmuch-mua-reply' to use the original To: addresses as the From:."
 (let ((to-address (notmuch--get-message-to)))
 (apply orig-fn args)
 (when to-address
 (message-replace-header "From" to-address))))

 (advice-add 'notmuch-mua-reply :around #'notmuch-reply-reverse-name-advice))

One of the killer feature of having email in Emacs is being able to reference an email with a clickable link from org-mode files. This is achieved using ol-notmuch.

(use-package ol-notmuch
 :bind
 ("C-c l" . org-store-link))

Oftentimes PDFs are attached to incoming mail. By default these would need to be manually saved and then opened. This script extracts the text data from the PDF attachment and pops it into a new buffer (source).

(defun user/mm-pipe-- (handle cmd)
 ;; conveniently, '-' '-' a args to pdftotext and docx2txt.pl work fine
 ;; fixme: naming inconsistency (fn name and buffer name)
 (let ((buffer (get-buffer-create "*attachment-to-text*")))
 (with-current-buffer buffer
 (setq buffer-read-only nil)
 (erase-buffer))
 (with-temp-buffer
 ;; "based on mm-pipe-part in mm-decode.el"
 (mm-with-unibyte-buffer
 (mm-insert-part handle)
 (mm-add-meta-html-tag handle)
 (let ((coding-system-for-write 'binary))
 (call-process-region (point-min) (point-max)
 cmd nil buffer nil "-" "-"))))
 (pop-to-buffer buffer)
 (goto-char (point-min))
 (text-mode)
 (visual-line-mode)
 (view-mode)))

(defun user/notmuch-show-pop-attachment-to-buffer ()
 ;; "based on notmuch-show-apply-to-current-part-handle"
 (interactive)
 (let ((handle (notmuch-show-current-part-handle)))
 ;;(message "%s" handle)
 (unwind-protect
 (pcase (car (nth 1 handle))
 ("application/pdf"
 (user/mm-pipe-- handle "pdftotext"))
 ("application/vnd.openxmlformats-officedocument.wordprocessingml.document"
 (user/mm-pipe-- handle "docx2txt.pl"))
 (_ (notmuch-show-save-part)))
 (kill-buffer (mm-handle-buffer handle)))))

(setq notmuch-show-part-button-default-action
 #'user/notmuch-show-pop-attachment-to-buffer)

The latest version of my Emacs config (and thus all of the above snippets) can always be found in my dotfiles.

Android client #

For the occasional access on my phone I use K-9 Mail. The same values as in the above IMAP and SMTP sections are used.

Testing #

Obviously we need to test that outgoing mail from the different domains are delivered and that incoming mail arrives, is properly tagged and displayed.

Uberspaces webmail can be used for testing if needed.

DKIM

To make sure DKIM and SPF are working correctly used this website for testing.

Conclusions #

Email was at first a daunting task because of the many moving parts and the endless testing on every change. Once I understood what components I needed and what they were responsible for they were not hard to configure. I hope you were able to take that understanding away from this.

Being able to have email in Emacs was definitely worth it to me. It is now easier than ever to reach inbox zero.

Add Hyper Modifier Key for Emacs on Linux

web@jneidel.com (Jonathan Neidel) — Sat, 16 Aug 2025 00:00:00 +0000

Modern keyboards don’t include a hyper key anymore. Emacs still supports it and here is how and why to add it.

What make adding a hyper key useful? #

Emacs only has so many modifier keys. Control and meta are heavily used by the default Emacs keybindings. Super is already filled with my window managers bindings. Leaves only the alt and hyper modifiers, for which I don’t have keys on my laptop.

Using one of these two empty modifier keys allows me to add a lot of directly accessible keybindings in an unobstrusive way. C-x … is fine for most commands, but what I use all the time I want more directly accessible, like H-b for buffer selection. And especially commands that repeat, like undo don’t work well with non-modifier prefixes like C-x, because you can’t keep holding it throughout.

Add your own hyper key #

What you are going to need is:

A key you don’t care about. I picked “End”. It can even be a key that does not exist on your keyboard, like “F13”.

An easy to reach key you want to turn into “Hyper”. I picked “ö”. On my german keyboard this is on the home row under my right pinkie. You will not loose this key. On tap it will work as normal, only on hold will it turn into “Hyper”.

In the configuration below I will reference the keys that I chose. Just replace them with the keys of your choosing when you set this up.

The tools and the logic #

I use kmonad for outputing different keys when I (1.) press a key or (2.) hold it for 200ms. This is technique is called “mod tap”.

The only problem with kmonad is, that it doesn’t know the hyper key. The way we get around this is by having kmonad output a key that we don’t care about (“End” in my case) and turning that into “Hyper” with Xmodmap.

Implementation #

~/.config/kmonad/mod-tap-mappings.kbd

(defcfg
 input (device-file "/dev/input/by-path/platform-i8042-serio-0-event-kbd")
 output (uinput-sink "kmonad-output")

 ;; tell KMonad to let unconfigured keys act normal
 fallthrough true
)

(defsrc
 semicolon ;; this is the evdev version of ö
)

(defalias
 ;; ö mod-tap: tap = ö (semicolon), hold = hyper (end)
 ö_hyper (tap-hold-next 200 semicolon end)
 ;; end will be transformed into hyper by xmodmap
)

(deflayer base
 @ö_hyper
)

Now run sudo kmonad ~/.config/kmonad/mod-tap-mappings.kbd &

~/.config/Xmodmap

! unmap Num_Lock as a modifier
! see modifier mappings: $ xmodmap -pm
remove mod2 = Num_Lock

! have End key output Hyper instead
! see keycodes: $ xmodmap -pke
! mapping both for good measure 🙂
keycode 115 = Hyper_R
keycode 87 = Hyper_R

! activate Hyper as a modifer key
add mod2 = Hyper_R

Now run xmodmap ~/.Xmodmap

You can now test that your newly-added hyper key works in Emacs:

(use-package consult
 :ensure t
 :bind ("H-b" . consult-buffer))

The last thing is to configure this to run at startup. Observe the order of execution, as it is matters. Add this to your autostart script, in my case ~/.xinit

# ö mod-tap: tap = ö, hold = hyper
sudo kmonad ~/.config/kmonad/mod-tap-mappings.kbd &
sleep 3s && xmodmap ~/.Xmodmap &

Enjoy :slightly_smiling_face:

References #

The issue on the kmonad Github contains more details if you want to dive deeper.