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
this tutorial, create an empty directory, and set
(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
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
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 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
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
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).