zk-emacs

Emacs interface for the zk plain text note-taking assistant.

Warning

This is currently an alpha project, so you may encounter some bugs!

Requirements

• GNU Emacs ≥ 30.1
• zk
• tomlparse.el (including the TOML Tree-sitter grammar)

Installation

Currently, zk-emacs (hereafter called zk4e)¹ is not on any package archive. If you are using Emacs 30.1+ and use-package, then you can install zk4e with the following:

(use-package zk4e
  :ensure t
  :vc ( :url "https://codeberg.org/mcookly/zk4e"
        :branch "main"
        ;; You may want to pin a commit until the first 0.x version
        ;; is released (hopefully soon).
        :rev :newest))

Of course, you can install zk4e via Elpaca or Straight if you wish.

Configuration

While I have designed its functions to be composable so that you can adapt zk4e to match your workflow, zk4e tries to respect zk's configuration as much as possible. By default, zk4e will detect notebooks based on ZK_NOTEBOOK_DIR or Emacs's default-directory. You may store locations to notebooks, if you wish, by customizing zk4e-notebook-directories. See Usage for more information.

Important

If you customize zk4e-notebook-directories, before/after loading zk4e, you must run zk4e-select-notebook to select a default notebook on startup. See the example configuration.

Here is a use-package example:

(use-package zk4e
  :custom
  ;; You can name notebooks for easier switching if you wish. See the
  ;; documentation for details.
  (zk4e-notebook-directories '(("Brain" . "~/Brain")
                               ("Notes" . "~/Notes")))

  :config
  ;; This selects "Brain" as the default notebook.
  (zk4e-select-notebook "Brain"))

By default, zk4e shows only the title of a note for completion in Emacs. If you have notes with the same name, adjust zk-completion-format. You may also wish to change how zk4e opens notes. You can do so by editing display-buffer-alist to perform certain actions when zk4e-note-p is true.

If you wish to have a buffer's name reflect its note's title, consider adding zk4e-maybe-name-buffer to zk4e-edit-hook. If you open notes from the command line, you may wish to add the function to server-visit-hook.

Usage

To maintain consistency, zk commands in Emacs have the same name and arguments as the respective CLI command. Assuming you're familiar with zk's CLI:

zk command	zk4e command
list	zk4e-list
edit	zk4e-edit
new	zk4e-new
tag list	zk4e-tag-list
index	zk4e-index

When called interactively, zk4e-list and zk4e-edit behave like zk list --interactive and zk edit --interactive respectively.

Switch notebooks with zk4e-select-notebook.

If zk is not working, you may find the log helpful. To visit it, call zk4e-goto-error.

Extending

zk4e is designed to be extensible. zk4e-edit, zk4e-list and zk4e-new should be sufficient building blocks for more complex commands. To add easy zk argument completion, consider using zk4e-interactive in place of interactive. (See zk4e-new-group for a simple example.)

Consider using the helper macros zk4e-with-configuration, zk4e-with-notebook and zk4e-with-notebook-directory when working with specific notebooks.

Integrations

• zk4e-citar for Citar

Contributing

I am an amateur hobbyist lisper, and my code probably reflects that. If you have suggestions or bugfixes, please open an issue or a PR. Collaboration is always welcome!

---

1. An Emacs package by the name of zk already exists, so to prevent conflict, this package uses zk4e, inspired by the incredible mu4e. ↩︎