# Minimum configuration of org-roam v2 + org-roam-bibtex for spacemacs users

**URL:** <https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755>\
**Category:** Guides\
**Created:** [July 16, 2021, 3:43pm UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755 "2021-07-16T15:43:02Z")\
**Posts on this page:** 16\
**Page:** 1

<div class="post-metadata">

**Author:** ![giveitacatch](https://avatars.discourse-cdn.com/v4/letter/g/d6d6ee/32.png) [@giveitacatch](https://org-roam.discourse.group/u/giveitacatch)\
**Post date:** [July 16, 2021, 3:43pm UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/1 "2021-07-16T15:43:03Z")

</div>

I would like to write down step-by-step instructions for setting up org-roam v2 and org-roam-bibtex on fresh installed spacemacs.

I am very new to org-roam and emcas in general. As a spacemacs user, I was looking for simple instructions with minimum configurations to have org-roam and org-roam-bibtex running. I didn’t find much information. I though writing down what I have so far might be helpful to others.

Please feel free to give feedback and corrections to make these instructions better.

# My Environment:

- Ubuntu 20.04
- emacs 27.2 (self-compiled)
- spacemacs (latest `develop` 5b3786f)
- org-roam v2 ( `v2` branch f20291f)
- org-roam-bibtex (`org-roam-v2` branch c7f7cb0)

**Note** : Both branches in org-roam and org-roam-bibtex will be merged to `master` and also available on MELPA in the near future.

# Steps

## Preparation

- emacs 27.2 should be installed
- spacemacs should be installed

## Install org-roam

1. Clone the source

2. Configuration under `dotspacemacs/user-config` (taken from The Org-roam v2 Great Migration)

```auto
  (use-package org-roam
    :load-path "/root/org-roam"
    :custom
    (org-roam-directory "~/.emacs.d/private/org-roam") ; replace with your path
    :bind (("C-c n l" . org-roam-buffer-toggle)
           ("C-c n f" . org-roam-node-find))
    ; global-page-break-lines-mode will break the org-roam buffer
    :hook ( org-roam-mode . (lambda () (global-page-break-lines-mode -1)))
    :config
    (org-roam-setup))

```

1. Install `magit` (required for org-roam v2)
  - Enable `git` under `dotspacemacs-configuration-layers`

2. Reload configuration: `SPC f e R` or restart emacs
3. Verify org-roam is working properly
  - `M-x org-roam-version` should return `2.0.0`
  - `M-x org-roam-node-find` can create notes
  - `M-x org-roam-insert` can create links to other notes
  - `M-x org-roam-buffer-toggle` brings up the `*org-roam*` buffer and shows backlinks
  - verify that one can navigate between notes from backlinks
    - If you see `There is no thing at point that could be visited` error, turn off `global-page-break-lines-mode`
    - use `M-m u RET` to open in another window (Any easier key binding?)  
 ![image](https://global.discourse-cdn.com/free1/uploads/orgroam/original/1X/31eca7eee2425aff7b88ed3b321b6e1ce1c509e5.png)

## Install Org-ref and helm-bibtex

1. Enable `bibtex` layer under `dotspacemacs-configuration-layers`
2. Configuration under `dotspacemacs/user-config` (taken from [org-ref](https://github.com/jkitchin/org-ref#configuration))

```auto
    (setq reftex-default-bibliography '("~/org/Zettelkasten/ref.bib"))

    (setq org-ref-bibliography-notes "~/org/ref_notes.org"
          org-ref-default-bibliography '("~/org/Zettelkasten/ref.bib")
          org-ref-pdf-directory "~/bibtex-pdfs/")

    (setq bibtex-completion-bibliography "~/org/Zettelkasten/ref.bib"
          bibtex-completion-library-path "~/org/bibtex-pdfs"
          bibtex-completion-notes-path "~/org/bibtex-notes")

    ; Optional. Open pdf in external viewer.
    (setq bibtex-completion-pdf-open-function
          (lambda (fpath)
            (start-process "open" "*open*" "open" fpath)))

```

1. Verify that bibtex can be added in `ref.bib`
  - `M-x isbn-to-bibtex` to add with isbn, e.g. 0143126563 will give you

```auto
@Book{allen15_gettin,
 author = {Allen, David},
 title = {Getting things done : the art of stress-free productivity},
 year = 2015,
 publisher = {Penguin Books},
 address = {New York, New York},
 isbn = 0143126563,
}

```

  - `M-x doi-add-bibtex-entry` to add with doi, .e.g. 10.1016/j.lrp.2008.09.004
  - Or, paste some bibtex direcly in `ref.bib`

2. Verify that citation can be added insert citation
  - Open any file
  - `M-x helm-bibtex` should bring you a buffer with references you added in previous step
  - `RET` on any reference should insert the `cite:xxxxx` link
  - `C-z` and then `[F9] Edit notes` should bring up a note. Note that this is not yet a note in org-roam.

3. Verify actions on citation link
  - `RET` on `cite:xxxxx` give you list of actions
    - `Open pdf` (Make sure a pdf viewer is installed, e.g. `qpdfview`. Save pdf named after cite key. E.g. `~/org/bibtex-pdfs/allen15_gettin.pdf`)
    - `Add note` (Note org-roam note)

## Install org-roam-bibtex

1. Clone the source
  - I cloned it to `~/.emacs.d/private/org-roam-bibtex`. You can choose wherever.
  - Check out `org-roam-v2`

2. Configuration under `dotspacemacs/user-config` (taken from [org-roam-bibtex](https://github.com/org-roam/org-roam-bibtex/tree/org-roam-v2#spacemacs))

```auto
    (use-package org-roam-bibtex
      :after org-roam
      :load-path "~/.emacs.d/private/org-roam-bibtex/"
      :hook (org-roam-mode . org-roam-bibtex-mode)
      :config
      (require 'org-ref)) ; optional: if Org Ref is not loaded anywhere else, load it here

```

1. Verify that `edit note` bring up org-roam notes
  - Open any org-roam file
  - `M-x org-roam-buffer-toggle`
  - `M-x helm-bibtex` → `C-z` → `Edit notes` should bring you to a org-roam note with `ID` and `ROAM_REFS` pre-configured
  - `RET` on `cite:xxxxx` and then `Open notes` should bring you to the same org-roam note
  - `M-x orb-insert-link` shoud insert a link  
(This somehow doesn’t work on some references with error `helm-M-x-execute-command: Invalid capture template format: (d default plain %? :if-new (file+head %<%Y%m%d%H%M%S>-${slug}.org #+title: ${title}) :unnarrowed t)`. Haven’t figured out yet.)
  - `M-x org-roam-buffer-toggle` shows backlinks and reflinks for those reference notes

That is all. Now you should have org-roam v2 and org-roam-bibtex working 🙂

# Remaining issues

- I tried to configure the `*org-roam*` buffer window location (taken from Hitchhiker’s Rough Guide to Org roam V2) but it somwhow does not work.

```auto
  (add-to-list 'display-buffer-alist
        '(;; Left side window
          (".org-roam.*"
           (display-buffer-in-side-window)
           (window-width . 0.25)
           (side . left)
           (slot . 0))))

```

- To make `Edit notes` in `helm-bibtex` works as configred by `org-roam-bibtex`, I need to run `M-x org-roam-buffer-toggle` first.

# Feedbacks and corrections are welcome

As said, I am just beginning with my journey with emacs and org-roam. If any of the steps above can be done in a more correct or elegant manner, please do give your feedback and make these steps better and easier for other beginners like me.

---

<div class="post-metadata">

**Author:** ![gnohz](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/gnohz/32/803_2.png) [@gnohz](https://org-roam.discourse.group/u/gnohz)\
**Post date:** [July 18, 2021, 3:34am UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/2 "2021-07-18T03:34:47Z")

</div>

Thanks so much for writing this up.  
I am just confusing with the setups for org-ref and helm-bibtex. For example, do we really need to set the notes/path/etc in both places, like

> [@giveitacatch](#):
>
> `setq org-ref-bibliography-notes "~/org/ref_notes.org"`

> [@giveitacatch](#):
>
> `bibtex-completion-notes-path "~/org/bibtex-notes"`

I used org-ref without orb and all the notes are in one org file. With orb, I think the point is to have each bib note for each entry. So can we delete the

> [@giveitacatch](#):
>
> `org-ref-bibliography-notes "~/org/ref_notes.org"`

in the setup?

---

<div class="post-metadata">

**Author:** ![cool\_ran](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/cool_ran/32/130_2.png) [@cool\_ran](https://org-roam.discourse.group/u/cool_ran)\
**Post date:** [July 18, 2021, 5:11pm UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/3 "2021-07-18T17:11:53Z")

</div>

> [@giveitacatch](#):
>
> but it somwhow does not work.

@nobiot write [something](https://github.com/org-roam/org-roam/wiki/Hitchhiker%27s-Rough-Guide-to-Org-roam-V2/_compare/4773e04%5E...4773e04) that works.

---

<div class="post-metadata">

**Author:** ![giveitacatch](https://avatars.discourse-cdn.com/v4/letter/g/d6d6ee/32.png) [@giveitacatch](https://org-roam.discourse.group/u/giveitacatch)\
**Post date:** [July 18, 2021, 10:23pm UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/4 "2021-07-18T22:23:39Z")

</div>

So with this under `dotspacemacs/user-config`

```auto
;; for org-roam-buffer-toggle
;; Recommendation in the official manual
(add-to-list 'display-buffer-alist
               '("\\*org-roam\\*"
                  (display-buffer-in-direction)
                  (direction . right)
                  (window-width . 0.33)
                  (window-height . fit-window-to-buffer)))

```

I did the following

- open a note with the only window
- call `org-roam-buffer-toggle`
- get a window open in the bottom with size of ~1/10 of the original window height with buffer `*org-roam*`

That does not seem to work as expected. Does it work for you?

---

<div class="post-metadata">

**Author:** ![giveitacatch](https://avatars.discourse-cdn.com/v4/letter/g/d6d6ee/32.png) [@giveitacatch](https://org-roam.discourse.group/u/giveitacatch)\
**Post date:** [July 18, 2021, 10:55pm UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/5 "2021-07-18T22:55:33Z")

</div>

Hi, no, we do not need that at the end when `org-roam-bibtex` is properly set up. You are right that the notes should go to each entry with `org-roam-bibtex` context. I just personally find it easier to do incremental configuration to know that I am on the right track.

Maybe we can give a tl;dr summary without those config you mentioned and all the detailed verification steps? Does it make sense?

I do not really know how to edit the post…

---

<div class="post-metadata">

**Author:** ![gnohz](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/gnohz/32/803_2.png) [@gnohz](https://org-roam.discourse.group/u/gnohz)\
**Post date:** [July 19, 2021, 3:49am UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/6 "2021-07-19T03:49:17Z")

</div>

Yes, I am looking for a cleaner setup in Spacemacs. Maybe a private layer is a way to go.  
Another thing I found is that you use “use-package” in the Spacemacs user-config, and it may work but there are some redundant setups there since Spacemacs’ org layer has done some for you. In other words, it is suggested (somewhere) not to use “use-package” in the Spacemacs user-config. Again, a private layer might be better choice.

---

<div class="post-metadata">

**Author:** ![gnohz](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/gnohz/32/803_2.png) [@gnohz](https://org-roam.discourse.group/u/gnohz)\
**Post date:** [July 20, 2021, 3:51pm UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/7 "2021-07-20T15:51:32Z")

</div>

I created a private layer in Spacemacs, please see [https://org-roam.discourse.group/t/v2-and-spacemacs/1676/4?u=gnohz](https://org-roam.discourse.group/t/v2-and-spacemacs/1676/4)

---

<div class="post-metadata">

**Author:** ![giveitacatch](https://avatars.discourse-cdn.com/v4/letter/g/d6d6ee/32.png) [@giveitacatch](https://org-roam.discourse.group/u/giveitacatch)\
**Post date:** [July 24, 2021, 1:15am UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/8 "2021-07-24T01:15:36Z")

</div>

Since both [org-roam](https://melpa.org/#/org-roam) and [org-roam-bibtex](https://melpa.org/#/org-roam-bibtex) are now updated on the MELPA, there is no need to clone and use `:load-path` in `use-package` anymore. Instead, include `org-roam` and `org-roam-bibtex` in `dotspacemacs-additional-packages`.

---

<div class="post-metadata">

**Author:** ![doubleloop](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/doubleloop/32/99_2.png) [@doubleloop](https://org-roam.discourse.group/u/doubleloop)\
**Post date:** [July 26, 2021, 7:40pm UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/9 "2021-07-26T19:40:45Z")

</div>

Noting that there is a PR soon to be merged to update the Spacemacs org layer to use org-roam v2: [Rename commands for org-roam v2 compatibility by kappa · Pull Request #14930 · syl20bnr/spacemacs · GitHub](https://github.com/syl20bnr/spacemacs/pull/14930)

---

<div class="post-metadata">

**Author:** ![japhir](https://avatars.discourse-cdn.com/v4/letter/j/b2d939/32.png) [@japhir](https://org-roam.discourse.group/u/japhir)\
**Post date:** [July 28, 2021, 9:24am UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/10 "2021-07-28T09:24:37Z")

</div>

Hi! @giveitacatch, I’m trying to get this to work using just MELPA packages for org-roam v2, org-ref, and org-roam-bibtex, but it doesn’t work: I’ve set it up [like this](https://github.com/japhir/ArchConfigs/blob/master/myinit.org#org-roam-bibtex) with [this org-roam config](https://github.com/japhir/ArchConfigs/blob/master/myinit.org#org-roam) but when I C-c C-o on e.g. cite:Sexton2006 and hit n for note action, I get a `org-ref-open-notes-at-point: Wrong type argument: listp, "Sexton2006"`.  
After I enable `org-roam-bibtex-mode` with M-x and try again, it does create a new file but seems to ignore my `org-roam-capture-ref-templates` that I set with the `r` key, and simply inserts a default `org-roam-capture-templates` one below in stead of my desired template.

Any idea how to get this going?  
I’m using: org-roam 2.0.0, org-ref 1.1.1, org-roam-bibtex 0.6.0 (which requires `;; Package-Requires: ((emacs "27.2") (org-roam "2.0.0") (bibtex-completion "2.0.0") (org-ref "1.1.1"))` so I think it’s the right one).

---

<div class="post-metadata">

**Author:** ![giveitacatch](https://avatars.discourse-cdn.com/v4/letter/g/d6d6ee/32.png) [@giveitacatch](https://org-roam.discourse.group/u/giveitacatch)\
**Post date:** [August 5, 2021, 10:37pm UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/11 "2021-08-05T22:37:24Z")

</div>

Hi @japhir , I am really not an expert in the templates. I can only share my config with you.

```auto
  (use-package org-roam
    :hook ( org-roam-mode . (lambda () (global-page-break-lines-mode -1)))
    :config
    (org-roam-setup))
    (setq org-roam-capture-templates
        '(("d" "default" plain
            "%?"
          :if-new (file+head "${slug}.org"
                              "#+title: ${title}\n")
          :immediate-finish t
          :unnarrowed t)
          ("b" "bibliography reference" plain "%?"
           :if-new
           (file+head "references/${citekey}.org" "#+title: ${title}\n")
           :unnarrowed t)
          ("n" "bibliography reference + noter" plain
           (file "~/org/templates/orb_template_noter.org")
           :if-new
           (file+head "references/${citekey}.org" "#+title: ${title}\n")
           )
          ))

```

Nothing really special here. Just using the basic templates. The `orb_template_noter.org` is directly taken from [Org Roam BibTeX manual](https://github.com/org-roam/org-roam-bibtex/blob/master/doc/orb-manual.org#org-noter-integration-special-treatment-of-the-file-keyword):

```auto
- tags ::
- keywords :: %^{keywords}

* %^{title}
:PROPERTIES:
:Custom_ID: %^{citekey}
:URL: %^{url}
:AUTHOR: %^{author-or-editor}
:NOTER_DOCUMENT: %^{file} 
:NOTER_PAGE:
:END:

```

I always create the note from `helm-bibtex`. There I select the entry and then `C-z` → `[f9] Edit notes`. With that a normal capture windows will open and I can select from the templates I defined in the config above. Both `bibliography reference`, with or without the noter, will create the note with `ROAM_REFS` properly filled. Afterwards if I `RET`, or `C-c C-o` on the `cite:something` in any of the note, I can select `3. Open notes` and that will bring up the bibliography reference note captured in previous step.

Hope this helps and sorry for the late reply.

Btw, the PR mentioned by @doubleloop is merged. Has anyone tried the layer already?

---

<div class="post-metadata">

**Author:** ![japhir](https://avatars.discourse-cdn.com/v4/letter/j/b2d939/32.png) [@japhir](https://org-roam.discourse.group/u/japhir)\
**Post date:** [August 6, 2021, 1:27pm UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/12 "2021-08-06T13:27:26Z")

</div>

Ah nice! I was confused because there is also a `org-roam-capture-ref-templates`, and because both @jethro and @zaeph have commented out their org-roam-bibtex sections in their configs ([zaeph’s config line](https://github.com/zaeph/.emacs.d/blob/8243cd8c74775387e011de679f041ca8e3cff41a/init.el#L3956) and [jethro’s config](https://github.com/jethrokuan/dots/blob/master/.doom.d/packages.el#L10).

I kind of like having few capture templates so that it can select the right one contextually, but I’m not advanced enough to know how to do that yet ;-).

---

<div class="post-metadata">

**Author:** ![doubleloop](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/doubleloop/32/99_2.png) [@doubleloop](https://org-roam.discourse.group/u/doubleloop)\
**Post date:** [August 7, 2021, 6:50am UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/13 "2021-08-07T06:50:06Z")

</div>

> [@giveitacatch](#):
>
> Btw, the PR mentioned by @doubleloop is merged. Has anyone tried the layer already?

I’m using the layer and it’s working fine for me so far.

(I’m not using org-roam-bibtex though, so I can’t comment as to whether it works well with this.)

---

<div class="post-metadata">

**Author:** ![wilya](https://avatars.discourse-cdn.com/v4/letter/w/94ad74/32.png) [@wilya](https://org-roam.discourse.group/u/wilya)\
**Post date:** [September 9, 2021, 7:43am UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/14 "2021-09-09T07:43:05Z")

</div>

> [@giveitacatch](#):
>
> ```auto
> :hook (org-roam-mode . org-roam-bibtex-mode)
> 
> ```

as reported by @mshevchuk, quote:

> In Org-roam v2, `org-roam-mode` is not longer a minor mode, so doing so makes little sense. Instead, one can put `(org-roam-bibtex-mode +1)` in the `:config` section of `use-package org-roam` :

see: [Minimal setup for helm-bibtex, org-roam v2, org-roam-bibtex](https://org-roam.discourse.group/t/minimal-setup-for-helm-bibtex-org-roam-v2-org-roam-bibtex/1971/2)

---

<div class="post-metadata">

**Author:** ![giveitacatch](https://avatars.discourse-cdn.com/v4/letter/g/d6d6ee/32.png) [@giveitacatch](https://org-roam.discourse.group/u/giveitacatch)\
**Post date:** [September 9, 2021, 1:49pm UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/15 "2021-09-09T13:49:01Z")

</div>

You are right. Thanks!

---

<div class="post-metadata">

**Author:** ![minyez](https://avatars.discourse-cdn.com/v4/letter/m/e9a140/32.png) [@minyez](https://org-roam.discourse.group/u/minyez)\
**Post date:** [April 25, 2022, 3:01am UTC](https://org-roam.discourse.group/t/minimum-configuration-of-org-roam-v2-org-roam-bibtex-for-spacemacs-users/1755/16 "2022-04-25T03:01:06Z")

</div>

Hi,

Have you solved this problem? With Doom Emacs and use-package, I put the `add-to-list` under `:config` session and it works, while it doesn’t under `:init`. Hope it helps.