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

[giveitacatch]

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

   • I cloned it to ~/.emacs.d/private/org-roam. You can choose wherever.
   • Check out v2

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

  (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))

3. Install magit (required for org-roam v2)
   • Enable git under dotspacemacs-configuration-layers
4. Reload configuration: SPC f e R or restart emacs
5. 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?)
       
       

Install Org-ref and helm-bibtex

1. Enable bibtex layer under dotspacemacs-configuration-layers
2. Configuration under dotspacemacs/user-config (taken from org-ref)

    (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)))

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

   @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
4. 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.
5. 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)

    (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

3. 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.

  (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.

[gnohz]

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?

[cool_ran]

@giveitacatch

but it somwhow does not work.

@nobiot write something that works.

[giveitacatch]

So with this under dotspacemacs/user-config

;; 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?

[giveitacatch]

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…

[gnohz]

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.

[gnohz]

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

[giveitacatch]

Since both org-roam and 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.

[doubleloop]

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

[japhir]

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 with this org-roam config 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).

[giveitacatch]

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

  (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:

- 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?

[japhir]

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 and jethro’s config.

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 ;-).

[doubleloop]

@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.)

[wilya]

@giveitacatch

      :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

[giveitacatch]

You are right. Thanks!

[minyez]

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.