Mastering Org-roam
Table of Contents
1 Introduction
Org-roam is a personal kb built on top of Org Mode. The best place to get up to date information is https://www.orgroam.com/, however this post is my personal note and guide that I used to configure it and use it for my needs. Hopefully it will help you as well.
2 Installation
Install it from MELPA.
M-x list-packages RET org-roam RET
Also install sqlite3. On Arch you can simply do sudo pacman -S sqlite3
The only configuration I did was to create ~/org-roam directory in your home which in my case is a Dropbox folder under my home directory but I use different home for my emacs.
Then add the following in your .emacs file.
(setq org-roam-directory "~/org-roam")
That is it really. Of course refer to the manual if you have to https://www.orgroam.com/manual.html
3 Basic usage
To start org-roam simple do M-x org-roam-mode. Then you can build cache using org-roam-db-build-cache.
However you can start org-roam-mode automatically on startup by adding the following line in your .emacs file.
(add-hook 'after-init-hook 'org-roam-mode)
3.1 Create a note
Call M-x org-roam-find-file and press tab it will show all the existing files in the ~/org-roam directory. It will be empty so press RET and create a new one.
It works like org-capture. It will create a note and will keep you on that note. I use C-x k to kill that buffer after saving that note of course.
However if you are used to org-capture like me then use M-x org-roam-capture which will bring you back to the original buffer.
3.2 Link to existing note
When you are working on a note, you obviously may want to link it to another existing note.
Call M-x org-roam-insert, select the file and insert it. It will make a link to that note.
3.3 Link to a new note
Using M-x org-roam-insert if the note you want to link to doesn't exist then no problem, create one on the fly and it will be linked. Cools isn't it?
3.4 Multiple titles, aliases and tags
A note can have more than one title.
#+title: Make Emacs video on org-roam #+roam_alias: "emacs" "video" "org-roam" #+roam_tags: "emacs" "tag1" "tag2" Note here
If you have more than one title then if you do M-x org-roam-capture then all the titles will appear. Convenient feature to have.
3.5 File Refs
These are unique identifiers for files.
#+title: Ravi Sagar #+roam_key: https://www.ravisagar.in
These keys helps in backlinks. For instance if another file links to https://www.ravisagar.in, then it will show up in backlines
4 Graphing
Linking various org-roam files together is the key feature and there is a way to show the interconnections. It took me sometime to configure it and I think I got it working.
An svg file show all the interconnections of your notes can be generated using M-x org-roam-graph RET. This will create a file like graph.XYZabc.svg~in your ~/tmp/ directory, which you can open in your browser showing all the interconnection.
4.1 Graphviz is needed for generating images
Install graphviz on your computer. On Arch linux you can do that with sudo pacman graphviz.
4.2 Roam Protocol for navigating the notes
When you open the svg file in your browser like Brave in my case you can see the interconnections of various notes which is great but cool thing is that you can also click on those individual notes in your browser and it can open that note in your emacs. Let us see how it works.
4.2.1 First enable the org-roam-protocol by adding this line to you .emacs file.
(require 'org-roam-protocol)
Make sure you have emacsclient installed on your computer.
4.2.2 Create a desktop application in ~/.local/share/applications/org-protocol.desktop file.
[Desktop Entry] Name=Org-Protocol Exec=emacsclientnew %u Icon=emacs-icon Type=Application Terminal=false MimeType=x-scheme-handler/org-protocol
If you notice in this file I am using emacsclientnew not emacsclient because I had a problem decoding the file path. So emacsclientnew is a shell script doing the decoding of the file path.
#!/bin/bash
function urldecode() {
: "${*//+/ }"; echo -e "${_//%/\\x}";
}
emacsclient $(urldecode $1)
If you make changes in your .desktop file then run this command to update the changes.
update-desktop-database ~/.local/share/applications/
4.2.3 Associate org-protocol:// links with the desktop application
Run this in your shell.
xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol
4.2.4 Start emacs server
Run this command.
M-x server-start
Or you can also add the following line in your .emacs file.
(server-start)
Finally enjoy this feature :) All done.