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
-
Clone the source
- I cloned it to
~/.emacs.d/private/org-roam
. You can choose wherever. - Check out
v2
- I cloned it to
-
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))
- Install
magit
(required for org-roam v2)- Enable
git
underdotspacemacs-configuration-layers
- Enable
- Reload configuration:
SPC f e R
or restart emacs - Verify org-roam is working properly
-
M-x org-roam-version
should return2.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 offglobal-page-break-lines-mode
- use
M-m u RET
to open in another window (Any easier key binding?)
- If you see
-
Install Org-ref and helm-bibtex
- Enable
bibtex
layer underdotspacemacs-configuration-layers
- 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)))
- 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
-
- 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 thecite: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.
- Verify actions on citation link
-
RET
oncite: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
- Clone the source
- I cloned it to
~/.emacs.d/private/org-roam-bibtex
. You can choose wherever. - Check out
org-roam-v2
- I cloned it to
- 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
- 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 withID
andROAM_REFS
pre-configured -
RET
oncite:xxxxx
and thenOpen 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 errorhelm-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
inhelm-bibtex
works as configred byorg-roam-bibtex
, I need to runM-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.