Org-roam Template Expansion ​

Org-roam’s template definitions also extend org-capture’s template syntax, to allow prefilling of strings. We have seen a glimpse of this in Template Walkthrough.

Org-roam provides the ${foo} syntax for substituting variables with known strings. ${foo}’s substitution is performed as follows:

  1. If foo is a function, foo is called with the current node as its argument.
  2. Else if org-roam-node-foo is a function, foo is called with the current node as its argument. The org-roam-node- prefix defines many of Org-roam’s node accessors such as org-roam-node-title and org-roam-node-level.
  3. Else look up org-roam-capture--info for foo. This is an internal variable that is set before the capture process begins.
  4. If none of the above applies, read a string using completing-read.
    1. Org-roam also provides the ${foo=default_val} syntax, where if a default value is provided, will be the initial value for the foo key during minibuffer completion.

One can check the list of available keys for nodes by inspecting the org-roam-node struct. At the time of writing, it is:

emacs-lisp
(cl-defstruct (org-roam-node (:constructor org-roam-node-create)
                             (:copier nil))
  "A heading or top level file with an assigned ID property."
  file file-hash file-atime file-mtime
  id level point todo priority scheduled deadline title properties olp
  tags aliases refs)

This makes ${file}, ${file-hash} etc. all valid substitutions.