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
|
2020-04-03 19:50:10 +00:00
|
|
|
set of Org-roam files. Remember to run `org-roam-db-build-cache` from a
|
2020-03-05 16:19:11 +00:00
|
|
|
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
|
2020-04-26 09:29:21 +00:00
|
|
|
[Roam Protocol](roam_protocol.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
|
|
|
|
|
|
|
```
|
2020-03-31 08:56:15 +00:00
|
|
|
(setq org-roam-graph-executable "/path/to/dot")
|
2020-02-12 19:14:34 +00:00
|
|
|
```
|
|
|
|
|
2020-03-13 05:37:55 +00:00
|
|
|
You may also choose to use `neato` in place of `dot`, which generates a more compact graph layout.
|
|
|
|
|
|
|
|
```
|
2020-03-31 08:56:15 +00:00
|
|
|
(setq org-roam-graph-executable "/path/to/neato")
|
|
|
|
(setq org-roam-graph-extra-config '(("overlap" . "false")))
|
2020-03-13 05:37:55 +00:00
|
|
|
```
|
|
|
|
|
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")
|
|
|
|
```
|
2020-03-12 11:34:27 +00:00
|
|
|
|
2020-03-13 17:17:32 +00:00
|
|
|
### Excluding Nodes and Edges
|
|
|
|
One may want to exclude certain files to declutter the graph. You can do so by setting `org-roam-graph-exclude-matcher`.
|
|
|
|
|
|
|
|
```
|
|
|
|
(setq org-roam-graph-exclude-matcher '("private" "dailies"))
|
|
|
|
```
|
|
|
|
|
|
|
|
This setting excludes all files whose path contain "private" or "dailies".
|
|
|
|
|
2020-03-12 11:34:27 +00:00
|
|
|
## Org-roam Completion System
|
|
|
|
|
|
|
|
Org-roam offers completion when choosing note titles etc.
|
|
|
|
The completion system is configurable. The default setting,
|
2020-03-13 17:17:32 +00:00
|
|
|
|
2020-03-12 11:34:27 +00:00
|
|
|
```
|
|
|
|
(setq org-roam-completion-system 'default)
|
|
|
|
```
|
2020-03-13 17:17:32 +00:00
|
|
|
|
2020-03-12 11:34:27 +00:00
|
|
|
uses Emacs' standard `completing-read`. If you prefer [Helm](https://emacs-helm.github.io/helm/), use
|
|
|
|
|
|
|
|
```
|
|
|
|
(setq org-roam-completion-system 'helm)
|
|
|
|
```
|
2020-03-13 17:17:32 +00:00
|
|
|
|
|
|
|
Other options included `'ido`, and `'ivy'`.
|