5 Getting Started

This short tutorial describes the essential commands used in Org-roam, to help you get started.

First, it is important to understand how Org-roam was designed. Org-roam was built to support a workflow that was not possible with vanilla Org-mode. This flow is modelled after the Zettelkasten Method, and many of Roam Research’s workflows. Org-roam does not magically make note-taking better – this often requires a radical change in your current note-taking workflow. To understand more about the methods and madness, see Note-taking Workflows.

To first start using Org-roam, one needs to pick a location to store the Org-roam files. The directory that will contain your notes, and database index is specified by the variable org-roam-directory. This variable needs to be set before any calls to Org-roam functions, including enabling org-roam-mode. For this tutorial, create an empty directory, and set org-roam-directory:

(make-directory "~/org-roam")
(setq org-roam-directory "~/org-roam")

We encourage using a flat hierarchy for storing notes, but some prefer using folders for storing specific kinds of notes (e.g. websites, papers). This is fine; Org-roam searches recursively within org-roam-directory for any notes. Instead of relying on the file hierarchy for any form of categorization, we solely rely on links between files to establish connections between notes.

Next, we need to enable the global minor mode org-roam-mode. This sets up Emacs with several hooks, builds a cache and keeps it consistent. We recommend starting org-roam-mode on startup:

(add-hook 'after-init-hook 'org-roam-mode)

To build the cache manually, one can run M-x org-roam-db-build-cache. The cache is a sqlite database named org-roam.db, which defaults to residing in the root org-roam-directory. Cache builds may take a while the first time, but is often instantaneous in subsequent runs.

Let us now create our first note. Call M-x org-roam-find-file. This shows a list of titles for notes that reside in org-roam-directory. It should show nothing right now, since there are no notes in the directory. Entering the title of the note you wish to create, and pressing RET should begin the note creation process. This process uses org-capture’s templating system, and can be freely customized (see The Templating System). Using the default template, pressing C-c C-c finishes the note capture. Running M-x org-roam-find-file again should show the note you have created, and selecting that entry will bring you to that note.

The crux of Org-roam is making it easy to create notes, and link them together. To link notes together, we call M-x org-roam-insert. This brings up a prompt with a list of title for existing notes. Selecting an existing entry will create and insert a link to the current file. Entering a non-existent title will create a new note with that title. Good usage of Org-roam requires liberally linking files: this facilitates building up a dense knowledge graph of inter-connected notes.

Org-roam provides an interface to view backlinks. It shows backlinks for the currently active Org-roam note, along with some surrounding context. To toggle the visibility of this buffer, call M-x org-roam.

For a visual representation of the notes and their connections, Org-roam also provides graphing capabilities, using Graphviz. It generates graphs with notes as nodes, and links between them as edges. The generated graph can be used to navigate to the files, but this requires some additional setup (see Roam Protocol).