2020-03-05 16:19:11 +00:00
|
|
|
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.
|
2020-02-12 16:25:45 +00:00
|
|
|
|
|
|
|
All of Org-roam's customization options can be viewed via `M-x
|
|
|
|
customize-group org-roam`.
|
|
|
|
|
2020-02-12 19:14:34 +00:00
|
|
|
## Setting the Org-roam Directory
|
|
|
|
|
2020-03-05 16:19:11 +00:00
|
|
|
Set `org-roam-directory` to the folder containing all your Org files:
|
2020-02-12 19:14:34 +00:00
|
|
|
|
|
|
|
```emacs-lisp
|
|
|
|
(setq org-roam-directory "/path/to/org/")
|
|
|
|
```
|
|
|
|
|
|
|
|
Every Org file, at any level of nesting, within `/path/to/org/` is
|
|
|
|
considered part of the Org-roam ecosystem.
|
|
|
|
|
2020-02-26 07:23:29 +00:00
|
|
|
### Having More Than One Org-roam Directory
|
|
|
|
|
2020-03-05 16:19:11 +00:00
|
|
|
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 `.dir-locals.el`.
|
2020-02-26 07:23:29 +00:00
|
|
|
|
2020-03-05 16:19:11 +00:00
|
|
|
To add support for multiple directories, override the
|
|
|
|
`org-roam-directory` variable using directory-local variables. This is
|
|
|
|
what `.dir-locals.el` may contain:
|
2020-02-26 07:23:29 +00:00
|
|
|
|
|
|
|
```emacs-lisp
|
2020-02-29 07:56:08 +00:00
|
|
|
((nil . ((org-roam-directory . "/path/to/here/"))))
|
2020-02-26 07:23:29 +00:00
|
|
|
```
|
|
|
|
|
2020-03-05 16:19:11 +00:00
|
|
|
All files within that directory will be treated as their own separate
|
|
|
|
set of Org-roam files. Remember to run `org-roam-build-cache` from a
|
|
|
|
file within that directory, at least once.
|
2020-02-29 07:56:08 +00:00
|
|
|
|
2020-02-12 19:14:34 +00:00
|
|
|
## Org-roam Buffer
|
|
|
|
|
|
|
|
The Org-roam buffer defaults to popping up from the right. You may
|
|
|
|
choose to set it to pop up from the left with `(setq
|
|
|
|
org-roam-buffer-position 'left)`.
|
|
|
|
|
|
|
|
The Org-roam buffer name can also be renamed: e.g. `(setq
|
|
|
|
org-roam-buffer "*my-buffer-name*")`.
|
|
|
|
|
|
|
|
The Org-roam buffer width is adjustable via `org-roam-buffer-width`.
|
|
|
|
The value of `org-roam-buffer-width` set as a percentage of the total
|
|
|
|
frame width. For example:
|
|
|
|
|
|
|
|
```emacs-lisp
|
|
|
|
(setq org-roam-buffer-width 0.4)
|
|
|
|
```
|
|
|
|
|
|
|
|
Will result in the Org-roam buffer taking up 40% of the screen width.
|
|
|
|
|
2020-03-08 06:54:56 +00:00
|
|
|
You can change backlinks appearance in the buffer by customizing
|
|
|
|
`org-roam-backlink` face (`M-x customize-face org-roam-backlink`).
|
|
|
|
|
2020-02-12 19:14:34 +00:00
|
|
|
## Org-roam Links
|
|
|
|
|
|
|
|
By default, links are inserted with the title as the link description.
|
2020-03-05 16:19:11 +00:00
|
|
|
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:
|
2020-02-12 19:14:34 +00:00
|
|
|
|
|
|
|
```emacs-lisp
|
|
|
|
(setq org-roam-link-title-format "R:%s")
|
|
|
|
```
|
|
|
|
|
2020-02-26 08:29:20 +00:00
|
|
|
If your version of Org is at least `9.2`, you may also choose to
|
2020-03-08 06:54:56 +00:00
|
|
|
simply style the link differently, by customizing `org-roam-link` face
|
2020-02-26 08:29:20 +00:00
|
|
|
(`M-x customize-face org-roam-link`).
|
2020-02-22 13:11:14 +00:00
|
|
|
|
2020-02-12 16:25:45 +00:00
|
|
|
## Org-roam Files
|
|
|
|
|
2020-03-05 16:19:11 +00:00
|
|
|
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](templating.md) page.
|
2020-02-12 19:14:34 +00:00
|
|
|
|
2020-02-16 10:31:51 +00:00
|
|
|
### Encryption
|
|
|
|
|
|
|
|
Encryption (via GPG) can be enabled for all new files by setting
|
|
|
|
`org-roam-encrypt-files` to `t`. When enabled, new files are created
|
2020-03-05 16:19:11 +00:00
|
|
|
with the `.org.gpg` extension and decryption are handled automatically
|
|
|
|
by EasyPG.
|
|
|
|
|
|
|
|
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.
|
2020-02-12 19:14:34 +00:00
|
|
|
|
|
|
|
## Org-roam Graph Viewer
|
|
|
|
|
|
|
|
Org-roam generates an SVG image using
|
2020-02-15 06:49:11 +00:00
|
|
|
[Graphviz](https://graphviz.org/). To setup graph navigation, see the
|
|
|
|
[Graph Setup](graph_setup.md) page.
|
2020-02-12 19:14:34 +00:00
|
|
|
|
|
|
|
Org-roam tries its best to locate the Graphviz executable from your
|
2020-03-05 16:19:11 +00:00
|
|
|
`PATH`, but if it fails to do so, you may set it manually:
|
2020-02-12 19:14:34 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
(setq org-roam-graphviz-executable "/path/to/dot")
|
|
|
|
```
|
|
|
|
|
2020-03-05 16:19:11 +00:00
|
|
|
Org-roam also attempts to use Firefox (located on `PATH`) to view the
|
2020-02-12 19:14:34 +00:00
|
|
|
SVG, you may choose to set it to any compatible program:
|
|
|
|
|
|
|
|
```
|
|
|
|
(setq org-roam-graph-viewer "/path/to/image-viewer")
|
|
|
|
```
|