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:

1. multiple references per note
2. multiple reference notes per file
3. ability to query note citations by reference
4. “live” updating of Citar UI for presence of notes
5. 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.