Leveraging Some Org Roam Version 2 Changes
update: In Diving into the Implementation of Subject Menus for Org Roam, I wrote about the implementation details for the following post.
Earlier I wrote about Adding Hydra Menu for Org Roam Lookup in Emacs and then Revisiting Hydra Menu for Org Roam Lookup in Emacs. 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.
| Key Combination | Command |
|---|---|
| p t | Open Personal Todo File |
| p c | Capture Personal |
| p i | Insert Personal |
| p f | Find Personal |
| u c | Capture Public |
| u i | Insert Public |
| u f | Find Public |
| h t | Open Hesburgh Libraries Todo File |
| h c | Capture Hesburgh Libraries |
| h i | Insert Hesburgh Libraries |
| h f | Find Hesburgh Libraries |
| t c | Capture Thel Sector |
| t i | Insert Thel Sector |
| t f | Find Thel Sector |
| c | Capture |
| i | Insert |
| f | Find |
| / | 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:
- Capture
- Insert
- Find
- Subject Todo
- Toggle Buffer
- 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, andorg-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.
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:
| Key Combination | Command |
|---|---|
| c | Capture Thel Sector |
| i | Insert Thel Sector |
| f | Find 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.
Conclusion
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.
Top comments (0)