README.org

org-roam-citation-keyword-nodes.el

This package synchronizes keywords found in a bibliography (a bibtex file, via citar) with org-roam nodes (the term node is org-roam jargon for a note, a zettel, a single file in the org-roam database).

For each keyword in the bibliography, an org-roam node is created if it does not already exist. In this node a heading is created that contains references to the entries in the bibliography that has the corresponding keyword assigned. If the node already contains a reference (somewhere), the reference will not be added again to the dedicated references heading. The bibliography is never modified.

The quality and usefulness of the result depend on (the quality of the keywords of) your literature database and your org-roam nodes, of course. It is a good idea to review the keywords (or groups, if you used groups in JabRef or similar) before migrating the nodes and references to your existing org-roam database.

This package is more or less the result of my migration from JabRef to citar / org-roam.

Requirements

• Obviously, org-roam is needed. I tested with org-roam v2.2.2 and used emacs’s built-in sqlite database, which is part of GNU Emacs since v29 (I think).
• To parse the bibliography, the package citar is used. I tested with v1.4.0.

Installation

The package is not available via ELPA / MELPA.

To install the package, you may use straight.el. With straight.el, you need to put the following into your config:

(straight-use-package
 '(org-roam-citation-keyword-nodes
   :type git :host github
   :repo "nuthub/org-roam-citation-keyword-nodes"))

Or, if you use straight.el’s version of use-package, you can use something like the following to install this package.

(use-package org-roam-citation-keyword-nodes
  :after roam citar
  :straight (org-roam-citation-keyword-nodes
	     :type git :host github
	     :repo "nuthub/org-roam-citation-keyword-nodes"))

Configuration

This is an example, of how you can configure this package. The examples set the default values, which is not necessary, since the values are already set by default.

(use-package org-roam-citation-keyword-nodes
  :after roam citar
  :straight (org-roam-citation-keyword-nodes
	     :type git :host github
	     :repo "nuthub/org-roam-citation-keyword-nodes")
  :config
  ;; The key (as in key/value) of the bibtex field that contains keywords.
  (setq jf/org-roam-references-keyword-field "keywords")
  ;; The character, the bibtex keyword entries are separated by.
  (setq jf/org-roam-references-keyword-separator ",")
  ;; The key (as in keyboard) of the template to use for new org-roam nodes.
  (setq jf/org-roam-references-capture-template-key "d")
  ;; A fallback template that is used, if the capture template key is nil.
  (setq jf/org-roam-references-capture-fallback-template
   	("d" "default" plain "%?"
	 :target (file+head "%<%Y%m%d%H%M%S>-${slug}.org"
			    "#+title: ${title}\n")
	 :unnarrowed t))
  ;; The org heading that should contain the references added to a keyword node.
  (setq jf/org-roam-references-heading "References")
  ;; The function used to ask the user for confirmation.
  (setq jf/confirmation-function 'y-or-n-p))

Usage

Hints:

• Make a backup of your org-roam database or set org-roam-directory to some sandbox directory
• Make sure, your org-roam-db is in sync with your file system. Run M-x org-roam-db-sync to be sure
• Inspect the results with org-roam-ui and discover relationships in your literature database that you weren’t aware of

Add to the references heading all bibrefs that have a related keyword, but don’t occur anywhere else in the node

• This use case operates on an org-roam node, since it cares for the title, possible aliases and the (configurable) references heading
• Command: M-x jf/org-roam-references-add-related-references

Remove unresolvable citations from buffer

• This use case is useful in all org buffers
• Command: M-x jf/org-roam-references-delete-unresolvable-citations-in-buffer

Remove all bibrefs from references heading, that don’t have a related keyword

• This use case operates on an org-roam node, since it cares for the title, possible aliases and the (configurable) references heading
• Command: M-x jf/org-roam-references-remove-unrelated-references

Add all bibrefs to all org-roam nodes’ reference headings that relate to the bibref’s keywords

• This use case operates on the whole bibliography and org-roam-db
• Command: M-x jf/org-roam-references-add-keywords-to-roam-db

Remove from all nodes’ reference headings those bibrefs that don’t have a related keyword

• This use case operates on the whole bibliography and org-roam-db
• Command: M-x jf/org-roam-references-remove-citations-from-roam-db

Remove references from an org-roam node that doesn’t exist in bibliography

M-x jf/org-roam-references-delete-unresolvable-citations-in-buffer

Remove references from References heading that don’t have a corresponding keyword

M-x jf/org-roam-references-remove-citations-without-related-keyword-in-buffer

Known issues

• ROAM_REFS property is not added to the nodes. This is used by citar-org-roam to quickly find all nodes that relate to a citation. To add this functionality, is a one-liner, but I am not sure, if this is what I really want. This could of course be configurable.
• These are one of my first Emacs Lisp steps (except for configuration things). So code quality may be improvable (suggestions welcome).
• ERT test cases are missing.
• Incompatibility with frames-only-mode.