🧠 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.

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-plus
brew 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_profile
    export 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]].

Resources

[[Zaiste Programming tutorial]]
Org Roam Docs
Great Overview Video of Org Roam
Doom emacs docs
Doom emacs discord server
Doom emacs windows installation instructions