kbd-mode

An Emacs major-mode for syntax highlighting kmonad's .kbd files. Because the configuration language has a lisp-ish syntax, you will find this very close to a regular lisp editing experience.

We provide the following additional keybindings (see Demo Mode for more information):

Keybinding	Function
C-c C-c	kbd-mode-start-demo
C-c C-z	kbd-mode-switch

Installation

package-vc

If you are on Emacs 29 and newer, you can use package-vc-install:

(package-vc-install
 '(kbd-mode . (:url "https://github.com/kmonad/kbd-mode")))

vc-use-package provides use-package integration, if that's your thing.

(use-package kbd-mode
  :vc (:fetcher github :repo kmonad/kbd-mode))

Alternatively, if you're on Emacs 30, a :vc keyword is built into use-package:

(use-package kbd-mode
  :vc (:url "https://github.com/kmonad/kbd-mode" :rev :newest))

Manually

Copy kbd-mode.el into a directory within your load-path and require it. For example, assuming that this file was placed within the ~/.config/emacs/elisp directory:

(add-to-list 'load-path "~/.config/emacs/elisp/")
(require 'kbd-mode)

If you use use-package, you can express the above as

(use-package kbd-mode
  :load-path "~/.config/emacs/elisp/")

Quelpa

If you use quelpa and quelpa-use-package, you can install directly from its repository:

(use-package kbd-mode
  :quelpa (kbd-mode :fetcher github :repo "kmonad/kbd-mode")
  :mode "\\.kbd\\'"
  :commands kbd-mode)

Spacemacs

If you use Spacemacs, add the following in the dotspacemacs-additional-packages section:

(kbd-mode
 :location
 (recipe
  :fetcher github
  :repo "kmonad/kbd-mode"))

Doom Emacs

If you use Doom Emacs, add the followings in the packages.el and config.el respectively.

(package! kbd-mode
  :recipe (:host github
           :repo "kmonad/kbd-mode"))

(use-package! kbd-mode)

GNU Guix

On Guix, kbd-mode can be installed via guix install:

$ guix install emacs-kbd

Demo Mode

The minor mode kbd-mode-demo-mode allows you to try out your configuration in a separate buffer.

Usage of this mode requires you to first customize the kbd-mode-kill-kmonad and kbd-mode-start-kmonad variables. If applicable, these are used for killing and (re-)starting your regular kmonad process.

For example:

(use-package kbd-mode
  :load-path "~/.config/emacs/elisp/"
  :custom
  (kbd-mode-kill-kmonad "pkill -9 kmonad")
  (kbd-mode-start-kmonad "kmonad ~/path/to/config.kbd"))

Note that, in general, it is not a good idea to run kmonad with root privileges. As such, kbd-mode-demo-mode only handles your configuration correctly if it was started as a regular user.

Starting and Stopping the Demo

To start the demo, either run M-x kbd-mode-start-demo RET or the corresponding keybinding, C-c C-c, for it. If current files extension is .kbd it's automatically selected as chosen configuration file. Else you'll be prompted for a file.

If your configuration does not compile, the current (working) kmonad process will not be killed and the demo won't start. Instead, an error buffer will be shown.

By default, start a demo process upon entering kbd-mode-demo-mode and stop it (starting an appropriate "normal" kmonad instance if needed) when exiting the mode with C-c C-c (kbd-mode-stop-demo).

If you set the variable kbd-mode-magic-focus to t, then this process will also happen whenever focus changes with regards to the *kmonad-demo* buffer. I.e., whenever you change focus from the demo buffer to another buffer, the demo process will be killed and a normal process starts. Likewise, when you switch to the demo buffer, your existing kmonad instance (if any) will be killed and a new demo.