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

In org-roam templates, the ${var} syntax allows for the expansion of variables, stored in org-roam-capture--info. For example, during org-roam-insert, the user is prompted for a title. Upon entering a non-existent title, the title key in org-roam-capture--info is set to the provided title. ${title} is then expanded into the provided title during the org-capture process. Any variables that do not contain strings, are prompted for values using completing-read.

After doing this expansion, the org-capture’s template expansion system is used to fill up the rest of the template. You may read up more on this on org-capture’s documentation page.

To illustrate this dual expansion process, take for example the template string: "%<%Y%m%d%H%M%S>-${title}", with the title "Foo". The template is first expanded into %<%Y%m%d%H%M%S>-Foo. Then org-capture expands %<%Y%m%d%H%M%S> with timestamp: e.g. 20200213032037-Foo.

All of the flexibility afforded by Emacs and Org-mode are available. For example, if you want to encode a UTC timestamp in the filename, you can take advantage of org-mode’s %(EXP) template expansion to call format-time-string directly to provide its third argument to specify UTC.

("d" "default" plain (function org-roam--capture-get-point)
     "%?"
     :file-name "%(format-time-string \"%Y-%m-%d--%H-%M-%SZ--${slug}\" (current-time) t)"
     :head "#+title: ${title}\n"
     :unnarrowed t)