9.1.3.1 Template elements
Now lets look at the elements of a template definition. Each entry in
org-capture-templates 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 key must be sequential
in the list and preceded by a 2-element entry explaining the
prefix key, for example
("b" "Templates for marking stuff to buy")
If you do not define a template for the C key, this key will
be used to open the customize buffer for this complex variable.
- description
- A short string describing the template, which will be shown during
selection.
- type
- The type of entry, a symbol. Valid values are:
entry- An Org mode node, with a headline. Will be filed as the child of the target
entry or as a top-level entry. The target file should be an Org mode file.
item- A plain list item, placed in the first plain list at the target
location. Again the target file should be an Org file.
checkitem- A checkbox item. This only differs from the plain list item by the
default template.
table-line- a new line in the first table at the target location. Where exactly the
line will be inserted depends on the properties
:prepend and
:table-line-pos (see below).
plain- Text to be inserted as it is.
- target
- Specification of where the captured item should be placed. In Org mode
files, targets usually define a node. Entries will become children of this
node. Other types will be added to the table or list in the body of this
node. Most target specifications contain a file name. If that file name is
the empty string, it defaults to
org-default-notes-file. A file can
also be given as a variable, function, or Emacs Lisp form.
Valid values are:
(file "path/to/file")- Text will be placed at the beginning or end of that file.
(id "id of existing org entry")- Filing as child of this entry, or in the body of the entry.
(file+headline "path/to/file" "node headline")- Fast configuration if the target heading is unique in the file.
(file+olp "path/to/file" "Level 1 heading" "Level 2" ...)- For non-unique headings, the full path is safer.
(file+regexp "path/to/file" "regexp to find location")- Use a regular expression to position the cursor.
(file+datetree "path/to/file")- Will create a heading in a date tree for today's date.
(file+datetree+prompt "path/to/file")- Will create a heading in a date tree, but will prompt for the date.
(file+function "path/to/file" function-finding-location)- A function to find the right location in the file.
(clock)- File to the entry that is currently being clocked.
(function function-finding-location)- Most general way, write your own function to find both
file and location.
- template
- The template for creating the capture item. If you leave this empty, an
appropriate default template will be used. Otherwise this is a string with
escape codes, which will be replaced depending on time and context of the
capture call. The string with escapes may be loaded from a template file,
using the special syntax
(file "path/to/template"). See below for
more details.
- properties
- The rest of the entry is a property list of additional options.
Recognized properties are:
:prepend- Normally new 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.
:empty-lines- Set this to the number of lines to insert
before and after the new item. Default 0, only common other value is 1.
:clock-in- Start the clock in this item.
:clock-keep- Keep the clock running when filing the captured entry.
:clock-resume- If starting the capture interrupted a clock, restart that clock when finished
with 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.
:unnarrowed- Do not narrow the target buffer, simply show the full buffer. Default is to
narrow it so that you only see the new material.
: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 when capture was invoked, kill the
buffer again after capture is completed.