The number of configuration options is deliberately kept small, to keep the Org-roam codebase manageable. However, we attempt to accommodate as many usage styles as possible.
All of Org-roam's customization options can be viewed via
Setting the Org-roam Directory
org-roam-directory to the folder containing all your Org files:
(setq org-roam-directory "/path/to/org/")
Every Org file, at any level of nesting, within
considered part of the Org-roam ecosystem.
Having More Than One Org-roam Directory
Emacs supports directory-local variables, allowing the value of
org-roam-directory to be different in different directories. It does
this by checking for a file named
To add support for multiple directories, override the
org-roam-directory variable using directory-local variables. This is
.dir-locals.el may contain:
((nil . ((org-roam-directory . "/path/to/here/"))))
All files within that directory will be treated as their own separate
set of Org-roam files. Remember to run
org-roam-db-build-cache from a
file within that directory, at least once.
The Org-roam buffer defaults to popping up from the right. You may
choose to set it to pop up from the left with
The Org-roam buffer name can also be renamed: e.g.
The Org-roam buffer width is adjustable via
The value of
org-roam-buffer-width set as a percentage of the total
frame width. For example:
(setq org-roam-buffer-width 0.4)
Will result in the Org-roam buffer taking up 40% of the screen width.
You can change backlinks appearance in the buffer by customizing
org-roam-backlink face (
M-x customize-face org-roam-backlink).
By default, links are inserted with the title as the link description.
This can make them hard to distinguish from external links. You may
choose add special indicators for Org-roam links by tweaking
org-roam-link-title-format, for example:
(setq org-roam-link-title-format "R:%s")
If your version of Org is at least
9.2, you may also choose to
simply style the link differently, by customizing
M-x customize-face org-roam-link).
Org-roam files are created and prefilled using Org-roam's templating system. The templating system is customizable, and the system is described in detail in the Org-roam Template page.
As your collection grows, you might want to create an index where you keep links to your main files.
In Org-roam, you can define the path to your index file by setting
(setq org-roam-index-file "index.org")
You can then bind
org-roam-jump-to-index in your configuration to access it (see Basic Install and
Configuration to review how
to set key-bindings).
Encryption (via GPG) can be enabled for all new files by setting
t. When enabled, new files are created
.org.gpg extension and decryption are handled automatically
Note that Emacs will prompt for a password for encrypted files during cache updates if it requires reading the encrypted file. To reduce the number of password prompts, you may wish to cache the password.
Org-roam Graph Viewer
Org-roam tries its best to locate the Graphviz executable from your
PATH, but if it fails to do so, you may set it manually:
(setq org-roam-graph-executable "/path/to/dot")
You may also choose to use
neato in place of
dot, which generates a more compact graph layout.
(setq org-roam-graph-executable "/path/to/neato") (setq org-roam-graph-extra-config '(("overlap" . "false")))
Org-roam also attempts to use Firefox (located on
PATH) to view the
SVG, you may choose to set it to any compatible program:
(setq org-roam-graph-viewer "/path/to/image-viewer")
Excluding Nodes and Edges
One may want to exclude certain files to declutter the graph. You can do so by setting
(setq org-roam-graph-exclude-matcher '("private" "dailies"))
This setting excludes all files whose path contain "private" or "dailies".
Org-roam Completion System
Org-roam offers completion when choosing note titles etc. The completion system is configurable. The default setting,
(setq org-roam-completion-system 'default)
uses Emacs' standard
completing-read. If you prefer Helm, use
(setq org-roam-completion-system 'helm)
Other options included