consult-org-roam

This is a collection of functions to operate org-roam with the help of consult and its live preview feature. You can use it to search, filter and find notes, preview backlinks as well as forward links, and sift through currently open org-roam buffers.

Overview and usage

consult-org-roam.el

consult-org-roam.el provides several functions to connect org-roam to consult’s completing read interface. On the one hand, it provides the following standalone functions which enhance org-roam’s capabilities:

consult-org-roam-file-find

Search your org-roam files with consult’s completing-read and its live preview

consult-org-roam-backlinks

List backlinks to org-roam-node-at-point (e.g. currently open note) and sift through them with consult’s completing-read and its live preview

consult-org-roam-backlinks-recursive

Recursive version of the former function, compared to which also considers headline nodes without explicit links to their ancestor headline and/or file nodes.

consult-org-roam-forward-links

List forward links contained in the currently opened note

consult-org-roam-search

Asynchronously search your roam-directory with grep or ripgrep

On the other hand, it provides a minormode called consult-org-roam-mode. When activated, org-roam-node-read is overridden, which is used by org-roam-node-find, org-roam-node-insert and org-roam-refile. By doing so, all functions utilizing completing-read resort to consult for performing completion. Furthermore, the same is done for org-roam-ref-read so that consult is used for completing references as well.

Eventually, you might want to suppress previewing for certain functions. This can be done by adding using consult-customize.

consult-org-roam-buffer.el

consult-org-roam-buffer.el adds a new source to consult-buffer for narrowing the selection to the currently open org-roam buffers. The predefined narrow-key is n (for notes) but could be conveniently customized via consult-org-roam-buffer-narrow-key.

Installation

You can install it from Melpa. If you are using use-package, the following snippet might serve as a viable starting point:

(use-package consult-org-roam
   :ensure t
   :after org-roam
   :init
   (require 'consult-org-roam)
   ;; Activate the minor mode
   (consult-org-roam-mode 1)
   :custom
   ;; Use `ripgrep' for searching with `consult-org-roam-search'
   (consult-org-roam-grep-func #'consult-ripgrep)
   ;; Configure a custom narrow key for `consult-buffer'
   (consult-org-roam-buffer-narrow-key ?r)
   ;; Display org-roam buffers right after non-org-roam buffers
   ;; in consult-buffer (and not down at the bottom)
   (consult-org-roam-buffer-after-buffers t)
   :config
   ;; Eventually suppress previewing for certain functions
   (consult-customize
    consult-org-roam-forward-links
    :preview-key "M-.")
   :bind
   ;; Define some convenient keybindings as an addition
   ("C-c n e" . consult-org-roam-file-find)
   ("C-c n b" . consult-org-roam-backlinks)
   ("C-c n B" . consult-org-roam-backlinks-recursive)
   ("C-c n l" . consult-org-roam-forward-links)
   ("C-c n r" . consult-org-roam-search))

Dependencies

consult-org-roam is built on top of org-roam and consult, it relies on its functionality.

Furthermore, ensure that you have at least grep or ripgrep installed on your system, and set consult-org-roam-grep-func to #'consult-ripgrep when using the latter.