Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/emacs-citar/citar-org-roam

citar/org-roam integration
https://github.com/emacs-citar/citar-org-roam

Last synced: 2 months ago
JSON representation

citar/org-roam integration

Awesome Lists containing this project

README 

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