org-roam/doc/installation.md

Basic Install and Configuration

Org-roam is now available on MELPA, so you can install it via the following command:

M-x package-install RET org-roam RET

Alternatively, you may use package managers such as straight or quelpa to install the package.

The recommended method of configuration is to use use-package.

(use-package org-roam
      :hook
      (after-init . org-roam-mode)
      :custom
      (org-roam-directory "/path/to/org-files/")
      :bind (:map org-roam-mode-map
              (("C-c n l" . org-roam)
               ("C-c n f" . org-roam-find-file)
               ("C-c n j" . org-roam-jump-to-index)
               ("C-c n b" . org-roam-switch-to-buffer)
               ("C-c n g" . org-roam-graph))
              :map org-mode-map
              (("C-c n i" . org-roam-insert))))

Or without use-package:

(require 'org-roam)
(define-key org-roam-mode-map (kbd "C-c n l") #'org-roam)
(define-key org-roam-mode-map (kbd "C-c n f") #'org-roam-find-file)
(define-key org-roam-mode-map (kbd "C-c n j") #'org-roam-jump-to-index)
(define-key org-roam-mode-map (kbd "C-c n b") #'org-roam-switch-to-buffer)
(define-key org-roam-mode-map (kbd "C-c n g") #'org-roam-graph)
(define-key org-mode-map (kbd "C-c n i") #'org-roam-insert)
(org-roam-mode +1)

The Configuration page details some of the common configuration options available.

Completion

Link auto-completion is offered via company-org-roam, refer to the documentation there for further details.

Spacemacs

If you are using Spacemacs, install org-roam by creating a simple layer that wraps Org-roam. Paste the following into a new file ~/.emacs.d/private/org-roam/packages.el.

(defconst org-roam-packages
  '(org-roam))

(defun org-roam/init-org-roam ()
  (use-package org-roam
    :hook
    (after-init . org-roam-mode)
    :custom
    (org-roam-directory "/path/to/org-files/")
    :init
    (progn
      (spacemacs/declare-prefix "ar" "org-roam")
      (spacemacs/set-leader-keys
       "arl" 'org-roam
       "art" 'org-roam-dailies-today
       "arf" 'org-roam-find-file
       "arg" 'org-roam-graph)

      (spacemacs/declare-prefix-for-mode 'org-mode "mr" "org-roam")
      (spacemacs/set-leader-keys-for-major-mode 'org-mode
                                                "rl" 'org-roam
                                                "rt" 'org-roam-dailies-today
                                                "rb" 'org-roam-switch-to-buffer
                                                "rf" 'org-roam-find-file
                                                "ri" 'org-roam-insert
                                                "rg" 'org-roam-graph))))

Next, append org-roam to the dotspacemacs-configuration-layers list in your .spacemacs configuration file. Reload (SPC f e R) or restart Emacs to load org-roam. It's functions are available under the prefix SPC a r and , r when visiting an org-mode buffer.

If you also have the ranger layer installed, the prefix 'ar' conflict with that of the ranger layer. You might want to change it to 'aor' (also change the 'ar' to 'aor' in the other key-binding declarations)

Doom Emacs

Doom Emacs has a +roam flag on its org module for easy installation and configuration. Simply add the flag to the org section of your ~/.doom.d/init.el and run ~/.emacs.d/bin/doom sync.

Windows

On Windows, if you follow the installation instructions above, you will likely get the error message: "No EmacSQL SQLite binary available, aborting", and org-roam won't start properly.

You need to do some additional steps to get org-roam to work.

Essentially, you will need to have a binary file for emacsql-sqlite so that your Emacs can work with sqlite database -- org-roam uses it to track backlinks. The following options have been reported to work by Windows users in the community.

Option 1. Windows Subsystem for Linux (WSL)

This option lets you use Linux on your Windows machine. It's Linux, so you don't need to do anything specific for Windows.

Option 2. mingw-x64

Use mingw-x64. You would spend a bit of time to download it, and get familiar with how it works. You should be able to use Linux tools within your Windows [more contribution welcome].

Option 3. scoop

Use scoop to install a couple of software tools (make and gcc) and manually compile a binary (.exe) file yourself. Find a short step-by-step guide below.

Option 4. emacsql-sqlite3

Use another Emacs package called emacsql-sqlite3. You can download an official binary for sqlite3. emacsql-sqlite3 lets you use it. For this option to work, you need to adjust the org-roam source code, and get your modified version to work in your Emacs environment. Find a suggestion below.

scoop

Step 1. In PowerShell, install scoop (instruction here).

iwr -useb get.scoop.sh | iex

Step 2. In PowerShell, install make and gcc via scoop

scoop install make gcc

Step 3. In Emacs, install the emacsql-sqlite package for your Emacs if it is not done yet.

Step 4. In PowerShell, move to the directory where emacsql.c is stored.

With MELPA, it is likely to be under your ELPA folder:

~\AppData\Roaming\.emacs.d\elpa\emacsql-sqlite-20190727.1710\sqlite

With Doom Emacs, it should be under your .emacs\.local:

~\.emacs.d\.local\straight\build\emacsql-sqlite\sqlite

Check the files via dir command. You should see these files:

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----       22/03/2020  12:10 PM           5170 emacsql.c
-a----       22/03/2020  12:10 PM            439 Makefile
-a----       22/03/2020  12:10 PM        7516138 sqlite3.c
-a----       22/03/2020  12:10 PM         526684 sqlite3.h

Step 5. Compile the .exe file with make

make emacsql-sqlite CC=gcc LDLIBS=

You will see the process triggered with lots of text automatically scrolling down; it may take a couple of minutes for compilation to finish.

Once compilation is done, check that emacsql-sqlite.exe has been added to the directory.

Step 6. Relaunch Emacs, use org-roam

When you start org-roam (e.g. via org-roam-mode), now you should no longer see the "No EmacSQL SQLite binary available, aborting" error. You are good to go.

emacsql-sqlite3

1. In Emacs, install the emacsql-sqlite3 package

2. Using your text editor, etc. modify org-roam-db.el:

   1. Replace (require 'emacsql-sqlite) with (require 'emacsql-sqlite3)

   2. Comment/deactivate the complete (defconst org-roam-db--sqlite-available-p ... )

   3. In (defun org-roam-db ..., replace emacsql-sqlite with emacsql-sqlite3

3. If you compile .el files, ensure to replace org-roam-db.elc with the new source you modified.