5.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)