In a previous post, I described my note-taking workflow with zettelkasten and org. I extracted some of that logic out into a Github repository, and it sort of took a life of its own. Now that it’s gaining a bit of popularity and usage, I thought I’d do a more formal introduction to the package, and how I use it. It is not published on MELPA, and likely won’t be for a while, but you can find it on Github here. The features I really need are in, so once bug reports stop coming, I’ll cut a release, and start taking its development more formally.
What is Org-roam?
Org-roam is an attempt at replicating Roam in Emacs, built upon the all-powerful Org-mode format. Like Roam, it is a note-taking tool for networked thought. The tool encourages a non-hierarchical note-taking workflow. With Org-roam, note-taking becomes effortless and fun: write notes wherever you want, and link them up however you want. For more information about why a tool like this would be useful, you can read the following articles:
- Building a Second Brain in Roam…And Why You Might Want To : RoamResearch
- Roam: Why I Love It and How I Use It - Nat Eliason
Why Org-roam?
Org-roam may seem like a result of NIH syndrome, and perhaps there’s some partial truth to that. After all, it started out as 27 lines of code on top of deft. However, I believe there is some merit in building a tool for Emacs.
- Never having to leave Emacs. That’s an additional context switch I can avoid.
- Leverage all the powerful features of Org-mode: LaTeX, tables, and the whole to-do ecosystem. Ties in well with my org-mode workflow.
- Be in full control your second brain, and access it offline.
There are already several packages in Emacs that have some overlapping functionality, including org-brain, zetteldeft, and org-zettelkasten. Here’s what makes org-roam different:
First, in org-roam, the ordinary org file-link syntax is used. Contrast this with org-brain which uses org heading IDs, and zetteldeft that uses a special indicator. Org-roam is a plug-and-play solution that should work with existing Org files. This means org-roam can remain small, and its behaviour is predictable (it’s just 300 LOC now).
Second, org-roam mimics more closely Roam’s interface of an always- updating sidebar that shows backlinks and their preview content. This is as far as I know unique to org-roam at the time of writing.
Shut Up and Show Me the Goods
Alright, alright.
I’m going to be slightly unconventional here, and first show you the graph of my notes. Of course, this graph is generated by org-roam. Feel free to view the image in another window, to bask at it in its full glory. This is a testament to how non-hierarchical note-taking can be, and should be.
Figure 1: org-roam graph
All of this starts from the note. A note is just a simple .org file
in the directory. Any org file in the directory is considered part of
the org-roam ecosystem. Notes are quickly linked together (and created
if necessary) using org-roam-insert. Yes I know the GIFs look
crappy here. Do me a favour and right click -> view image would you.
Figure 2: org-roam-insert makes it easy to add links
Org-roam tracks all of these file links, and builds a cache asynchronously in the background. This cache is used to populate the backlinks buffer, which shows files that link to the current file, as well as some preview contents:
Figure 3: the org-roam buffer gives a nice navigable preview of backlinked content
If that’s not enough, the org-roam graph shows is navigable. This is especially nice when using exwm, but that’s not necessary.
Figure 4: navigating to files using the org-roam graph
What’s next?
I’d always been building out Org-roam as my workflow adapts. Now that there’s a small community using it, I foresee that changing a little. I’d think org-roam will still be highly guided by my tastes, but I don’t imagine forking off org-roam to be challenging, since the code is relatively simple.
A lot of the core functionality is already there, but some things could definitely be improved, including:
- The aesthetics of the org-buffer.
- Smaller graph generations around the current content.
Once the core features are stable, I’d like to start working on introducing features that the Emacs ecosystem makes possible:
- Keyboard-friendly navigation ⭐: perhaps using link-hint or the like.
- Rendering small SVGs within Emacs.
Give it a shot!
Give it a try, and let me know what you think. What else would you like to see?