Ever Further Refinements of Org Roam Usage

Leveraging Some Org Roam Version 2 Changes


In , I wrote about the implementation details for the following post.

Earlier I wrote about and then . I wrote those when I was using Org-Roam 📖 version 1. The release of version 2 of Org-Roam broke that setup. But the breaking changes are well worth it!

Let’s dive into my new Org-Roam menu:

The Org Subject Menu. I invoke jnf/org-subject-menu--all/body via the keybinding C-c i.

Refer to Table #226 below for the description of heavy text-based image
Table 226: Textual Representation of Org Subject Menu
Key CombinationCommand
p tOpen Personal Todo File
p cCapture Personal
p iInsert Personal
p fFind Personal
u cCapture Public
u iInsert Public
u fFind Public
h tOpen Hesburgh Libraries Todo File
h cCapture Hesburgh Libraries
h iInsert Hesburgh Libraries
h fFind Hesburgh Libraries
t cCapture Thel Sector
t iInsert Thel Sector
t fFind Thel Sector
/Toggle Org Roam Side Buffer
#Toggle Default Filter

In the default menu, there’s duplication based on subject (e.g., Personal, Public, Hesburgh Libraries, and Thel Sector).

Let’s go over the basic commands:

  1. Capture
  2. Insert
  3. Find
  4. Subject Todo
  5. Toggle Buffer
  6. Toggle Default Filter

The Capture, Insert, and Find are three of the core functions of org-roam; I map org-roam-captureto C-s-c, org-roam-node-insert to C-s-i, and org-roam-node-find to C-s-f.

When you Capture something, you find or create a new node title. If you’re creating a new node, you select your template. You then start writing down your note. When you finish the capture, the buffer closes and you’re back to the original context in which you launched the capture.

When you Insert something, it’s like Capture, except when you finish writing, org-roam inserts a link to your node in the original context in which you launched the capture.

When you Find something, you open a buffer for the found node.

In the above Org Subject Menu, there’s a Capture, Insert, and Find for each subject. Each of those subjects are configured with a set of filters and templates appropriate for the subject. More on that later.

The Subject Todo is my way of partitioning todo lists. Each subject location it’s own todo.org that I maintain.

The Toggle Buffer calls org-roam-buffer-toggle, which toggles the backlinks buffer. When the backlinks buffer is open, and I’m on an org-roam node, I can see the list of nodes that link to the current org-roam node.

The Toggle Default Filter allows me to narrow my Org-Roam activity to a single subject. What does that mean?

The prompt area for toggling the default filter; the subjects are: all, hesburgh-libraries, personal, public, and thel-sector.

An emacs minibuffer with five entries: all, hesburgh-libraries, personal, public, and thel-sector.

When I select the “thel-sector” as the default filter, I re-map C-c i to jnf/org-subject-menu--thel-sector/body. The subject menu looks as follows:

Refer to Table #227 below for the description of heavy text-based image
Table 227: Textual Representation of Org Subject Menu
Key CombinationCommand
cCapture Thel Sector
iInsert Thel Sector
fFind Thel Sector
/Toggle Org Roam Side Buffer
#Toggle Default Filter
Note that I've dropped the t leading key.

In addition, I re-map C-s-c, C-s-i, and C-s-f to functions that automatically narrow the filter and templates to the “thel-sector” subject. So when I’m focusing on a particular subject, I can narrow my keyboard shortcuts to the subject.


This implementation feels much cleaner that my Org-Roam version 1 implementation. There’s both an internal consistency and a few more places to pivot.

I wrote an issue and submitted a pull request to org-roam. The maintainer of Org-Roam merged the pull request, and it’s now part of v2.1.0. The issue includes a lot more detail of the why and the how.

You can checkout this gist for my org-roam configuration. There’s room for improvement, but for now this is working quite well for my needs.

Those diving into the Emacs code will see that the Personal subject currently has two capture templates: a simple template and an encrypted template. It’s relatively simple to add new templates for a given subject.

For example, if I were to do more work in the Thel Sector, I might consider making a capture template for an Non-Player Character 📖, Session Notes, Locations, and Faction Turns.

Similarly, for the Hesburgh Libraries subject I could see templates for Meeting Minutes and Problem Statements. For now, I have a simple template.

I hope this provides some insights into hacking on Emacs 📖 and configuring Org-Roam.