🧠 Own Your Second Brain: Set Up org-roam on Your Own Machine
I recorded an overview of what you can build when you follow this technical guide here on youtube.
Table of Contents
- Installing Doom Emacs
- Installing Org Roam
- Resources
First things first, I am new to emacs and the eco system so there are packages I’m not aware of.
This is my current set up that I am pretty happy with but if you read through it and see something that can be improved, please let me know on twitter at @_jonesian
or on the Doom Emacs Discord server!
Installing Doom Emacs
These are instructions for Mac/Linux, if you're on windows I recommend looking at ervingad's window instructions here.
First things first, you need to install Homebrew. I try to install as many programs from homebrew as I can. This way I can reduce the overhead of keeping all my dependencies up to date.
Once homebrew is installed, there are a couple utils you need for doom emacs.
brew install git ripgrep coreutils fd
I am on MacOS so I have to install the XCode developer tools
xcode-select --install
Some people have ran into issues directly installing emacs from brew (Youtube explanation link) so we are going to use install it a slightly different way:
brew tap d12frosted/emacs-plusbrew install emacs-plus
Now we need to actually install doom emacs. This is down through cloneing the git repo into your ~/.emacs.d
file that installing emacs-plus
gave you.
git clone https://github.com/hlissner/doom-emacs ~/.emacs.d
After this, we want to run doom install
. This command can be run from the recently cloned doom-emacs
project.
~/.emacs.d/bin/doom install
You will want to add this doom command to your path because any time you update the config, you will need to run doom refresh
to sync those changes.
# inside your .zshrc or .bash_profileexport PATH=$PATH:~/.emacs.d/bin
Finally, run emacs
in your terminal and you should see the doom homepage.
The Easy Way
[[Doom Emacs]] is the [[Emacs]] configuration that I use. There are flags that you can use to install common dependencies. To install [[Org Roam]], You need to add the +roam
flag to your org dependency.
So in your .doom.d/init.el
, find org
under the :lang
section and add the +roam
flag:
:lang(org +roam)
This will install org-roam
, org-roam-protocol
, and company-org-roam
(if you have company enabled).
By default, the org roam directory will be your in your org-directory/roam
. You can override where your org-roam-directory
. In your config.el
:
(setq org-roam-directory "~/Desktop/03-resources/org-roam")
For my [[Ephemeral Scratchings]], I have switched to using org-roam-dailies
which is just built into org roam. I call org-roam-dalies-today
to create or get back to my current daily notes. I keep all of my notes here. You can also use [[Org Journal]]. [[Doom Emacs]] has a flag for this as well:
:lang(org +roam +journal)
The Hard Way
This is how I first installed [[Org Roam]]. There is a lot of custom config code that you have to write that [[Doom Emacs]] has already taken care of for you.
Adding Org Roam To Your Config
There are 3 main files that define your doom emacs config:
- config.el
- init.el
- packages.el
doom emacs
comes with many different packages enabled as well as commented out packages that are popular options. Lets take a look, with emacs running, type spc f p
and then select the init.el
file. spc f p
is a short cut to get to your config from anywhere in emacs.
Scroll down to around line 138, you should see org
on a line. Org mode
comes with a + roam
flag, so it will install all of the dependencies for you. Change that line to look like this:
(org +roam)
Now, lets head over to our config.el
file: spc f p
, then select config.el
.
This is the file that you configure all of your packages in. You can see that this is where you can set your fonts and a theme if you want to change them heres a list of available themes. This is where we will set the directory that we will create our org-roam files in. I have mine in ~/Desktop/03-resources/org-roam
.
(setq org-roam-directory "~/Desktop/03-resources/org-roam")
You can access all of the Roam commands with spc n r
. It's nice to bind your own to skip that one character so lets add some custom key mappings.
Next we want to map some custom commands that you will use a lot in org-roam. To do this we will use the after!
hook doom provides to set some customization up after the org-roam
package is loaded.
(after! org-roam(map! :leader:prefix "n":desc "org-roam" "l" #'org-roam:desc "org-roam-insert" "i" #'org-roam-insert:desc "org-roam-switch-to-buffer" "b" #'org-roam-switch-to-buffer:desc "org-roam-find-file" "f" #'org-roam-find-file:desc "org-roam-show-graph" "g" #'org-roam-show-graph:desc "org-roam-insert" "i" #'org-roam-insert:desc "org-roam-capture" "c" #'org-roam-capture))
When you are in the Org
major emacs mode, you will be able to type spc n
and then any of these letters above to run those functions. For example, you can run M-x org-roam
instead of spc n l
to run the specific function.
When you want to create a new page, you can run spc n i
to insert a new topic page. This process is customizable with org capture templates so you can pre-fill any data you want based on a specific template.
Add Bidirectional Link Auto Complete
You need company-org-roam
. You'll need to install the package. Head over to your packages.el
file: spc f p
and select packages.el
. If you are using the (org +roam)
flag in Doom emacs, then you dont need to do this set up, its already done for you.
The maker of org-roam also made this package, we can install it straight from his github:
(package! company-org-roam:recipe (:host github :repo "jethrokuan/company-org-roam"))
Next, head over to your config.el
and add the configuration:
(require 'company-org-roam)(use-package company-org-roam:when (featurep! :completion company):after org-roam:config(set-company-backend! 'org-mode '(company-org-roam company-yasnippet company-dabbrev)))
Now you will need to quit your current session, doom refresh
and open emacs back up to get this to work. When you start typing, if you type the title or alias of an org roam note, a completion dialogue will show up and you can press enter
to select the completion.
Fleeting Notes
Roam Research puts you in a note that corresponds with the current day as a jumping off point for your notes. This same functionality can be accomplished with org journal
.
You can use use-package
function that doom emacs provides to install org journal
. org journal
comes installed in doom emacs, we just need to configure it to and point it to the same directory as your org roam
files. Open up your config (spc f p config.el
) and add this use-package
statement:
(use-package org-journal:bind("C-c n j" . org-journal-new-entry):custom(org-journal-dir "~/Desktop/03-resources/org-roam/")(org-journal-date-prefix "#+TITLE: ")(org-journal-file-format "%Y-%m-%d.org")(org-journal-date-format "%A, %d %B %Y"))(setq org-journal-enable-agenda-integration t)
Now you can enter a new journal for that day with C-c n j
(C
is the “control” key). You can see that we have configured what directory this journal entry is added to (in my case ~/Desktop/03-resources/org-roam/
). I like my Journal titles to be in “Tuesday, 05 May 2020” format.
I create a lot of TODO=s to my journal entries so =(setq org-journal-enable-agenda-integration t)
will automatically add these files to my agenda.
Capture Links From the Web
I’ve added a Chrome bookmarklet titled “open in roam” that will add any webpage I am on as a note in my Roam. Here are the docs on what an org-protocol
is and how to set it up with org-roam
. Make sure to follow the instructions for Mac OS
installing platypus
.
I ran the command in the “Note for emacs mac port” section which totally broke org-protocol
for me so don’t do that ;)
If you are using the (org +roam)
flag, you wont need to add (require 'org-roam-protocol)
to your org-roam
config.
Add a org-roam-capture-ref-templates
in your config.el
heres mine:
(after! org-roam(setq org-roam-capture-ref-templates'(("r" "ref" plain (function org-roam-capture--get-point)"%?":file-name "websites/${slug}":head "#+TITLE: ${title}#+ROAM_KEY: ${ref}- source :: ${ref}":unnarrowed t))))
The ROAM_KEY
is how org-roam
knows what site links to what note.
Now add the Chrome Bookmarklet. This is just adding a new bookmark. The title for mine is “Open Roam Notes” and the “url” is:
javascript: (function () {location.href ='org-protocol://roam-ref?template=r&ref=' +encodeURIComponent(location.href) +'&title=' +encodeURIComponent(document.title)})()
Now when you click the button, it will open or start the capture process for that specific ROAM_KEY
.
Navigate your files easily
I was recommended using deft
to navigate my org roam
files. This can be done by using the deft
flag in your init.el
(this option is disabled by default).
Or you can install it manually:
This can be done by adding use-package
in your config.el
.
(use-package deft:after org:bind("C-c n d" . deft):custom(deft-recursive t)(deft-use-filter-string-for-filename t)(deft-default-extension "org")(deft-directory "~/Desktop/03-resources/org-roam/"))
The important part is setting the directory to your org-roam
directory. Now you can get a list of your most recently edited org-roam
files.
Reach out to me on twitter at @jonesian or on the Doom Emacs Discord server if you have any questions or comments!
Be sure to level up your Emacs skills with [[Zaiste Programming tutorial]].