Org Roam BibTeX (ORB) is an Org Roam extension that integrates Org Roam with bibliography/citation management software: Org Ref, Helm and Ivy BibTeX and Citar.
It allows users to manage their bibliographical notes using Org Roam and access
the notes in org-roam-directory
via helm-bibtex
, ivy-bibtex
,
citar-open-notes
or by activation Org-ref cite:
links and Org-cite
citations.
See also a somewhat outdated video demonstration of Org Roam v0.2.1
Here is a selection of articles that you may find interesting.
Org Roam BibTeX has been upgraded to v0.6, which is compatible with Org-roam
v2. Please read carefully this README file and the
manual and adjust your configuration files accordingly.
In particular, pay attention that the variable orb-templates
has been
deprecated in favour of org-roam-capture-templates
, which in Org-roam v2 has
a different list structure. Consult the manual for more
details
Org Roam BibTeX v0.5.2 is the last version of ORB that works with Org-roam v1.
It can be found on the branch orb-v0.5
.
org-roam-bibtex
is in Alpha.
This means that a lot of things may change in the future (e.g. renaming variables, rewriting functions). As a result, the package will be unstable for a while. This will change when we release v1.0, but for now, you will have to be on the lookout for a few things:
Please read carefully this section before installing Org Roam BibTeX. We are glad to help you in case something does not work as expected. However, we kindly ask you to follow these simple rules when asking for help:
this command
,
then I run that command
, and finally this one
. I expect this
to happen
but instead happens that
. Here is my configuration
."Keep in mind that ORB is under active development and the configuration snippets that you might have found somewhere in the Internet may be outdated and be the actual cause your errors. It is therefore highly recommended to use this README file, the manual and the Emacs built-in docstrings as primary documentation sources.
Org Roam BibTeX depends on Org Roam and BibTeX Completion. Users cloning ORB directly from GitHub also need to install the above packages. When installing ORB with a package manager (MELPA) or from within a configuration framework (Doom, Spacemacs), no additional steps are required.
Some parts of Org Roam BibTeX will not work without:
Org Ref — namely when Org-ref v2 or v3 citation citation links are used as ROAM_REFS. Org-roam and ORB now support the built-in Org-cite citation keys (Org mode version 9.5+), so Org-ref is not a strict requirement anymore.
Helm/Ivy-bibtex — these packages are required by Org-ref and provide native interfaces for Bibtex-completion, although the latter can be installed separately without them.
Citar — this package provides an extended support for Org-cite citations. You will need to install the companion package Citar-org-roam, and configure it as described here.
AnyStyle CLI — ORB PDF Scrapper requires this external tool, see Orb Anystyle for more details.
ORB offers basic completion functions based on Emacs native completion interfaces, but user experience can be enhanced with Helm, Ivy and Hydra packages.
Users of Projectile and Persp-mode will be pleased to learn that ORB can automatically switch perspective to the Org Roam project when creating a note.
package.el
)The package is on MELPA.
Install org-roam-bibtex
:
a) using package.el
:
M-x package-install RET org-roam-bibtex RET
b) Alternatively, install it with M-x package-list-packages
.
Load and configure the package in your init-file:
a) with use-package
:
(use-package org-roam-bibtex
:after org-roam
:config
(require 'org-ref)) ; optional: if using Org-ref v2 or v3 citation links
b) Alternatively, require the package if you don't use use-package
:
(require 'org-ref) ; optional: if using Org-ref v2 or v3 citation links
(require 'org-roam-bibtex)
You can also clone the repository somewhere in your load-path
. If you would
like to assist with development, this is the way to go.
To do that:
Create a directory where you’d like to clone the repository, e.g. mkdir ~/projects
.
cd ~/projects
git clone https://github.com/org-roam/org-roam-bibtex.git
Load and configure the package:
a) with use-package
:
(use-package org-roam-bibtex
:after org-roam
:load-path "~/projects/org-roam-bibtex/" ; Modify with your own path where you cloned the repository
:config
(require 'org-ref)) ; optional: if using Org-ref v2 or v3 citation links
b) Alternatively, if you don't use use-package
:
(require 'org-ref) ; optional: if using Org-ref v2 or v3 citation links
(add-to-list 'load-path "~/projects/org-roam-bibtex/") ; Modify with your own path where you cloned the repository
(require 'org-roam-bibtex)
If you have a private org-roam
layer, modify it as follows:
(defconst org-roam-packages
'(org-roam org-roam-bibtex))
;; add this after `org-roam/init-org-roam`:
(defun org-roam/init-org-roam-bibtex ()
(use-package org-roam-bibtex
:after org-roam
:config
(require 'org-ref)) ; optional: if using Org-ref v2 or v3 citation links
If you don't have a private org-roam
layer, configure it first, see examples
here
and
here.
Recent versions of Spacemacs ship with a built-in org-roam
support, so you
won't need a private org-roam
layer. You still need a private layer for
org-roam-bibtex
. Consult Spacemacs documentation on how to create one, or
use the approach described in the above mentioned resources.
$DOOMDIR/packages.el
:(package! org-roam-bibtex
:recipe (:host github :repo "org-roam/org-roam-bibtex"))
;; When using org-roam via the `+roam` flag
(unpin! org-roam)
;; When using bibtex-completion via the `biblio` module
(unpin! bibtex-completion helm-bibtex ivy-bibtex)
$DOOMDIR/config.el
: (use-package! org-roam-bibtex
:after org-roam
:config
(require 'org-ref)) ; optional: if using Org-ref v2 or v3 citation links
bin/doom sync -u
and restart Emacs.org-roam-bibtex-mode
Call interactively org-roam-bibtex-mode
or arrange your init file to perform
this automatically.
You can now access your bibliographical notes in org-roam-directory
with
helm-bibtex
/ivy-bibtex
or by opening org-ref
links. ORB modifies the
behaviour of the above packages to make them use orb-edit-note
instead of
their default note-management commands. To get their default behaviour back,
disable org-roam-bibtex-mode
.
orb-note-actions
Type M-x orb-note-actions
to easily access additional commands useful in
note's context. These commands are run with the note's BibTeX key as an
argument. The key is taken from the :ROAM_REFS:
file or heading property.
orb-insert-link
Select a bibliography entry and insert a link to a note associated with it. If
the note does not exist yet, create it. Similar to org-roam-node-insert
, if a
region is selected, it becomes the link description.
org-roam-buffer
sectionsThree bibliography related org-roam-buffer
sections are available.
They may be added to the org-roam-mode-sections
variable. These
are:
orb-section-reference
displays a formatted reference for the
current entry.orb-section-abstract
displays the abstract (if available) of the
current entry.orb-section-file
displays a link to open the attached file, if
such file exists.See the Org Roam BibTeX Manual for configuration options and advanced usage.
For help, support, or if you just want to hang out with us, you can find us here:
Changelog is being maintained here.
Copyright © 2020-2022 Mykhailo Shevchuk
Copyright © 2020 Leo Vivier
And contributros.
Distributed under the GNU General Public License , see LICENSE.