Introducing nroam

Introduction & rationale

I’ve been absolutely loving org-roam since I started experimenting with it. It’s a brilliant implementation of the concept of bidirectional linking for org-mode—replacing hierarchies of notes—, however the way it displays backlinks never really clicked for me.

Because backlinks in org-roam are only displayed in a side buffer, they are easy to miss. The side buffer will not always be open, and even if it is, the information it contains is visually far away from the note you’re looking at.

I was reluctant to use the daily notes as much as I would have in applications such as Roam Research or Logseq, in fear of content getting buried in notes that I would not come back to.

Another issue with the side buffer implementation of backlinks in org-roam is that it does not display the entire outline subtree of a backlink. This is I think an essential part of the bidirectional linking feature of Roam for surfacing content from other notes.

Enter nroam

nroam is a supplementary package for org-roam that replaces its backlink side buffer. Instead, it displays org-roam backlinks at the end of org-roam buffers. The user can also click a button to see unlinked references, all in the original org-mode source buffer.

One of the ideas behind nroam is to remove the friction and effort it takes to consult backlinks. By making them an integral part of the org buffer, backlinks also become more powerful. You could for instance make a sparse tree—see org-sparse-tree—to filter the contents of a note and its backlinks at the same time.

Below is a screenshot of what nroam looks like.

For a comparison, here’s how backlinks are rendered in vanilla org-roam:

And here are the same backlinks displayed with nroam:

As you can see, the purpose is not only to display references within the notes buffer, but also to display the entire org-mode subtree for each reference, giving much more context to the reader.

Why extend org-roam?

Alternative Emacs packages exist, such as gkroam, which I could have simply used, but I decided instead to build nroam as a companion package for org-roam as I believe we should build upon and extend the existing ecosystem of org-roam instead of competing with it. Org-roam has gained a lot of traction recently and does much of the heavy lifting already, so there is no need to compete with it.

Installing nroam

nroam is still quite young and is not yet available in MELPA. A recipe is waiting for review, but in the meantime you will have to manually install the Elisp files in your .emacs.d from the git repository.

Once installed, simply add the following hook and you should be ready to go.

(add-hook 'org-mode-hook #'nroam-setup-maybe)