citar-org-roam

An emacs package to provide tighter Citar and Org-Roam integration.

Features

Out-of-box, Citar provides default support for file-per-note bibliographic notes that are compatible with Org-Roam v2. This package integrates directly with the Org-Roam database, and provides the following additional features to Citar note support:

multiple references per note
multiple reference notes per file
ability to query note citations by reference
“live” updating of Citar UI for presence of notes
support for org-roam capture templates

Screenshot

Installation

This package is available via MELPA.

Configuration

Activating citar-org-roam-mode will configure Citar to use these functions.

(use-package citar-org-roam
  :after (citar org-roam)
  :config (citar-org-roam-mode))

Templates

To change the default note title output, you can modify the citar-org-roam-note-title-template variable:

(setq citar-org-roam-note-title-template "${author} - ${title}")

This will set the title in the org-roam database, and therefore the completion interface.

To format the actual note file, specify which of the org-roam-capture-templates to use for bibliographic note formatting. As an example, with org-roam-capture-templates defined like so:

(setq org-roam-capture-templates
      '(("d" "default" plain
         "%?"
         :target
         (file+head
          "%<%Y%m%d%H%M%S>-${slug}.org"
          "#+title: ${note-title}\n")
         :unnarrowed t)
        ("n" "literature note" plain
         "%?"
         :target
         (file+head
          "%(expand-file-name (or citar-org-roam-subdir \"\") org-roam-directory)/${citar-citekey}.org"
          "#+title: ${citar-citekey} (${citar-date}). ${note-title}.\n#+created: %U\n#+last_modified: %U\n\n")
         :unnarrowed t)))

… if you then want to use your “literature note” template for new bibliographic notes, you can set citar-org-roam-capture-template-key to its key:

(setq citar-org-roam-capture-template-key "n")

In that example template, the note-title template variable includes the formatting noted above for new note titles as specified in citar-org-roam-note-title-template. Note also the template includes some citar-related template variables, including citar-date. This is an example of data passed from citar to the capture template, the details of which you can configure in citar-org-roam-template-fields.

For additional template ideas, please see, and contribute to, the wiki.

Usage

The citar-open-notes and citar-open commands will work as normal, but will use org-roam to open notes.

To define a sub-file node as a bibliographic note (ref node), use citar-org-roam-ref-add to add the ROAM_REF to the node at point.

Beyond that, the only interactive command this package provides is:

citar-org-roam-cited: presents a list of notes that cite the selected references
citar-org-roam-open-current-refs: Opens Citar UI for all cite references associated with the roam-node in the current buffer.