mirror of
https://github.com/org-roam/org-roam
synced 2025-08-01 12:17:21 -05:00
Add docstring for Org-roam capture templates
This commit is contained in:
Jethro Kuan
@ -59,12 +59,275 @@ during the Org-roam capture process.")
|
|||||||
:if-new (file+head "%<%Y%m%d%H%M%S>-${slug}.org"
|
:if-new (file+head "%<%Y%m%d%H%M%S>-${slug}.org"
|
||||||
"#+title: ${title}\n")
|
"#+title: ${title}\n")
|
||||||
:unnarrowed t))
|
:unnarrowed t))
|
||||||
"Capture templates for Org-roam.
|
"Templates for the creation of new entries within Org-roam.
|
||||||
|
|
||||||
TODO: Document this"
|
Each entry is a list with the following items:
|
||||||
|
|
||||||
|
keys The keys that will select the template, as a string, characters only,
|
||||||
|
for example \"a\" for a template to be selected with a single key, or \"bt\"
|
||||||
|
for selection with two keys. When using several keys, keys using the same prefix
|
||||||
|
must be together in the list and preceded by a 2-element entry
|
||||||
|
explaining the prefix key, for example:
|
||||||
|
|
||||||
|
(\"b\" \"Templates for marking stuff to buy\")
|
||||||
|
|
||||||
|
The \"C\" key is used by default for quick access to the customization of the template
|
||||||
|
variable. But if you want to use that key for a template, you can.
|
||||||
|
|
||||||
|
description A short string describing the template, which will be shown during selection.
|
||||||
|
|
||||||
|
type The type of entry. Valid types are:
|
||||||
|
entry an Org node, with a headline. Will be filed
|
||||||
|
as the child of the target entry or as a
|
||||||
|
top-level entry. Its default template is:
|
||||||
|
\"* %?\n %a\"
|
||||||
|
item a plain list item, will be placed in the
|
||||||
|
first plain list at the target location.
|
||||||
|
Its default template is:
|
||||||
|
\"- %?\"
|
||||||
|
checkitem a checkbox item. This differs from the
|
||||||
|
plain list item only in so far as it uses a
|
||||||
|
different default template. Its default
|
||||||
|
template is:
|
||||||
|
\"- [ ] %?\"
|
||||||
|
table-line a new line in the first table at target location.
|
||||||
|
Its default template is:
|
||||||
|
\"| %? |\"
|
||||||
|
plain text to be inserted as it is.
|
||||||
|
|
||||||
|
template The template for creating the capture item.
|
||||||
|
If it is an empty string or nil, a default template based on
|
||||||
|
the entry type will be used (see the \"type\" section above).
|
||||||
|
Instead of a string, this may also be one of:
|
||||||
|
|
||||||
|
(file \"/path/to/template-file\")
|
||||||
|
(function function-returning-the-template)
|
||||||
|
|
||||||
|
in order to get a template from a file, or dynamically
|
||||||
|
from a function.
|
||||||
|
|
||||||
|
The template contains a compulsory :if-new property. This determines the
|
||||||
|
location of the new node. The :if-new property contains a list, supporting
|
||||||
|
the following options:
|
||||||
|
|
||||||
|
(file \"path/to/file\")
|
||||||
|
The file will be created, and prescribed an ID.
|
||||||
|
|
||||||
|
(file+head \"path/to/file\" \"head content\")
|
||||||
|
The file will be created, prescribed an ID, and head content will be
|
||||||
|
inserted into the file.
|
||||||
|
|
||||||
|
(file+olp \"path/to/file\" '(\"h1\" \"h2\"))
|
||||||
|
The file will be created, prescribed an ID. The OLP (h1, h2) will be created,
|
||||||
|
and the point placed after.
|
||||||
|
|
||||||
|
(file+head+olp \"path/to/file\" \"head content\" '(\"h1\" \"h2\"))
|
||||||
|
The file will be created, prescribed an ID. Head content will be inserted at the
|
||||||
|
start of the file. The OLP (h1, h2) will be created, and the point placed after.
|
||||||
|
|
||||||
|
The rest of the entry is a property list of additional options. Recognized
|
||||||
|
properties are:
|
||||||
|
|
||||||
|
:prepend Normally newly captured information will be appended at
|
||||||
|
the target location (last child, last table line,
|
||||||
|
last list item...). Setting this property will
|
||||||
|
change that.
|
||||||
|
|
||||||
|
:immediate-finish When set, do not offer to edit the information, just
|
||||||
|
file it away immediately. This makes sense if the
|
||||||
|
template only needs information that can be added
|
||||||
|
automatically.
|
||||||
|
|
||||||
|
:jump-to-captured When set, jump to the captured entry when finished.
|
||||||
|
|
||||||
|
:empty-lines Set this to the number of lines that should be inserted
|
||||||
|
before and after the new item. Default 0, only common
|
||||||
|
other value is 1.
|
||||||
|
|
||||||
|
:empty-lines-before Set this to the number of lines that should be inserted
|
||||||
|
before the new item. Overrides :empty-lines for the
|
||||||
|
number lines inserted before.
|
||||||
|
|
||||||
|
:empty-lines-after Set this to the number of lines that should be inserted
|
||||||
|
after the new item. Overrides :empty-lines for the
|
||||||
|
number of lines inserted after.
|
||||||
|
|
||||||
|
:clock-in Start the clock in this item.
|
||||||
|
|
||||||
|
:clock-keep Keep the clock running when filing the captured entry.
|
||||||
|
|
||||||
|
:clock-resume Start the interrupted clock when finishing the capture.
|
||||||
|
Note that :clock-keep has precedence over :clock-resume.
|
||||||
|
When setting both to t, the current clock will run and
|
||||||
|
the previous one will not be resumed.
|
||||||
|
|
||||||
|
:time-prompt Prompt for a date/time to be used for date/week trees
|
||||||
|
and when filling the template.
|
||||||
|
|
||||||
|
:tree-type When `week', make a week tree instead of the month-day
|
||||||
|
tree. When `month', make a month tree instead of the
|
||||||
|
month-day tree.
|
||||||
|
|
||||||
|
:unnarrowed Do not narrow the target buffer, simply show the
|
||||||
|
full buffer. Default is to narrow it so that you
|
||||||
|
only see the new stuff.
|
||||||
|
|
||||||
|
:table-line-pos Specification of the location in the table where the
|
||||||
|
new line should be inserted. It should be a string like
|
||||||
|
\"II-3\", meaning that the new line should become the
|
||||||
|
third line before the second horizontal separator line.
|
||||||
|
|
||||||
|
:kill-buffer If the target file was not yet visited by a buffer when
|
||||||
|
capture was invoked, kill the buffer again after capture
|
||||||
|
is finalized.
|
||||||
|
|
||||||
|
:no-save Do not save the target file after finishing the capture.
|
||||||
|
|
||||||
|
The template defines the text to be inserted. Often this is an
|
||||||
|
Org mode entry (so the first line should start with a star) that
|
||||||
|
will be filed as a child of the target headline. It can also be
|
||||||
|
freely formatted text. Furthermore, the following %-escapes will
|
||||||
|
be replaced with content and expanded:
|
||||||
|
|
||||||
|
%[pathname] Insert the contents of the file given by
|
||||||
|
`pathname'. These placeholders are expanded at the very
|
||||||
|
beginning of the process so they can be used to extend the
|
||||||
|
current template.
|
||||||
|
%(sexp) Evaluate elisp `(sexp)' and replace it with the results.
|
||||||
|
Only placeholders pre-existing within the template, or
|
||||||
|
introduced with %[pathname] are expanded this way. Since this
|
||||||
|
happens after expanding non-interactive %-escapes, those can
|
||||||
|
be used to fill the expression.
|
||||||
|
%<...> The result of format-time-string on the ... format specification.
|
||||||
|
%t Time stamp, date only. The time stamp is the current time,
|
||||||
|
except when called from agendas with `\\[org-agenda-capture]' or
|
||||||
|
with `org-capture-use-agenda-date' set.
|
||||||
|
%T Time stamp as above, with date and time.
|
||||||
|
%u, %U Like the above, but inactive time stamps.
|
||||||
|
%i Initial content, copied from the active region. If
|
||||||
|
there is text before %i on the same line, such as
|
||||||
|
indentation, and %i is not inside a %(sexp), that prefix
|
||||||
|
will be added before every line in the inserted text.
|
||||||
|
%a Annotation, normally the link created with `org-store-link'.
|
||||||
|
%A Like %a, but prompt for the description part.
|
||||||
|
%l Like %a, but only insert the literal link.
|
||||||
|
%L Like %l, but without brackets (the link content itself).
|
||||||
|
%c Current kill ring head.
|
||||||
|
%x Content of the X clipboard.
|
||||||
|
%k Title of currently clocked task.
|
||||||
|
%K Link to currently clocked task.
|
||||||
|
%n User name (taken from the variable `user-full-name').
|
||||||
|
%f File visited by current buffer when org-capture was called.
|
||||||
|
%F Full path of the file or directory visited by current buffer.
|
||||||
|
%:keyword Specific information for certain link types, see below.
|
||||||
|
%^g Prompt for tags, with completion on tags in target file.
|
||||||
|
%^G Prompt for tags, with completion on all tags in all agenda files.
|
||||||
|
%^t Like %t, but prompt for date. Similarly %^T, %^u, %^U.
|
||||||
|
You may define a prompt like: %^{Please specify birthday}t.
|
||||||
|
The default date is that of %t, see above.
|
||||||
|
%^C Interactive selection of which kill or clip to use.
|
||||||
|
%^L Like %^C, but insert as link.
|
||||||
|
%^{prop}p Prompt the user for a value for property `prop'.
|
||||||
|
A default value can be specified like this:
|
||||||
|
%^{prop|default}p.
|
||||||
|
%^{prompt} Prompt the user for a string and replace this sequence with it.
|
||||||
|
A default value and a completion table can be specified like this:
|
||||||
|
%^{prompt|default|completion2|completion3|...}.
|
||||||
|
%? After completing the template, position cursor here.
|
||||||
|
%\\1 ... %\\N Insert the text entered at the nth %^{prompt}, where N
|
||||||
|
is a number, starting from 1.
|
||||||
|
|
||||||
|
Apart from these general escapes, you can access information specific to
|
||||||
|
the link type that is created. For example, calling `org-capture' in emails
|
||||||
|
or in Gnus will record the author and the subject of the message, which you
|
||||||
|
can access with \"%:from\" and \"%:subject\", respectively. Here is a
|
||||||
|
complete list of what is recorded for each link type.
|
||||||
|
|
||||||
|
Link type | Available information
|
||||||
|
------------------------+------------------------------------------------------
|
||||||
|
bbdb | %:type %:name %:company
|
||||||
|
vm, wl, mh, mew, rmail, | %:type %:subject %:message-id
|
||||||
|
gnus | %:from %:fromname %:fromaddress
|
||||||
|
| %:to %:toname %:toaddress
|
||||||
|
| %:fromto (either \"to NAME\" or \"from NAME\")
|
||||||
|
| %:date %:date-timestamp (as active timestamp)
|
||||||
|
| %:date-timestamp-inactive (as inactive timestamp)
|
||||||
|
gnus | %:group, for messages also all email fields
|
||||||
|
eww, w3, w3m | %:type %:url
|
||||||
|
info | %:type %:file %:node
|
||||||
|
calendar | %:type %:date
|
||||||
|
|
||||||
|
When you need to insert a literal percent sign in the template,
|
||||||
|
you can escape ambiguous cases with a backward slash, e.g., \\%i.
|
||||||
|
|
||||||
|
In addition to all of the above, Org-roam supports additional
|
||||||
|
substitutions within its templates. \"${foo}\" will look for the
|
||||||
|
foo property in the Org-roam node (see the `org-roam-node'). If
|
||||||
|
the property does not exist, the user will be prompted to fill in
|
||||||
|
the string value.
|
||||||
|
|
||||||
|
Org-roam templates are NOT compatible with regular Org capture:
|
||||||
|
they rely on additional hacks and hooks to achieve the
|
||||||
|
streamlined user experience in Org-roam. "
|
||||||
:group 'org-roam
|
:group 'org-roam
|
||||||
:type '(repeat plist) ;; TODO: add :type properly
|
:type
|
||||||
)
|
'(repeat
|
||||||
|
(choice (list :tag "Multikey description"
|
||||||
|
(string :tag "Keys ")
|
||||||
|
(string :tag "Description"))
|
||||||
|
(list :tag "Template entry"
|
||||||
|
(string :tag "Keys ")
|
||||||
|
(string :tag "Description ")
|
||||||
|
(choice :tag "Capture Type " :value entry
|
||||||
|
(const :tag "Org entry" entry)
|
||||||
|
(const :tag "Plain list item" item)
|
||||||
|
(const :tag "Checkbox item" checkitem)
|
||||||
|
(const :tag "Plain text" plain)
|
||||||
|
(const :tag "Table line" table-line))
|
||||||
|
(choice :tag "Template "
|
||||||
|
(string)
|
||||||
|
(list :tag "File"
|
||||||
|
(const :format "" file)
|
||||||
|
(file :tag "Template file"))
|
||||||
|
(list :tag "Function"
|
||||||
|
(const :format "" function)
|
||||||
|
(function :tag "Template function")))
|
||||||
|
(plist :inline t
|
||||||
|
;; Give the most common options as checkboxes
|
||||||
|
:options (((const :format "%v " :if-new)
|
||||||
|
(choice :tag "Node location"
|
||||||
|
(list :tag "File"
|
||||||
|
(const :format "" file)
|
||||||
|
(string :tag " File"))
|
||||||
|
(list :tag "File & Head Content"
|
||||||
|
(const :format "" file+head)
|
||||||
|
(string :tag " File")
|
||||||
|
(string :tag " Head Content"))
|
||||||
|
(list :tag "File & Outline path"
|
||||||
|
(const :format "" file+olp)
|
||||||
|
(string :tag " File")
|
||||||
|
(list :tag "Outline path"
|
||||||
|
(repeat string :tag "Headline")))
|
||||||
|
(list :tag "File & Head Content & Outline path"
|
||||||
|
(const :format "" file+head+olp)
|
||||||
|
(string :tag " File")
|
||||||
|
(string :tag " Head Content")
|
||||||
|
(list :tag "Outline path"
|
||||||
|
(repeat string :tag "Headline")))))
|
||||||
|
((const :format "%v " :prepend) (const t))
|
||||||
|
((const :format "%v " :immediate-finish) (const t))
|
||||||
|
((const :format "%v " :jump-to-captured) (const t))
|
||||||
|
((const :format "%v " :empty-lines) (const 1))
|
||||||
|
((const :format "%v " :empty-lines-before) (const 1))
|
||||||
|
((const :format "%v " :empty-lines-after) (const 1))
|
||||||
|
((const :format "%v " :clock-in) (const t))
|
||||||
|
((const :format "%v " :clock-keep) (const t))
|
||||||
|
((const :format "%v " :clock-resume) (const t))
|
||||||
|
((const :format "%v " :time-prompt) (const t))
|
||||||
|
((const :format "%v " :tree-type) (const week))
|
||||||
|
((const :format "%v " :unnarrowed) (const t))
|
||||||
|
((const :format "%v " :table-line-pos) (string))
|
||||||
|
((const :format "%v " :kill-buffer) (const t))))))))
|
||||||
|
|
||||||
(defcustom org-roam-capture-ref-templates
|
(defcustom org-roam-capture-ref-templates
|
||||||
'(("r" "ref" plain "%?"
|
'(("r" "ref" plain "%?"
|
||||||
@ -72,10 +335,66 @@ TODO: Document this"
|
|||||||
"#+title: ${title}")
|
"#+title: ${title}")
|
||||||
:unnarrowed t))
|
:unnarrowed t))
|
||||||
"The Org-roam templates used during a capture from the roam-ref protocol.
|
"The Org-roam templates used during a capture from the roam-ref protocol.
|
||||||
Details on how to specify for the template is given in `org-roam-capture-templates'."
|
See `org-roam-capture-templates' for the template documentation."
|
||||||
:group 'org-roam
|
:group 'org-roam
|
||||||
:type '(repeat plist) ;; TODO: add :type properly
|
:type
|
||||||
)
|
'(repeat
|
||||||
|
(choice (list :tag "Multikey description"
|
||||||
|
(string :tag "Keys ")
|
||||||
|
(string :tag "Description"))
|
||||||
|
(list :tag "Template entry"
|
||||||
|
(string :tag "Keys ")
|
||||||
|
(string :tag "Description ")
|
||||||
|
(choice :tag "Capture Type " :value entry
|
||||||
|
(const :tag "Org entry" entry)
|
||||||
|
(const :tag "Plain list item" item)
|
||||||
|
(const :tag "Checkbox item" checkitem)
|
||||||
|
(const :tag "Plain text" plain)
|
||||||
|
(const :tag "Table line" table-line))
|
||||||
|
(choice :tag "Template "
|
||||||
|
(string)
|
||||||
|
(list :tag "File"
|
||||||
|
(const :format "" file)
|
||||||
|
(file :tag "Template file"))
|
||||||
|
(list :tag "Function"
|
||||||
|
(const :format "" function)
|
||||||
|
(function :tag "Template function")))
|
||||||
|
(plist :inline t
|
||||||
|
;; Give the most common options as checkboxes
|
||||||
|
:options (((const :format "%v " :if-new)
|
||||||
|
(choice :tag "Node location"
|
||||||
|
(list :tag "File"
|
||||||
|
(const :format "" file)
|
||||||
|
(string :tag " File"))
|
||||||
|
(list :tag "File & Head Content"
|
||||||
|
(const :format "" file+head)
|
||||||
|
(string :tag " File")
|
||||||
|
(string :tag " Head Content"))
|
||||||
|
(list :tag "File & Outline path"
|
||||||
|
(const :format "" file+olp)
|
||||||
|
(string :tag " File")
|
||||||
|
(list :tag "Outline path"
|
||||||
|
(repeat string :tag "Headline")))
|
||||||
|
(list :tag "File & Head Content & Outline path"
|
||||||
|
(const :format "" file+head+olp)
|
||||||
|
(string :tag " File")
|
||||||
|
(string :tag " Head Content")
|
||||||
|
(list :tag "Outline path"
|
||||||
|
(repeat string :tag "Headline")))))
|
||||||
|
((const :format "%v " :prepend) (const t))
|
||||||
|
((const :format "%v " :immediate-finish) (const t))
|
||||||
|
((const :format "%v " :jump-to-captured) (const t))
|
||||||
|
((const :format "%v " :empty-lines) (const 1))
|
||||||
|
((const :format "%v " :empty-lines-before) (const 1))
|
||||||
|
((const :format "%v " :empty-lines-after) (const 1))
|
||||||
|
((const :format "%v " :clock-in) (const t))
|
||||||
|
((const :format "%v " :clock-keep) (const t))
|
||||||
|
((const :format "%v " :clock-resume) (const t))
|
||||||
|
((const :format "%v " :time-prompt) (const t))
|
||||||
|
((const :format "%v " :tree-type) (const week))
|
||||||
|
((const :format "%v " :unnarrowed) (const t))
|
||||||
|
((const :format "%v " :table-line-pos) (string))
|
||||||
|
((const :format "%v " :kill-buffer) (const t))))))))
|
||||||
|
|
||||||
(defun org-roam-capture-p ()
|
(defun org-roam-capture-p ()
|
||||||
"Return t if the current capture process is an Org-roam capture.
|
"Return t if the current capture process is an Org-roam capture.
|
||||||
@ -323,6 +642,8 @@ This function is used solely in Org-roam's capture templates: see
|
|||||||
PROPS is a plist containing additional Org-roam specific
|
PROPS is a plist containing additional Org-roam specific
|
||||||
properties to be added to the template."
|
properties to be added to the template."
|
||||||
(pcase template
|
(pcase template
|
||||||
|
(`(,key ,desc)
|
||||||
|
template)
|
||||||
(`(,key ,desc ,type ,body . ,rest)
|
(`(,key ,desc ,type ,body . ,rest)
|
||||||
(setq rest (append rest props))
|
(setq rest (append rest props))
|
||||||
(let (org-roam-plist options)
|
(let (org-roam-plist options)
|
||||||
|
|||||||
@ -65,10 +65,67 @@
|
|||||||
"* %?"
|
"* %?"
|
||||||
:if-new `(file+head ,(concat org-roam-dailies-directory "%<%Y-%m-%d>.org")
|
:if-new `(file+head ,(concat org-roam-dailies-directory "%<%Y-%m-%d>.org")
|
||||||
"#+title: %<%Y-%m-%d>\n")))
|
"#+title: %<%Y-%m-%d>\n")))
|
||||||
"Capture templates for daily-notes in Org-roam."
|
"Capture templates for daily-notes in Org-roam.
|
||||||
|
See `org-roam-capture-templates' for the template documentation."
|
||||||
:group 'org-roam
|
:group 'org-roam
|
||||||
:type
|
:type
|
||||||
'(repeat plist))
|
'(repeat
|
||||||
|
(choice (list :tag "Multikey description"
|
||||||
|
(string :tag "Keys ")
|
||||||
|
(string :tag "Description"))
|
||||||
|
(list :tag "Template entry"
|
||||||
|
(string :tag "Keys ")
|
||||||
|
(string :tag "Description ")
|
||||||
|
(choice :tag "Capture Type " :value entry
|
||||||
|
(const :tag "Org entry" entry)
|
||||||
|
(const :tag "Plain list item" item)
|
||||||
|
(const :tag "Checkbox item" checkitem)
|
||||||
|
(const :tag "Plain text" plain)
|
||||||
|
(const :tag "Table line" table-line))
|
||||||
|
(choice :tag "Template "
|
||||||
|
(string)
|
||||||
|
(list :tag "File"
|
||||||
|
(const :format "" file)
|
||||||
|
(file :tag "Template file"))
|
||||||
|
(list :tag "Function"
|
||||||
|
(const :format "" function)
|
||||||
|
(function :tag "Template function")))
|
||||||
|
(plist :inline t
|
||||||
|
;; Give the most common options as checkboxes
|
||||||
|
:options (((const :format "%v " :if-new)
|
||||||
|
(choice :tag "Node location"
|
||||||
|
(list :tag "File"
|
||||||
|
(const :format "" file)
|
||||||
|
(string :tag " File"))
|
||||||
|
(list :tag "File & Head Content"
|
||||||
|
(const :format "" file+head)
|
||||||
|
(string :tag " File")
|
||||||
|
(string :tag " Head Content"))
|
||||||
|
(list :tag "File & Outline path"
|
||||||
|
(const :format "" file+olp)
|
||||||
|
(string :tag " File")
|
||||||
|
(list :tag "Outline path"
|
||||||
|
(repeat string :tag "Headline")))
|
||||||
|
(list :tag "File & Head Content & Outline path"
|
||||||
|
(const :format "" file+head+olp)
|
||||||
|
(string :tag " File")
|
||||||
|
(string :tag " Head Content")
|
||||||
|
(list :tag "Outline path"
|
||||||
|
(repeat string :tag "Headline")))))
|
||||||
|
((const :format "%v " :prepend) (const t))
|
||||||
|
((const :format "%v " :immediate-finish) (const t))
|
||||||
|
((const :format "%v " :jump-to-captured) (const t))
|
||||||
|
((const :format "%v " :empty-lines) (const 1))
|
||||||
|
((const :format "%v " :empty-lines-before) (const 1))
|
||||||
|
((const :format "%v " :empty-lines-after) (const 1))
|
||||||
|
((const :format "%v " :clock-in) (const t))
|
||||||
|
((const :format "%v " :clock-keep) (const t))
|
||||||
|
((const :format "%v " :clock-resume) (const t))
|
||||||
|
((const :format "%v " :time-prompt) (const t))
|
||||||
|
((const :format "%v " :tree-type) (const week))
|
||||||
|
((const :format "%v " :unnarrowed) (const t))
|
||||||
|
((const :format "%v " :table-line-pos) (string))
|
||||||
|
((const :format "%v " :kill-buffer) (const t))))))))
|
||||||
|
|
||||||
;;;; Utilities
|
;;;; Utilities
|
||||||
(defun org-roam-dailies-directory--get-absolute-path ()
|
(defun org-roam-dailies-directory--get-absolute-path ()
|
||||||
|
|||||||
Reference in New Issue
Block a user