Taking Notes with Emacs Org Mode and Org-Roam

Org-Roam implements the principles of the Zettelkasten method as a digital slip box full of cards. German sociologist Niklas Luhmann maintained a collection of tens of thousands notes, each written on an index card. These cards were linked through a series of keywords. This method allowed Luhmann to connect disparate ideas and writes his extensive oeuvre of books and articles.

The Org-Roam package in Emacs creates a network of links between your notes and manages your digital knowledge garden. Basically, the package extends Org mode functionality by storing all nodes (files and registered headings) in a database, including which between nodes. Furthermore, Org-roam provides each node in your knowledge network with a unique identifier consisting of a long string of numbers and letters, e.g. 711a7cac-e46b-4e64-b1e6-2940fa431e55.

The Org-Roam database provides excellent opportunities to analyse your network and discover patterns in your research that were perhaps previously invisible. You can examine this database and visualise its structure. The graph below is created with the igraph package in R.

The package provides a lot of freedom to structure your personal Wiki, and this article describes the basic functionality. However, before we can get started, we need to configure the system.

The Org-roam package stores a summary of all nodes in your network in a database. In Emacs version 29.1, this functionality comes out of the box and no further configuration is required.

If you are using an older version of Emacs, then Org-Roam depends on the EmacSQL package to connect with the database. During package installation EmacSQL needs to compile a custom native binary for communicating with the SQLite database.

To enable this task, you will need to install a compiler on your system. On GNU/Linux systems, including Chromebook, you need to instal the GCC compiler through your favourite package manager.

On Windows you need to install Chocolatey. Open PowerShell as administrator and follow he instructions on the Chocolatey website. After Chocolatey is available, you can install the compiler in Powershell as administrator with:

choco install mingw

When Emacs configures the Org-Roam package, it will try to compile the database connector. This might take a little while, but is only done once.

The Org-roam package requires some configuration to get it to work. At a minimum, we need to activate the package, bind some keys, define the folder where your notes and database will live and set a template for new notes.

You will also need to install the use-package package, which the configure Emacs article discusses. Alternatively, you can download the complete init file for this series of articles from GitHub and store it in your configuration folder.

You will also need to install use-package, which is explained article on how to configure Emacs.

  ;; Org-Roam basic configuration
  (setq org-directory (concat (getenv "HOME") "/Documents/org-roam/"))

  (use-package org-roam
    :after org
    :custom
    (org-roam-directory (file-truename org-directory))
    :init
    (org-roam-setup)
    :bind (("C-c n f" . org-roam-node-find)
           ("C-c n r" . org-roam-node-random)		    
           (:map org-mode-map
                 (("C-c n i" . org-roam-node-insert)
                  ("C-c n o" . org-id-get-create)
                  ("C-c n t" . org-roam-tag-add)
                  ("C-c n a" . org-roam-alias-add)
                  ("C-c n l" . org-roam-buffer-toggle)))))

The first line defines the default file for Org mode files. I store my Org-Roam notes in /Documents/notes/ in my home folder. You need to change the name of the folder to your personal preference. The (getenv ““HOME””) part of this configuration is your home folder, so you only need to modify the relative path between quotation marks.

The org-roam-setup function initiates the database, which can take a while the first time round if you have many existing notes.

Lastly, the configuration defines the keyboard shortcuts. The first three shortcuts are added to the overall keyboard map, so you can activate it from anywhere in Emacs. The last five lines are only valid when you are in an open Org mode buffer. Note that all shortcuts start with C-c n to provide consistency.

In Org-roam terminology, a file or a registered heading is a node in a network. You can promote a heading inside a file to a node by pressing C-c n o (org-id-get-create). This will create a property drawer below the heading with an id tag. Use the TAB key to open or close the drawer. Drawers are an Org mode functionality to store metadata about files or headings.

Org-roam indexes every node (file or heading with an id) that resides in its designated folder and subfolders in a database. This database contains metadata about the node, such as its title and any links from and to the node.

To make it easier to group and find nodes, you can give it one or more alias titles with the C-c n a shortcut (org-roam-alias-add). The main and the alias titles are searchable when finding a node. The name of the alias stored in the drawer at the start of the file.

To add one or more tags to a Org-Roam file, use org-roam-tag-add (C-c n t). Note that tags have completion using the TAB key. Tags are also searchable when visiting a node. Tags are a way to add structure to your nodes by adding them to a group. Adding a tag to a heading is as easy as hitting C-c C-c, which is a standard Org mode function.

The second method to add structure is by linking nodes. You can start writing your note as per usual. Links to existing files are easy to insert with the C-c n i shortcut (org-roam-node-insert). Search for the file you want to link to and hit enter.

As your nodes grow in number, you slowly build a personal knowledge network. Org-Roam has graphing capabilities, provided you have the Graphviz package installed, which is outside the scope of this article. The org-roam-ui package provides an interactive graphical interface to your node network through your browser.

If you like to know which files link to the buffer you are currently editing, then use org-rosm-buffer-toggle (C-c n l). A new window appears with a list of all files that link to the current buffer. Move to the window with org-open-at-point (C-c o), select your node, and hit ENTER to open the note. To close the backlinks window, use C-c n l again.

My favourite function is to open a random note. Pressing C-c n r (org-roam-node-random) opens a note and invite you to take a random walk through your knowledge garden.

The default new node only has a property drawer and a title and the filename starts with a timestamp. You can of course change this default behaviour by setting the org-roam-capture-templates variable.

For example, this configuration creates a new default node with a filename and a template head (file+head).

The file name is based on the title slug (${slug}.org), which is basically the node title in lower case, with spaces replaced by dashes.

The first lines of the head of this node contain the title, the creation date and a #+lastmod: entry, which you can use to store the date it was last saved. To make this happen, you also set the time-stamp-start variable.

The immediate-finish option bypasses the capture system and creates a new file without .

  (setq org-roam-capture-templates
        '(("d" "default" plain "%?"
           :if-new
           (file+head "${slug}.org"
                      "#+title: ${title}\n#+date: %u\n#+lastmod: \n\n")
           :immediate-finish t))
        time-stamp-start "#\\+lastmod: [\t]*")

The template functionality in Org-Roam is extensive, so I will leave it at this example. You can add additional lines to your node template after the title or lastmod entry in this example. The \n indicator denotes a new line.!