citar-org-roam

citar-org-roam copied to clipboard

[[https://melpa.org/#/citar-org-roam][file:https://melpa.org/packages/citar-org-roam-badge.svg]]

• 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

#+CAPTION: citar-open command with citar-org-roam [[file:images/open-screenshot.png]]

** Installation

This package is available via [[https://melpa.org/#/citar-org-roam][MELPA]].

** Configuration

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

#+begin_src emacs-lisp (use-package citar-org-roam :after (citar org-roam) :config (citar-org-roam-mode)) #+end_src

*** Templates

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

#+begin_src emacs-lisp (setq citar-org-roam-note-title-template "${author} - ${title}") #+end_src

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:

#+begin_src emacs-lisp (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))) #+end_src

... 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:

#+begin_src emacs-lisp (setq citar-org-roam-capture-template-key "n") #+end_src

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 [[https://github.com/emacs-citar/citar-org-roam/wiki][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.